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 30 39 20 32 30 30 38 2f 31 n,v 1.409 2008/1
05f0: 31 2f 30 37 20 30 30 3a 30 36 3a 31 38 20 64 72 1/07 00:06:18 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 34 22 0a 23 64 65 "3.6.4".#de
1020: 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 fine SQLITE_VERS
1030: 49 4f 4e 5f 4e 55 4d 42 45 52 20 20 33 30 30 36 ION_NUMBER 3006
1040: 30 30 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 004../*.** CAPI3
1050: 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 REF: Run-Time Li
1060: 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 brary Version Nu
1070: 6d 62 65 72 73 20 7b 48 31 30 30 32 30 7d 20 3c mbers {H10020} <
1080: 53 36 30 31 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f S60100>.** KEYWO
1090: 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 RDS: sqlite3_ver
10a0: 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 sion.**.** These
10b0: 20 66 65 61 74 75 72 65 73 20 70 72 6f 76 69 64 features provid
10c0: 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 e the same infor
10d0: 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 mation as the [S
10e0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a QLITE_VERSION].*
10f0: 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 56 45 * and [SQLITE_VE
1100: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 23 64 RSION_NUMBER] #d
1110: 65 66 69 6e 65 73 20 69 6e 20 74 68 65 20 68 65 efines in the he
1120: 61 64 65 72 2c 20 62 75 74 20 61 72 65 20 61 73 ader, but are as
1130: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 sociated.** with
1140: 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 the library ins
1150: 74 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 tead of the head
1160: 65 72 20 66 69 6c 65 2e 20 20 43 61 75 74 69 6f er file. Cautio
1170: 75 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d us programmers m
1180: 69 67 68 74 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 ight.** include
1190: 61 20 63 68 65 63 6b 20 69 6e 20 74 68 65 69 72 a check in their
11a0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 application to
11b0: 76 65 72 69 66 79 20 74 68 61 74 0a 2a 2a 20 73 verify that.** s
11c0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
11d0: 6e 5f 6e 75 6d 62 65 72 28 29 20 61 6c 77 61 79 n_number() alway
11e0: 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 s returns the va
11f0: 6c 75 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 lue.** [SQLITE_V
1200: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a ERSION_NUMBER]..
1210: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
1220: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 3_libversion() f
1230: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
1240: 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 the same informa
1250: 74 69 6f 6e 20 61 73 20 69 73 0a 2a 2a 20 69 6e tion as is.** in
1260: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 the sqlite3_ver
1270: 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f sion[] string co
1280: 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 66 75 6e nstant. The fun
1290: 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 ction is provide
12a0: 64 0a 2a 2a 20 66 6f 72 20 75 73 65 20 69 6e 20 d.** for use in
12b0: 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 DLLs since DLL u
12c0: 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 sers usually do
12d0: 6e 6f 74 20 68 61 76 65 20 64 69 72 65 63 74 20 not have direct
12e0: 61 63 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 access to string
12f0: 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 .** constants wi
1300: 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 0a 2a 2a thin the DLL..**
1310: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
1320: 2a 2a 0a 2a 2a 20 7b 48 31 30 30 32 31 7d 20 54 **.** {H10021} T
1330: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 he [sqlite3_libv
1340: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d ersion_number()]
1350: 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c interface shall
1360: 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 return.**
1370: 20 20 20 20 61 6e 20 69 6e 74 65 67 65 72 20 65 an integer e
1380: 71 75 61 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f qual to [SQLITE_
1390: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e VERSION_NUMBER].
13a0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 32 32 7d 20 .**.** {H10022}
13b0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 65 72 The [sqlite3_ver
13c0: 73 69 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e sion] string con
13d0: 73 74 61 6e 74 20 73 68 61 6c 6c 20 63 6f 6e 74 stant shall cont
13e0: 61 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ain.**
13f0: 74 68 65 20 74 65 78 74 20 6f 66 20 74 68 65 20 the text of the
1400: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d [SQLITE_VERSION]
1410: 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b string..**.** {
1420: 48 31 30 30 32 33 7d 20 54 68 65 20 5b 73 71 6c H10023} The [sql
1430: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 ite3_libversion(
1440: 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c )] function shal
1450: 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 l return.**
1460: 20 20 20 20 20 61 20 70 6f 69 6e 74 65 72 20 74 a pointer t
1470: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 o the [sqlite3_v
1480: 65 72 73 69 6f 6e 5d 20 73 74 72 69 6e 67 20 63 ersion] string c
1490: 6f 6e 73 74 61 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 onstant..*/.SQLI
14a0: 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 TE_EXTERN const
14b0: 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 char sqlite3_ver
14c0: 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 sion[];.const ch
14d0: 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 ar *sqlite3_libv
14e0: 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 69 6e ersion(void);.in
14f0: 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 t sqlite3_libver
1500: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 sion_number(void
1510: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1520: 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 EF: Test To See
1530: 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 If The Library I
1540: 73 20 54 68 72 65 61 64 73 61 66 65 20 7b 48 31 s Threadsafe {H1
1550: 30 31 30 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 0100} <S60100>.*
1560: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 *.** SQLite can
1570: 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 be compiled with
1580: 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 or without mute
1590: 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 xes. When.** th
15a0: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
15b0: 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 SAFE] C preproce
15c0: 73 73 6f 72 20 6d 61 63 72 6f 20 31 20 6f 72 20 ssor macro 1 or
15d0: 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 2, mutexes.** ar
15e0: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 e enabled and SQ
15f0: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61 Lite is threadsa
1600: 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a fe. When the.**
1610: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
1620: 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c AFE] macro is 0,
1630: 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 .** the mutexes
1640: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 are omitted. W
1650: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 ithout the mutex
1660: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 es, it is not sa
1670: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c fe.** to use SQL
1680: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 ite concurrently
1690: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 from more than
16a0: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a one thread..**.*
16b0: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 * Enabling mutex
16c0: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 es incurs a meas
16d0: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e urable performan
16e0: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 ce penalty..** S
16f0: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 o if speed is of
1700: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e utmost importan
1710: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e ce, it makes sen
1720: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a se to disable.**
1730: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 the mutexes. B
1740: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 ut for maximum s
1750: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 afety, mutexes s
1760: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 hould be enabled
1770: 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 ..** The default
1780: 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 behavior is for
1790: 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 mutexes to be e
17a0: 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 nabled..**.** Th
17b0: 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e is interface can
17c0: 20 62 65 20 75 73 65 64 20 62 79 20 61 20 70 72 be used by a pr
17d0: 6f 67 72 61 6d 20 74 6f 20 6d 61 6b 65 20 73 75 ogram to make su
17e0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 re that the.** v
17f0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 ersion of SQLite
1800: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b that it is link
1810: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 ing against was
1820: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
1830: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 the desired set
1840: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c ting of the [SQL
1850: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 ITE_THREADSAFE]
1860: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 macro..**.** Thi
1870: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 s interface only
1880: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 reports on the
1890: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 compile-time mut
18a0: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 ex setting.** of
18b0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
18c0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 EADSAFE] flag.
18d0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
18e0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 piled with.** SQ
18f0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
1900: 31 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61 1 then mutexes a
1910: 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 re enabled by de
1920: 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e fault but.** can
1930: 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 be fully or par
1940: 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 tially disabled
1950: 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 using a call to
1960: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
1970: 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 )].** with the v
1980: 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e erbs [SQLITE_CON
1990: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 FIG_SINGLETHREAD
19a0: 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ], [SQLITE_CONFI
19b0: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a G_MULTITHREAD],.
19c0: 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f ** or [SQLITE_CO
19d0: 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 54 68 NFIG_MUTEX]. Th
19e0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f e return value o
19f0: 66 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 f this function
1a00: 73 68 6f 77 73 0a 2a 2a 20 6f 6e 6c 79 20 74 68 shows.** only th
1a10: 65 20 64 65 66 61 75 6c 74 20 63 6f 6d 70 69 6c e default compil
1a20: 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 2c 20 e-time setting,
1a30: 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 not any run-time
1a40: 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 74 changes.** to t
1a50: 68 61 74 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a hat setting..**.
1a60: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 ** See the [thre
1a70: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 ading mode] docu
1a80: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 mentation for ad
1a90: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 ditional informa
1aa0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 tion..**.** INVA
1ab0: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 RIANTS:.**.** {H
1ac0: 31 30 31 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 10101} The [sqli
1ad0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 te3_threadsafe()
1ae0: 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c ] function shall
1af0: 20 72 65 74 75 72 6e 20 7a 65 72 6f 20 69 66 0a return zero if.
1b00: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 ** and
1b10: 6f 6e 6c 79 20 69 66 20 53 51 4c 69 74 65 20 77 only if SQLite w
1b20: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 as compiled with
1b30: 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f mutexing code o
1b40: 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 mitted..**.** {H
1b50: 31 30 31 30 32 7d 20 54 68 65 20 76 61 6c 75 65 10102} The value
1b60: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 returned by the
1b70: 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 [sqlite3_thread
1b80: 73 61 66 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e safe()] function
1b90: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 .** sha
1ba0: 6c 6c 20 72 65 6d 61 69 6e 20 74 68 65 20 73 61 ll remain the sa
1bb0: 6d 65 20 61 63 72 6f 73 73 20 63 61 6c 6c 73 20 me across calls
1bc0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 to [sqlite3_conf
1bd0: 69 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ig()]..*/.int sq
1be0: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 lite3_threadsafe
1bf0: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 (void);../*.** C
1c00: 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 API3REF: Databas
1c10: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e e Connection Han
1c20: 64 6c 65 20 7b 48 31 32 30 30 30 7d 20 3c 53 34 dle {H12000} <S4
1c30: 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 0200>.** KEYWORD
1c40: 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e S: {database con
1c50: 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 nection} {databa
1c60: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a se connections}.
1c70: 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 **.** Each open
1c80: 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 SQLite database
1c90: 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 is represented b
1ca0: 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 y a pointer to a
1cb0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a n instance of.**
1cc0: 20 74 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 the opaque stru
1cd0: 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c cture named "sql
1ce0: 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 ite3". It is us
1cf0: 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 eful to think of
1d00: 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 an sqlite3.** p
1d10: 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a ointer as an obj
1d20: 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 ect. The [sqlit
1d30: 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c e3_open()], [sql
1d40: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 ite3_open16()],
1d50: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
1d60: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 open_v2()] inter
1d70: 66 61 63 65 73 20 61 72 65 20 69 74 73 20 63 6f faces are its co
1d80: 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 nstructors, and
1d90: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 [sqlite3_close()
1da0: 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64 65 73 74 ].** is its dest
1db0: 72 75 63 74 6f 72 2e 20 20 54 68 65 72 65 20 61 ructor. There a
1dc0: 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e re many other in
1dd0: 74 65 72 66 61 63 65 73 20 28 73 75 63 68 20 61 terfaces (such a
1de0: 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 s.** [sqlite3_pr
1df0: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 epare_v2()], [sq
1e00: 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
1e10: 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a ction()], and.**
1e20: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 [sqlite3_busy_t
1e30: 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d imeout()] to nam
1e40: 65 20 62 75 74 20 74 68 72 65 65 29 20 74 68 61 e but three) tha
1e50: 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e t are methods on
1e60: 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f an.** sqlite3 o
1e70: 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 bject..*/.typede
1e80: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
1e90: 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a sqlite3;../*.**
1ea0: 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 CAPI3REF: 64-Bi
1eb0: 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 20 t Integer Types
1ec0: 7b 48 31 30 32 30 30 7d 20 3c 53 31 30 31 31 30 {H10200} <S10110
1ed0: 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 >.** KEYWORDS: s
1ee0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 qlite_int64 sqli
1ef0: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 te_uint64.**.**
1f00: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73 Because there is
1f10: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f no cross-platfo
1f20: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 rm way to specif
1f30: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 y 64-bit integer
1f40: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 types.** SQLite
1f50: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 includes typede
1f60: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 fs for 64-bit si
1f70: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 gned and unsigne
1f80: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a d integers..**.*
1f90: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e * The sqlite3_in
1fa0: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f t64 and sqlite3_
1fb0: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 uint64 are the p
1fc0: 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65 referred type de
1fd0: 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 finitions..** Th
1fe0: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 e sqlite_int64 a
1ff0: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 nd sqlite_uint64
2000: 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f types are suppo
2010: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 rted for backwar
2020: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c ds.** compatibil
2030: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 ity only..**.**
2040: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
2050: 2a 20 7b 48 31 30 32 30 31 7d 20 54 68 65 20 5b * {H10201} The [
2060: 73 71 6c 69 74 65 5f 69 6e 74 36 34 5d 20 61 6e sqlite_int64] an
2070: 64 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 d [sqlite3_int64
2080: 5d 20 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65 ] type shall spe
2090: 63 69 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 cify.**
20a0: 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 a 64-bit signed
20b0: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 integer..**.**
20c0: 7b 48 31 30 32 30 32 7d 20 54 68 65 20 5b 73 71 {H10202} The [sq
20d0: 6c 69 74 65 5f 75 69 6e 74 36 34 5d 20 61 6e 64 lite_uint64] and
20e0: 20 5b 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 [sqlite3_uint64
20f0: 5d 20 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65 ] type shall spe
2100: 63 69 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 cify.**
2110: 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e a 64-bit unsign
2120: 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2f 0a 23 ed integer..*/.#
2130: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 ifdef SQLITE_INT
2140: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 64_TYPE. typede
2150: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 f SQLITE_INT64_T
2160: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 YPE sqlite_int64
2170: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 ;. typedef unsi
2180: 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 gned SQLITE_INT6
2190: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 4_TYPE sqlite_ui
21a0: 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 nt64;.#elif defi
21b0: 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c ned(_MSC_VER) ||
21c0: 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 defined(__BORLA
21d0: 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 NDC__). typedef
21e0: 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f __int64 sqlite_
21f0: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 int64;. typedef
2200: 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 unsigned __int6
2210: 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 4 sqlite_uint64;
2220: 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 .#else. typedef
2230: 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 long long int s
2240: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 qlite_int64;. t
2250: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 ypedef unsigned
2260: 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 long long int sq
2270: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e lite_uint64;.#en
2280: 64 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 dif.typedef sqli
2290: 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 te_int64 sqlite3
22a0: 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 _int64;.typedef
22b0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 sqlite_uint64 sq
22c0: 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f lite3_uint64;../
22d0: 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e *.** If compilin
22e0: 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f g for a processo
22f0: 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f r that lacks flo
2300: 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 ating point supp
2310: 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 ort,.** substitu
2320: 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 te integer for f
2330: 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a loating-point..*
2340: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f /.#ifdef SQLITE_
2350: 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f OMIT_FLOATING_PO
2360: 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 INT.# define dou
2370: 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 ble sqlite3_int6
2380: 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4.#endif../*.**
2390: 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e CAPI3REF: Closin
23a0: 67 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e g A Database Con
23b0: 6e 65 63 74 69 6f 6e 20 7b 48 31 32 30 31 30 7d nection {H12010}
23c0: 20 3c 53 33 30 31 30 30 3e 3c 53 34 30 32 30 30 <S30100><S40200
23d0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 >.**.** This rou
23e0: 74 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 tine is the dest
23f0: 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b ructor for the [
2400: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e sqlite3] object.
2410: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 .**.** Applicati
2420: 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 ons should [sqli
2430: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 te3_finalize | f
2440: 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 inalize] all [pr
2450: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2460: 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 s].** and [sqlit
2470: 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 e3_blob_close |
2480: 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 close] all [BLOB
2490: 20 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 handles] associ
24a0: 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 ated with.** the
24b0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 [sqlite3] objec
24c0: 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d t prior to attem
24d0: 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 pting to close t
24e0: 68 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 he object..** Th
24f0: 65 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f e [sqlite3_next_
2500: 73 74 6d 74 28 29 5d 20 69 6e 74 65 72 66 61 63 stmt()] interfac
2510: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f e can be used to
2520: 20 6c 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a 20 5b locate all.** [
2530: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2540: 6e 74 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20 nts] associated
2550: 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 with a [database
2560: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 66 20 connection] if
2570: 64 65 73 69 72 65 64 2e 0a 2a 2a 20 54 79 70 69 desired..** Typi
2580: 63 61 6c 20 63 6f 64 65 20 6d 69 67 68 74 20 6c cal code might l
2590: 6f 6f 6b 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a ook like this:.*
25a0: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
25b0: 3e 3c 70 72 65 3e 0a 2a 2a 20 73 71 6c 69 74 65 ><pre>.** sqlite
25c0: 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 3b 0a 2a 3_stmt *pStmt;.*
25d0: 2a 20 77 68 69 6c 65 28 20 28 70 53 74 6d 74 20 * while( (pStmt
25e0: 3d 20 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 = sqlite3_next_s
25f0: 74 6d 74 28 64 62 2c 20 30 29 29 21 3d 30 20 29 tmt(db, 0))!=0 )
2600: 7b 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 73 71 {.** sq
2610: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 70 lite3_finalize(p
2620: 53 74 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c Stmt);.** }.** <
2630: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
2640: 65 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73 71 6c e>.**.** If [sql
2650: 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 ite3_close()] is
2660: 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 invoked while a
2670: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 transaction is
2680: 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 open,.** the tra
2690: 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f nsaction is auto
26a0: 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 matically rolled
26b0: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 back..**.** INV
26c0: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
26d0: 48 31 32 30 31 31 7d 20 41 20 73 75 63 63 65 73 H12011} A succes
26e0: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 sful call to [sq
26f0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 lite3_close(C)]
2700: 73 68 61 6c 6c 20 64 65 73 74 72 6f 79 20 74 68 shall destroy th
2710: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 e.** [d
2720: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2730: 6f 6e 5d 20 6f 62 6a 65 63 74 20 43 2e 0a 2a 2a on] object C..**
2740: 0a 2a 2a 20 7b 48 31 32 30 31 32 7d 20 41 20 73 .** {H12012} A s
2750: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 uccessful call t
2760: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 o [sqlite3_close
2770: 28 43 29 5d 20 73 68 61 6c 6c 20 72 65 74 75 72 (C)] shall retur
2780: 6e 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a n SQLITE_OK..**.
2790: 2a 2a 20 7b 48 31 32 30 31 33 7d 20 41 20 73 75 ** {H12013} A su
27a0: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f ccessful call to
27b0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 [sqlite3_close(
27c0: 43 29 5d 20 73 68 61 6c 6c 20 72 65 6c 65 61 73 C)] shall releas
27d0: 65 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 e all.**
27e0: 20 20 6d 65 6d 6f 72 79 20 61 6e 64 20 73 79 73 memory and sys
27f0: 74 65 6d 20 72 65 73 6f 75 72 63 65 73 20 61 73 tem resources as
2800: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 5b 64 sociated with [d
2810: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2820: 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 on].**
2830: 43 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 34 C..**.** {H12014
2840: 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c } A call to [sql
2850: 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6f ite3_close(C)] o
2860: 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f n a [database co
2870: 6e 6e 65 63 74 69 6f 6e 5d 20 43 20 74 68 61 74 nnection] C that
2880: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61 73 .** has
2890: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 70 65 one or more ope
28a0: 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 n [prepared stat
28b0: 65 6d 65 6e 74 73 5d 20 73 68 61 6c 6c 20 66 61 ements] shall fa
28c0: 69 6c 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 il with.**
28d0: 20 20 20 20 61 6e 20 5b 53 51 4c 49 54 45 5f 42 an [SQLITE_B
28e0: 55 53 59 5d 20 65 72 72 6f 72 20 63 6f 64 65 2e USY] error code.
28f0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 35 7d 20 .**.** {H12015}
2900: 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 A call to [sqlit
2910: 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 77 68 65 e3_close(C)] whe
2920: 72 65 20 43 20 69 73 20 61 20 4e 55 4c 4c 20 70 re C is a NULL p
2930: 6f 69 6e 74 65 72 20 73 68 61 6c 6c 0a 2a 2a 20 ointer shall.**
2940: 20 20 20 20 20 20 20 20 20 62 65 20 61 20 68 61 be a ha
2950: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 20 72 65 74 rmless no-op ret
2960: 75 72 6e 69 6e 67 20 53 51 4c 49 54 45 5f 4f 4b urning SQLITE_OK
2970: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 39 7d ..**.** {H12019}
2980: 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 63 When [sqlite3_c
2990: 6c 6f 73 65 28 43 29 5d 20 69 73 20 69 6e 76 6f lose(C)] is invo
29a0: 6b 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 ked on a [databa
29b0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 43 se connection] C
29c0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 .** tha
29d0: 74 20 68 61 73 20 61 20 70 65 6e 64 69 6e 67 20 t has a pending
29e0: 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 transaction, the
29f0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 73 68 61 transaction sha
2a00: 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 20 20 20 20 ll be.**
2a10: 20 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a rolled back..*
2a20: 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 *.** ASSUMPTIONS
2a30: 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 30 31 36 7d :.**.** {A12016}
2a40: 20 54 68 65 20 43 20 70 61 72 61 6d 65 74 65 72 The C parameter
2a50: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f to [sqlite3_clo
2a60: 73 65 28 43 29 5d 20 6d 75 73 74 20 62 65 20 65 se(C)] must be e
2a70: 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 ither a NULL.**
2a80: 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 pointer
2a90: 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d or an [sqlite3]
2aa0: 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 object pointer
2ab0: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 20 20 20 20 obtained.**
2ac0: 20 20 20 20 20 66 72 6f 6d 20 5b 73 71 6c 69 74 from [sqlit
2ad0: 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c e3_open()], [sql
2ae0: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 ite3_open16()],
2af0: 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b or.** [
2b00: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
2b10: 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 )], and not prev
2b20: 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a iously closed..*
2b30: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c /.int sqlite3_cl
2b40: 6f 73 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a ose(sqlite3 *);.
2b50: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 ./*.** The type
2b60: 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 for a callback f
2b70: 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 unction..** This
2b80: 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 is legacy and d
2b90: 65 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 eprecated. It i
2ba0: 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 s included for h
2bb0: 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d istorical.** com
2bc0: 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 patibility and i
2bd0: 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 s not documented
2be0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 ..*/.typedef int
2bf0: 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 (*sqlite3_callb
2c00: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 ack)(void*,int,c
2c10: 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a har**, char**);.
2c20: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2c30: 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 One-Step Query
2c40: 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 Execution Interf
2c50: 61 63 65 20 7b 48 31 32 31 30 30 7d 20 3c 53 31 ace {H12100} <S1
2c60: 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 0000>.**.** The
2c70: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 sqlite3_exec() i
2c80: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f nterface is a co
2c90: 6e 76 65 6e 69 65 6e 74 20 77 61 79 20 6f 66 20 nvenient way of
2ca0: 72 75 6e 6e 69 6e 67 20 6f 6e 65 20 6f 72 20 6d running one or m
2cb0: 6f 72 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 ore.** SQL state
2cc0: 6d 65 6e 74 73 20 77 69 74 68 6f 75 74 20 68 61 ments without ha
2cd0: 76 69 6e 67 20 74 6f 20 77 72 69 74 65 20 61 20 ving to write a
2ce0: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 20 lot of C code.
2cf0: 54 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 The UTF-8 encode
2d00: 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 d.** SQL stateme
2d10: 6e 74 73 20 61 72 65 20 70 61 73 73 65 64 20 69 nts are passed i
2d20: 6e 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 n as the second
2d30: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
2d40: 69 74 65 33 5f 65 78 65 63 28 29 2e 0a 2a 2a 20 ite3_exec()..**
2d50: 54 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 61 The statements a
2d60: 72 65 20 65 76 61 6c 75 61 74 65 64 20 6f 6e 65 re evaluated one
2d70: 20 62 79 20 6f 6e 65 20 75 6e 74 69 6c 20 65 69 by one until ei
2d80: 74 68 65 72 20 61 6e 20 65 72 72 6f 72 20 6f 72 ther an error or
2d90: 0a 2a 2a 20 61 6e 20 69 6e 74 65 72 72 75 70 74 .** an interrupt
2da0: 20 69 73 20 65 6e 63 6f 75 6e 74 65 72 65 64 2c is encountered,
2db0: 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 79 20 61 or until they a
2dc0: 72 65 20 61 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 re all done. Th
2dd0: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 0a e 3rd parameter.
2de0: 2a 2a 20 69 73 20 61 6e 20 6f 70 74 69 6f 6e 61 ** is an optiona
2df0: 6c 20 63 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 l callback that
2e00: 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 is invoked once
2e10: 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20 for each row of
2e20: 61 6e 79 20 71 75 65 72 79 0a 2a 2a 20 72 65 73 any query.** res
2e30: 75 6c 74 73 20 70 72 6f 64 75 63 65 64 20 62 79 ults produced by
2e40: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
2e50: 6e 74 73 2e 20 20 54 68 65 20 35 74 68 20 70 61 nts. The 5th pa
2e60: 72 61 6d 65 74 65 72 20 74 65 6c 6c 73 20 77 68 rameter tells wh
2e70: 65 72 65 0a 2a 2a 20 74 6f 20 77 72 69 74 65 20 ere.** to write
2e80: 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 any error messag
2e90: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 72 es..**.** The er
2ea0: 72 6f 72 20 6d 65 73 73 61 67 65 20 70 61 73 73 ror message pass
2eb0: 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 ed back through
2ec0: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 the 5th paramete
2ed0: 72 20 69 73 20 68 65 6c 64 0a 2a 2a 20 69 6e 20 r is held.** in
2ee0: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 memory obtained
2ef0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 from [sqlite3_ma
2f00: 6c 6c 6f 63 28 29 5d 2e 20 20 54 6f 20 61 76 6f lloc()]. To avo
2f10: 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b id a memory leak
2f20: 2c 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 69 6e 67 ,.** the calling
2f30: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f application sho
2f40: 75 6c 64 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 uld call [sqlite
2f50: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 61 6e 79 3_free()] on any
2f60: 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 error.** messag
2f70: 65 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 e returned throu
2f80: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d gh the 5th param
2f90: 65 74 65 72 20 77 68 65 6e 20 69 74 20 68 61 73 eter when it has
2fa0: 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 0a finished using.
2fb0: 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 ** the error mes
2fc0: 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 sage..**.** If t
2fd0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
2fe0: 20 69 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 in the 2nd para
2ff0: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 6f 72 meter is NULL or
3000: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 an empty string
3010: 0a 2a 2a 20 6f 72 20 61 20 73 74 72 69 6e 67 20 .** or a string
3020: 63 6f 6e 74 61 69 6e 69 6e 67 20 6f 6e 6c 79 20 containing only
3030: 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 20 63 whitespace and c
3040: 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f omments, then no
3050: 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e SQL.** statemen
3060: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 ts are evaluated
3070: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 and the databas
3080: 65 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 e is not changed
3090: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
30a0: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 te3_exec() inter
30b0: 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e face is implemen
30c0: 74 65 64 20 69 6e 20 74 65 72 6d 73 20 6f 66 0a ted in terms of.
30d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
30e0: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 are_v2()], [sqli
30f0: 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 te3_step()], and
3100: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
3110: 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 71 ze()]..** The sq
3120: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 72 6f 75 lite3_exec() rou
3130: 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 68 69 6e tine does nothin
3140: 67 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 g to the databas
3150: 65 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 e that cannot be
3160: 20 64 6f 6e 65 0a 2a 2a 20 62 79 20 5b 73 71 6c done.** by [sql
3170: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
3180: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 )], [sqlite3_ste
3190: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 p()], and [sqlit
31a0: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a e3_finalize()]..
31b0: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
31c0: 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 31 7d :.**.** {H12101}
31d0: 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e A successful in
31e0: 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c vocation of [sql
31f0: 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c ite3_exec(D,S,C,
3200: 41 2c 45 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 A,E)].**
3210: 20 20 73 68 61 6c 6c 20 73 65 71 75 65 6e 74 69 shall sequenti
3220: 61 6c 6c 79 20 65 76 61 6c 75 61 74 65 20 61 6c ally evaluate al
3230: 6c 20 6f 66 20 74 68 65 20 55 54 46 2d 38 20 65 l of the UTF-8 e
3240: 6e 63 6f 64 65 64 2c 0a 2a 2a 20 20 20 20 20 20 ncoded,.**
3250: 20 20 20 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 semicolon-se
3260: 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 parated SQL stat
3270: 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 ements in the ze
3280: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ro-terminated.**
3290: 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 string
32a0: 20 53 20 77 69 74 68 69 6e 20 74 68 65 20 63 6f S within the co
32b0: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 ntext of the [da
32c0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
32d0: 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 n] D..**.** {H12
32e0: 31 30 32 7d 20 49 66 20 74 68 65 20 53 20 70 61 102} If the S pa
32f0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
3300: 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 te3_exec(D,S,C,A
3310: 2c 45 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 ,E)] is NULL the
3320: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 n.** th
3330: 65 20 61 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 e actions of the
3340: 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c interface shall
3350: 20 62 65 20 74 68 65 20 73 61 6d 65 20 61 73 20 be the same as
3360: 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 if the.**
3370: 20 20 20 53 20 70 61 72 61 6d 65 74 65 72 20 77 S parameter w
3380: 65 72 65 20 61 6e 20 65 6d 70 74 79 20 73 74 72 ere an empty str
3390: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 ing..**.** {H121
33a0: 30 34 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 04} The return v
33b0: 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 alue of [sqlite3
33c0: 5f 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 62 _exec()] shall b
33d0: 65 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 e [SQLITE_OK] if
33e0: 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 all.**
33f0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
3400: 72 75 6e 20 73 75 63 63 65 73 73 66 75 6c 6c 79 run successfully
3410: 20 61 6e 64 20 74 6f 20 63 6f 6d 70 6c 65 74 69 and to completi
3420: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 on..**.** {H1210
3430: 35 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 5} The return va
3440: 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f lue of [sqlite3_
3450: 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 62 65 exec()] shall be
3460: 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a an appropriate.
3470: 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 6e 2d ** non-
3480: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 zero [error code
3490: 5d 20 69 66 20 61 6e 79 20 53 51 4c 20 73 74 61 ] if any SQL sta
34a0: 74 65 6d 65 6e 74 20 66 61 69 6c 73 2e 0a 2a 2a tement fails..**
34b0: 0a 2a 2a 20 7b 48 31 32 31 30 37 7d 20 49 66 20 .** {H12107} If
34c0: 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 one or more of t
34d0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
34e0: 73 20 68 61 6e 64 65 64 20 74 6f 20 5b 73 71 6c s handed to [sql
34f0: 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 ite3_exec()].**
3500: 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 return
3510: 72 65 73 75 6c 74 73 20 61 6e 64 20 74 68 65 20 results and the
3520: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 3rd parameter is
3530: 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 0a not NULL, then.
3540: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
3550: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
3560: 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 n specified by t
3570: 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 he 3rd parameter
3580: 20 73 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 shall be.**
3590: 20 20 20 20 20 20 69 6e 76 6f 6b 65 64 20 6f 6e invoked on
35a0: 63 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20 ce for each row
35b0: 6f 66 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a of result..**.**
35c0: 20 7b 48 31 32 31 31 30 7d 20 49 66 20 74 68 65 {H12110} If the
35d0: 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
35e0: 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 76 61 6c s a non-zero val
35f0: 75 65 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 ue then [sqlite3
3600: 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20 _exec()].**
3610: 20 20 20 20 20 73 68 61 6c 6c 20 61 62 6f 72 74 shall abort
3620: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
3630: 6e 74 20 69 74 20 69 73 20 63 75 72 72 65 6e 74 nt it is current
3640: 6c 79 20 65 76 61 6c 75 61 74 69 6e 67 2c 0a 2a ly evaluating,.*
3650: 2a 20 20 20 20 20 20 20 20 20 20 73 6b 69 70 20 * skip
3660: 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 53 all subsequent S
3670: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 QL statements, a
3680: 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 nd return [SQLIT
3690: 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 E_ABORT]..**.**
36a0: 7b 48 31 32 31 31 33 7d 20 54 68 65 20 5b 73 71 {H12113} The [sq
36b0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f lite3_exec()] ro
36c0: 75 74 69 6e 65 20 73 68 61 6c 6c 20 70 61 73 73 utine shall pass
36d0: 20 69 74 73 20 34 74 68 20 70 61 72 61 6d 65 74 its 4th paramet
36e0: 65 72 20 74 68 72 6f 75 67 68 0a 2a 2a 20 20 20 er through.**
36f0: 20 20 20 20 20 20 20 61 73 20 74 68 65 20 31 73 as the 1s
3700: 74 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 t parameter of t
3710: 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a he callback..**.
3720: 2a 2a 20 7b 48 31 32 31 31 36 7d 20 54 68 65 20 ** {H12116} The
3730: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
3740: 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 routine shall s
3750: 65 74 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d et the 2nd param
3760: 65 74 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20 eter of its.**
3770: 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b callback
3780: 20 74 6f 20 62 65 20 74 68 65 20 6e 75 6d 62 65 to be the numbe
3790: 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 r of columns in
37a0: 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 the current row
37b0: 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 of.** r
37c0: 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 esult..**.** {H1
37d0: 32 31 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 2119} The [sqlit
37e0: 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 e3_exec()] routi
37f0: 6e 65 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 ne shall set the
3800: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 6f 3rd parameter o
3810: 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 f its.**
3820: 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 callback to be
3830: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 an array of poi
3840: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 nters to strings
3850: 20 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a 20 holding the.**
3860: 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 73 20 values
3870: 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20 for each column
3880: 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 in the current r
3890: 65 73 75 6c 74 20 73 65 74 20 72 6f 77 20 61 73 esult set row as
38a0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 74 .** obt
38b0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 ained from [sqli
38c0: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
38d0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 32 )]..**.** {H1212
38e0: 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 2} The [sqlite3_
38f0: 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 exec()] routine
3900: 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 34 74 shall set the 4t
3910: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 69 h parameter of i
3920: 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 ts.** c
3930: 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 61 6e allback to be an
3940: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 array of pointe
3950: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 68 6f rs to strings ho
3960: 6c 64 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 lding the.**
3970: 20 20 20 20 20 20 6e 61 6d 65 73 20 6f 66 20 72 names of r
3980: 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 61 73 esult columns as
3990: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
39a0: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e sqlite3_column_n
39b0: 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ame()]..**.** {H
39c0: 31 32 31 32 35 7d 20 49 66 20 74 68 65 20 33 72 12125} If the 3r
39d0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b d parameter to [
39e0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 sqlite3_exec()]
39f0: 69 73 20 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a 20 is NULL then.**
3a00: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
3a10: 33 5f 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 3_exec()] shall
3a20: 73 69 6c 65 6e 74 6c 79 20 64 69 73 63 61 72 64 silently discard
3a30: 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 0a query results..
3a40: 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33 31 7d 20 49 **.** {H12131} I
3a50: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 f an error occur
3a60: 73 20 77 68 69 6c 65 20 70 61 72 73 69 6e 67 20 s while parsing
3a70: 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20 61 6e or evaluating an
3a80: 79 20 6f 66 20 74 68 65 20 53 51 4c 0a 2a 2a 20 y of the SQL.**
3a90: 20 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 stateme
3aa0: 6e 74 73 20 69 6e 20 74 68 65 20 53 20 70 61 72 nts in the S par
3ab0: 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 ameter of [sqlit
3ac0: 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c e3_exec(D,S,C,A,
3ad0: 45 29 5d 20 61 6e 64 20 69 66 0a 2a 2a 20 20 20 E)] and if.**
3ae0: 20 20 20 20 20 20 20 74 68 65 20 45 20 70 61 72 the E par
3af0: 61 6d 65 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 ameter is not NU
3b00: 4c 4c 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 LL, then [sqlite
3b10: 33 5f 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 3_exec()] shall
3b20: 73 74 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 store.**
3b30: 20 20 69 6e 20 2a 45 20 61 6e 20 61 70 70 72 6f in *E an appro
3b40: 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 priate error mes
3b50: 73 61 67 65 20 77 72 69 74 74 65 6e 20 69 6e 74 sage written int
3b60: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 o memory obtaine
3b70: 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 d.** fr
3b80: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
3b90: 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 oc()]..**.** {H1
3ba0: 32 31 33 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 2134} The [sqlit
3bb0: 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c e3_exec(D,S,C,A,
3bc0: 45 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c E)] routine shal
3bd0: 6c 20 73 65 74 20 74 68 65 20 76 61 6c 75 65 20 l set the value
3be0: 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 2a of.** *
3bf0: 45 20 74 6f 20 4e 55 4c 4c 20 69 66 20 45 20 69 E to NULL if E i
3c00: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 74 s not NULL and t
3c10: 68 65 72 65 20 61 72 65 20 6e 6f 20 65 72 72 6f here are no erro
3c20: 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33 rs..**.** {H1213
3c30: 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 7} The [sqlite3_
3c40: 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d exec(D,S,C,A,E)]
3c50: 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 function shall
3c60: 73 65 74 20 74 68 65 20 5b 65 72 72 6f 72 20 63 set the [error c
3c70: 6f 64 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 ode].**
3c80: 20 61 6e 64 20 6d 65 73 73 61 67 65 20 61 63 63 and message acc
3c90: 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c essible via [sql
3ca0: 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c ite3_errcode()],
3cb0: 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 .** [s
3cc0: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f qlite3_extended_
3cd0: 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 errcode()],.**
3ce0: 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
3cf0: 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 _errmsg()], and
3d00: 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 [sqlite3_errmsg1
3d10: 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 6()]..**.** {H12
3d20: 31 33 38 7d 20 49 66 20 74 68 65 20 53 20 70 61 138} If the S pa
3d30: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
3d40: 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 te3_exec(D,S,C,A
3d50: 2c 45 29 5d 20 69 73 20 4e 55 4c 4c 20 6f 72 20 ,E)] is NULL or
3d60: 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 an.** e
3d70: 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 63 mpty string or c
3d80: 6f 6e 74 61 69 6e 73 20 6e 6f 74 68 69 6e 67 20 ontains nothing
3d90: 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69 74 65 other than white
3da0: 73 70 61 63 65 2c 20 63 6f 6d 6d 65 6e 74 73 2c space, comments,
3db0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 .** and
3dc0: 2f 6f 72 20 73 65 6d 69 63 6f 6c 6f 6e 73 2c 20 /or semicolons,
3dd0: 74 68 65 6e 20 72 65 73 75 6c 74 73 20 6f 66 20 then results of
3de0: 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 [sqlite3_errcode
3df0: 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 ()],.**
3e00: 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 [sqlite3_extend
3e10: 65 64 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a ed_errcode()],.*
3e20: 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
3e30: 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 te3_errmsg()], a
3e40: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d nd [sqlite3_errm
3e50: 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 sg16()].**
3e60: 20 20 20 20 73 68 61 6c 6c 20 72 65 73 65 74 20 shall reset
3e70: 74 6f 20 69 6e 64 69 63 61 74 65 20 6e 6f 20 65 to indicate no e
3e80: 72 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 rrors..**.** ASS
3e90: 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 UMPTIONS:.**.**
3ea0: 7b 41 31 32 31 34 31 7d 20 54 68 65 20 66 69 72 {A12141} The fir
3eb0: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
3ec0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
3ed0: 20 6d 75 73 74 20 62 65 20 61 6e 20 76 61 6c 69 must be an vali
3ee0: 64 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20 20 20 d and open.**
3ef0: 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 [database
3f00: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a connection]..**
3f10: 0a 2a 2a 20 7b 41 31 32 31 34 32 7d 20 54 68 65 .** {A12142} The
3f20: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
3f30: 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 62 65 tion must not be
3f40: 20 63 6c 6f 73 65 64 20 77 68 69 6c 65 0a 2a 2a closed while.**
3f50: 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
3f60: 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 e3_exec()] is ru
3f70: 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 nning..**.** {A1
3f80: 32 31 34 33 7d 20 54 68 65 20 63 61 6c 6c 69 6e 2143} The callin
3f90: 67 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c g function shoul
3fa0: 64 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 66 d use [sqlite3_f
3fb0: 72 65 65 28 29 5d 20 74 6f 20 66 72 65 65 0a 2a ree()] to free.*
3fc0: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6d * the m
3fd0: 65 6d 6f 72 79 20 74 68 61 74 20 2a 65 72 72 6d emory that *errm
3fe0: 73 67 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 sg is left point
3ff0: 69 6e 67 20 61 74 20 6f 6e 63 65 20 74 68 65 20 ing at once the
4000: 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 error.**
4010: 20 20 6d 65 73 73 61 67 65 20 69 73 20 6e 6f 20 message is no
4020: 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a longer needed..*
4030: 2a 0a 2a 2a 20 7b 41 31 32 31 34 35 7d 20 54 68 *.** {A12145} Th
4040: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
4050: 74 65 78 74 20 69 6e 20 74 68 65 20 32 6e 64 20 text in the 2nd
4060: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 parameter to [sq
4070: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a lite3_exec()].**
4080: 20 20 20 20 20 20 20 20 20 20 6d 75 73 74 20 72 must r
4090: 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 emain unchanged
40a0: 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 65 while [sqlite3_e
40b0: 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e xec()] is runnin
40c0: 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 g..*/.int sqlite
40d0: 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 3_exec(. sqlite
40e0: 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 3*,
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4100: 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 /* An open
4110: 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f database */. co
4120: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 nst char *sql,
4130: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4140: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 /* SQL
4150: 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 to be evaluated
4160: 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 */. int (*callb
4170: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 ack)(void*,int,c
4180: 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 har**,char**),
4190: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 /* Callback func
41a0: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a tion */. void *
41b0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
41c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
41d0: 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 /* 1st argu
41e0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b ment to callback
41f0: 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 */. char **err
4200: 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 msg
4210: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4220: 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 /* Error msg wr
4230: 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b itten here */.);
4240: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
4250: 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b : Result Codes {
4260: 48 31 30 32 31 30 7d 20 3c 53 31 30 37 30 30 3e H10210} <S10700>
4270: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 .** KEYWORDS: SQ
4280: 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 LITE_OK {error c
4290: 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 ode} {error code
42a0: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 s}.** KEYWORDS:
42b0: 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 {result code} {r
42c0: 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a esult codes}.**.
42d0: 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 ** Many SQLite f
42e0: 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 unctions return
42f0: 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c an integer resul
4300: 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 t code from the
4310: 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 set shown.** her
4320: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e e in order to in
4330: 64 69 63 61 74 65 73 20 73 75 63 63 65 73 73 20 dicates success
4340: 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a or failure..**.*
4350: 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 * New error code
4360: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 s may be added i
4370: 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e n future version
4380: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a s of SQLite..**.
4390: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 ** See also: [SQ
43a0: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 LITE_IOERR_READ
43b0: 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c | extended resul
43c0: 74 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 t codes].*/.#def
43d0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 ine SQLITE_OK
43e0: 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 0 /* S
43f0: 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 uccessful result
4400: 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 */./* beginning
4410: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 -of-error-codes
4420: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4430: 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 E_ERROR 1
4440: 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 /* SQL error
4450: 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 or missing datab
4460: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ase */.#define S
4470: 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 QLITE_INTERNAL
4480: 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 2 /* Intern
4490: 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 al logic error i
44a0: 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 n SQLite */.#def
44b0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 ine SQLITE_PERM
44c0: 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 3 /* A
44d0: 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e ccess permission
44e0: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 denied */.#defi
44f0: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 ne SQLITE_ABORT
4500: 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 4 /* Ca
4510: 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 llback routine r
4520: 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 equested an abor
4530: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
4540: 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 ITE_BUSY
4550: 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 5 /* The data
4560: 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 base file is loc
4570: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ked */.#define S
4580: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 QLITE_LOCKED
4590: 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 6 /* A tabl
45a0: 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 e in the databas
45b0: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 e is locked */.#
45c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f define SQLITE_NO
45d0: 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f MEM 7 /
45e0: 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 * A malloc() fai
45f0: 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 led */.#define S
4600: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 QLITE_READONLY
4610: 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 8 /* Attemp
4620: 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 t to write a rea
4630: 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a donly database *
4640: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4650: 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 _INTERRUPT 9
4660: 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 /* Operation t
4670: 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c erminated by sql
4680: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
4690: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
46a0: 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 E_IOERR 10
46b0: 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 /* Some kind
46c0: 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f of disk I/O erro
46d0: 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 r occurred */.#d
46e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 efine SQLITE_COR
46f0: 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a RUPT 11 /*
4700: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69 The database di
4710: 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 sk image is malf
4720: 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 ormed */.#define
4730: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 SQLITE_NOTFOUND
4740: 20 20 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20 12 /* NOT
4750: 55 53 45 44 2e 20 54 61 62 6c 65 20 6f 72 20 72 USED. Table or r
4760: 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20 ecord not found
4770: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4780: 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 E_FULL 13
4790: 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 /* Insertion
47a0: 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 failed because d
47b0: 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 atabase is full
47c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
47d0: 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 E_CANTOPEN 14
47e0: 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 /* Unable to
47f0: 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 open the databas
4800: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e e file */.#defin
4810: 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f e SQLITE_PROTOCO
4820: 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54 L 15 /* NOT
4830: 20 55 53 45 44 2e 20 44 61 74 61 62 61 73 65 20 USED. Database
4840: 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 lock protocol er
4850: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ror */.#define S
4860: 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 QLITE_EMPTY
4870: 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 16 /* Databa
4880: 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 se is empty */.#
4890: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 define SQLITE_SC
48a0: 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f HEMA 17 /
48b0: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 * The database s
48c0: 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f chema changed */
48d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
48e0: 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 TOOBIG 18
48f0: 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c /* String or BL
4900: 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 OB exceeds size
4910: 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 limit */.#define
4920: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
4930: 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 NT 19 /* Abor
4940: 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 t due to constra
4950: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f int violation */
4960: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4970: 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 MISMATCH 20
4980: 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 /* Data type mi
4990: 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e smatch */.#defin
49a0: 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 e SQLITE_MISUSE
49b0: 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 21 /* Lib
49c0: 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 rary used incorr
49d0: 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 ectly */.#define
49e0: 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 SQLITE_NOLFS
49f0: 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 22 /* Uses
4a00: 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 OS features not
4a10: 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f supported on ho
4a20: 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 st */.#define SQ
4a30: 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 LITE_AUTH
4a40: 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 23 /* Authori
4a50: 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f zation denied */
4a60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4a70: 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 FORMAT 24
4a80: 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 /* Auxiliary da
4a90: 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 tabase format er
4aa0: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ror */.#define S
4ab0: 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 QLITE_RANGE
4ac0: 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 25 /* 2nd pa
4ad0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
4ae0: 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 e3_bind out of r
4af0: 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ange */.#define
4b00: 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 SQLITE_NOTADB
4b10: 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 26 /* File
4b20: 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e opened that is n
4b30: 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 ot a database fi
4b40: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 le */.#define SQ
4b50: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 LITE_ROW
4b60: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 100 /* sqlite3
4b70: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 _step() has anot
4b80: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f her row ready */
4b90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4ba0: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 DONE 101
4bb0: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 /* sqlite3_step
4bc0: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 () has finished
4bd0: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 executing */./*
4be0: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 end-of-error-cod
4bf0: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 es */../*.** CAP
4c00: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 I3REF: Extended
4c10: 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 Result Codes {H1
4c20: 30 32 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 0220} <S10700>.*
4c30: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 * KEYWORDS: {ext
4c40: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 ended error code
4c50: 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f } {extended erro
4c60: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 r codes}.** KEYW
4c70: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 ORDS: {extended
4c80: 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 result code} {ex
4c90: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
4ca0: 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 des}.**.** In it
4cb0: 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 s default config
4cc0: 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 uration, SQLite
4cd0: 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 API routines ret
4ce0: 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e urn one of 26 in
4cf0: 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 teger.** [SQLITE
4d00: 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 _OK | result cod
4d10: 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 es]. However, e
4d20: 78 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 xperience has sh
4d30: 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 own that many of
4d40: 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 .** these result
4d50: 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 codes are too c
4d60: 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 oarse-grained.
4d70: 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 They do not prov
4d80: 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 ide as.** much i
4d90: 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 nformation about
4da0: 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f problems as pro
4db0: 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c grammers might l
4dc0: 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f ike. In an effo
4dd0: 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 rt to.** address
4de0: 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 this, newer ver
4df0: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 sions of SQLite
4e00: 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 (version 3.3.8 a
4e10: 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 nd later) includ
4e20: 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 e.** support for
4e30: 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 additional resu
4e40: 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 lt codes that pr
4e50: 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 ovide more detai
4e60: 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a led information.
4e70: 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e ** about errors.
4e80: 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 The extended re
4e90: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 sult codes are e
4ea0: 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c nabled or disabl
4eb0: 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 ed.** on a per d
4ec0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
4ed0: 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 on basis using t
4ee0: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 he.** [sqlite3_e
4ef0: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 xtended_result_c
4f00: 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a odes()] API..**.
4f10: 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 ** Some of the a
4f20: 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 vailable extende
4f30: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 d result codes a
4f40: 72 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a re listed here..
4f50: 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 ** One may expec
4f60: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 t the number of
4f70: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
4f80: 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 codes will be ex
4f90: 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d pand.** over tim
4fa0: 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 e. Software tha
4fb0: 74 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 t uses extended
4fc0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f result codes sho
4fd0: 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f uld expect.** to
4fe0: 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 see new result
4ff0: 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 codes in future
5000: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 releases of SQLi
5010: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 te..**.** The SQ
5020: 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 LITE_OK result c
5030: 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 ode will never b
5040: 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 e extended. It
5050: 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 will always.** b
5060: 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a e exactly zero..
5070: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
5080: 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 33 7d :.**.** {H10223}
5090: 20 54 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 The symbolic na
50a0: 6d 65 20 66 6f 72 20 61 6e 20 65 78 74 65 6e 64 me for an extend
50b0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 73 ed result code s
50c0: 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a hall contains.**
50d0: 20 20 20 20 20 20 20 20 20 20 61 20 72 65 6c 61 a rela
50e0: 74 65 64 20 70 72 69 6d 61 72 79 20 72 65 73 75 ted primary resu
50f0: 6c 74 20 63 6f 64 65 20 61 73 20 61 20 70 72 65 lt code as a pre
5100: 66 69 78 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 fix..**.** {H102
5110: 32 34 7d 20 50 72 69 6d 61 72 79 20 72 65 73 75 24} Primary resu
5120: 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73 20 73 68 lt code names sh
5130: 61 6c 6c 20 63 6f 6e 74 61 69 6e 20 61 20 73 69 all contain a si
5140: 6e 67 6c 65 20 22 5f 22 20 63 68 61 72 61 63 74 ngle "_" charact
5150: 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 er..**.** {H1022
5160: 35 7d 20 45 78 74 65 6e 64 65 64 20 72 65 73 75 5} Extended resu
5170: 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73 20 73 68 lt code names sh
5180: 61 6c 6c 20 63 6f 6e 74 61 69 6e 20 74 77 6f 20 all contain two
5190: 6f 72 20 6d 6f 72 65 20 22 5f 22 20 63 68 61 72 or more "_" char
51a0: 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 acters..**.** {H
51b0: 31 30 32 32 36 7d 20 54 68 65 20 6e 75 6d 65 72 10226} The numer
51c0: 69 63 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 65 ic value of an e
51d0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
51e0: 6f 64 65 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 ode shall contai
51f0: 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 n the.**
5200: 20 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 numeric value
5210: 6f 66 20 69 74 73 20 63 6f 72 72 65 73 70 6f 6e of its correspon
5220: 64 69 6e 67 20 70 72 69 6d 61 72 79 20 72 65 73 ding primary res
5230: 75 6c 74 20 63 6f 64 65 20 69 6e 0a 2a 2a 20 20 ult code in.**
5240: 20 20 20 20 20 20 20 20 69 74 73 20 6c 65 61 73 its leas
5250: 74 20 73 69 67 6e 69 66 69 63 61 6e 74 20 38 20 t significant 8
5260: 62 69 74 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 bits..*/.#define
5270: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 SQLITE_IOERR_RE
5280: 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 AD
5290: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
52a0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (1<<8)).#define
52b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f SQLITE_IOERR_SHO
52c0: 52 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 RT_READ (
52d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
52e0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 2<<8)).#define S
52f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 QLITE_IOERR_WRIT
5300: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 E (S
5310: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 QLITE_IOERR | (3
5320: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5330: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 LITE_IOERR_FSYNC
5340: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
5350: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c LITE_IOERR | (4<
5360: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5370: 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 ITE_IOERR_DIR_FS
5380: 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c YNC (SQL
5390: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c ITE_IOERR | (5<<
53a0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
53b0: 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 TE_IOERR_TRUNCAT
53c0: 45 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 E (SQLI
53d0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 TE_IOERR | (6<<8
53e0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
53f0: 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 E_IOERR_FSTAT
5400: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
5410: 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 E_IOERR | (7<<8)
5420: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5430: 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 _IOERR_UNLOCK
5440: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5450: 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 _IOERR | (8<<8))
5460: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5470: 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 IOERR_RDLOCK
5480: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5490: 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a IOERR | (9<<8)).
54a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
54b0: 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 OERR_DELETE
54c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
54d0: 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a OERR | (10<<8)).
54e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
54f0: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 OERR_BLOCKED
5500: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
5510: 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a OERR | (11<<8)).
5520: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5530: 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 OERR_NOMEM
5540: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
5550: 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a OERR | (12<<8)).
5560: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5570: 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 OERR_ACCESS
5580: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
5590: 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a OERR | (13<<8)).
55a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
55b0: 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 OERR_CHECKRESERV
55c0: 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 EDLOCK (SQLITE_I
55d0: 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a OERR | (14<<8)).
55e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
55f0: 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 OERR_LOCK
5600: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
5610: 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a OERR | (15<<8)).
5620: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
5630: 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 Flags For File
5640: 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 20 Open Operations
5650: 7b 48 31 30 32 33 30 7d 20 3c 48 31 31 31 32 30 {H10230} <H11120
5660: 3e 20 3c 48 31 32 37 30 30 3e 0a 2a 2a 0a 2a 2a > <H12700>.**.**
5670: 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 These bit value
5680: 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 s are intended f
5690: 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a or use in the.**
56a0: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 3rd parameter t
56b0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f o the [sqlite3_o
56c0: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 pen_v2()] interf
56d0: 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 ace and.** in th
56e0: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 4th parameter
56f0: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 to the xOpen met
5700: 68 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 hod of the.** [s
5710: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
5720: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ct..*/.#define S
5730: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
5740: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 NLY 0x00
5750: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 000001.#define S
5760: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
5770: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 RITE 0x00
5780: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 000002.#define S
5790: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
57a0: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 E 0x00
57b0: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 000004.#define S
57c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 QLITE_OPEN_DELET
57d0: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 EONCLOSE 0x00
57e0: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 000008.#define S
57f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 QLITE_OPEN_EXCLU
5800: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 SIVE 0x00
5810: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 000010.#define S
5820: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f QLITE_OPEN_MAIN_
5830: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 DB 0x00
5840: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 000100.#define S
5850: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
5860: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 DB 0x00
5870: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 000200.#define S
5880: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 QLITE_OPEN_TRANS
5890: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 IENT_DB 0x00
58a0: 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 000400.#define S
58b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f QLITE_OPEN_MAIN_
58c0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 JOURNAL 0x00
58d0: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 000800.#define S
58e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
58f0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 JOURNAL 0x00
5900: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 001000.#define S
5910: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f QLITE_OPEN_SUBJO
5920: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 URNAL 0x00
5930: 30 30 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53 002000.#define S
5940: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 QLITE_OPEN_MASTE
5950: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 R_JOURNAL 0x00
5960: 30 30 34 30 30 30 0a 23 64 65 66 69 6e 65 20 53 004000.#define S
5970: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 QLITE_OPEN_NOMUT
5980: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 EX 0x00
5990: 30 30 38 30 30 30 0a 23 64 65 66 69 6e 65 20 53 008000.#define S
59a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d QLITE_OPEN_FULLM
59b0: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30 UTEX 0x00
59c0: 30 31 30 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 010000../*.** CA
59d0: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 PI3REF: Device C
59e0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 7b haracteristics {
59f0: 48 31 30 32 34 30 7d 20 3c 48 31 31 31 32 30 3e H10240} <H11120>
5a00: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 .**.** The xDevi
5a10: 63 65 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d ceCapabilities m
5a20: 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 ethod of the [sq
5a30: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
5a40: 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 ].** object retu
5a50: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 rns an integer w
5a60: 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 hich is a vector
5a70: 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a of the these.**
5a80: 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 bit values expr
5a90: 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 essing I/O chara
5aa0: 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 cteristics of th
5ab0: 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a e mass storage.*
5ac0: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f * device that ho
5ad0: 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 lds the file tha
5ae0: 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 t the [sqlite3_i
5af0: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 o_methods].** re
5b00: 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 fers to..**.** T
5b10: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
5b20: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 ATOMIC property
5b30: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 means that all w
5b40: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 rites of.** any
5b50: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e size are atomic.
5b60: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 The SQLITE_IOC
5b70: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c AP_ATOMICnnn val
5b80: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 ues.** mean that
5b90: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b writes of block
5ba0: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 s that are nnn b
5bb0: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 ytes in size and
5bc0: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 .** are aligned
5bd0: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 to an address wh
5be0: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 ich is an intege
5bf0: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a r multiple of.**
5c00: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e nnn are atomic.
5c10: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 The SQLITE_IOC
5c20: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 AP_SAFE_APPEND v
5c30: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 alue means.** th
5c40: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 at when data is
5c50: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 appended to a fi
5c60: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 le, the data is
5c70: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 appended.** firs
5c80: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 t then the size
5c90: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 of the file is e
5ca0: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 xtended, never t
5cb0: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 he other.** way
5cc0: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c around. The SQL
5cd0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e ITE_IOCAP_SEQUEN
5ce0: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 TIAL property me
5cf0: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f ans that.** info
5d00: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 rmation is writt
5d10: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 en to disk in th
5d20: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 e same order as
5d30: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 calls.** to xWri
5d40: 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 te()..*/.#define
5d50: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
5d60: 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 30 78 OMIC 0x
5d70: 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 00000001.#define
5d80: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
5d90: 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 30 78 OMIC512 0x
5da0: 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 00000002.#define
5db0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
5dc0: 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 30 78 OMIC1K 0x
5dd0: 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 00000004.#define
5de0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
5df0: 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 30 78 OMIC2K 0x
5e00: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 00000008.#define
5e10: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
5e20: 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 30 78 OMIC4K 0x
5e30: 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 00000010.#define
5e40: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
5e50: 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 30 78 OMIC8K 0x
5e60: 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 00000020.#define
5e70: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
5e80: 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 30 78 OMIC16K 0x
5e90: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 00000040.#define
5ea0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
5eb0: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 30 78 OMIC32K 0x
5ec0: 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 00000080.#define
5ed0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
5ee0: 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 30 78 OMIC64K 0x
5ef0: 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 00000100.#define
5f00: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 SQLITE_IOCAP_SA
5f10: 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78 FE_APPEND 0x
5f20: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 00000200.#define
5f30: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 SQLITE_IOCAP_SE
5f40: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78 QUENTIAL 0x
5f50: 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 00000400../*.**
5f60: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c CAPI3REF: File L
5f70: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 48 ocking Levels {H
5f80: 31 30 32 35 30 7d 20 3c 48 31 31 31 32 30 3e 20 10250} <H11120>
5f90: 3c 48 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 <H11310>.**.** S
5fa0: 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f QLite uses one o
5fb0: 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 f these integer
5fc0: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 values as the se
5fd0: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 cond.** argument
5fe0: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b to calls it mak
5ff0: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 es to the xLock(
6000: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 ) and xUnlock()
6010: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e methods.** of an
6020: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
6030: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f hods] object..*/
6040: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6050: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 LOCK_NONE
6060: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0.#define SQL
6070: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 ITE_LOCK_SHARED
6080: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 1.#define
6090: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 SQLITE_LOCK_RES
60a0: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 ERVED 2.#de
60b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b fine SQLITE_LOCK
60c0: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 _PENDING 3
60d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
60e0: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 LOCK_EXCLUSIVE
60f0: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 4../*.** CAPI
6100: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 3REF: Synchroniz
6110: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 ation Type Flags
6120: 20 7b 48 31 30 32 36 30 7d 20 3c 48 31 31 31 32 {H10260} <H1112
6130: 30 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 0>.**.** When SQ
6140: 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 Lite invokes the
6150: 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 xSync() method
6160: 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 of an.** [sqlite
6170: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
6180: 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 ject it uses a c
6190: 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a ombination of.**
61a0: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 these integer v
61b0: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 alues as the sec
61c0: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a ond argument..**
61d0: 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c .** When the SQL
61e0: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c ITE_SYNC_DATAONL
61f0: 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 Y flag is used,
6200: 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 it means that th
6210: 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 e.** sync operat
6220: 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 ion only needs t
6230: 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 o flush data to
6240: 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 mass storage. I
6250: 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 node.** informat
6260: 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 ion need not be
6270: 66 6c 75 73 68 65 64 2e 20 54 68 65 20 53 51 4c flushed. The SQL
6280: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 ITE_SYNC_NORMAL
6290: 66 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f flag means.** to
62a0: 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e use normal fsyn
62b0: 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 20 54 c() semantics. T
62c0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 he SQLITE_SYNC_F
62d0: 55 4c 4c 20 66 6c 61 67 20 6d 65 61 6e 73 0a 2a ULL flag means.*
62e0: 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 2d * to use Mac OS-
62f0: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 X style fullsync
6300: 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e instead of fsyn
6310: 63 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 c()..*/.#define
6320: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d SQLITE_SYNC_NORM
6330: 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30 AL 0x0000
6340: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
6350: 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 _SYNC_FULL
6360: 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 0x00003.#def
6370: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f ine SQLITE_SYNC_
6380: 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 DATAONLY 0x
6390: 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 00010../*.** CAP
63a0: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 I3REF: OS Interf
63b0: 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 ace Open File Ha
63c0: 6e 64 6c 65 20 7b 48 31 31 31 31 30 7d 20 3c 53 ndle {H11110} <S
63d0: 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 20110>.**.** An
63e0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f [sqlite3_file] o
63f0: 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 bject represents
6400: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e an open file in
6410: 20 74 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 the OS.** inter
6420: 66 61 63 65 20 6c 61 79 65 72 2e 20 20 49 6e 64 face layer. Ind
6430: 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 ividual OS inter
6440: 66 61 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 face implementat
6450: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e ions will.** wan
6460: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 t to subclass th
6470: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 is object by app
6480: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 ending additiona
6490: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 l fields.** for
64a0: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 their own use.
64b0: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 The pMethods ent
64c0: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 ry is a pointer
64d0: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 to an.** [sqlite
64e0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
64f0: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 ject that define
6500: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 s methods for pe
6510: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 rforming.** I/O
6520: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 operations on th
6530: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a e open file..*/.
6540: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
6550: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 qlite3_file sqli
6560: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 te3_file;.struct
6570: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a sqlite3_file {.
6580: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 const struct s
6590: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
65a0: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a s *pMethods; /*
65b0: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 Methods for an
65c0: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a open file */.};.
65d0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
65e0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 OS Interface Fi
65f0: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f le Virtual Metho
6600: 64 73 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 32 ds Object {H1112
6610: 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 0} <S20110>.**.*
6620: 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 * Every file ope
6630: 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 ned by the [sqli
6640: 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20 6d te3_vfs] xOpen m
6650: 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 ethod populates
6660: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 an.** [sqlite3_f
6670: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c ile] object (or,
6680: 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 more commonly,
6690: 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 a subclass of th
66a0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 e.** [sqlite3_fi
66b0: 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 le] object) with
66c0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
66d0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 instance of thi
66e0: 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 s object..** Thi
66f0: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 s object defines
6700: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 the methods use
6710: 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 d to perform var
6720: 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a ious operations.
6730: 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f ** against the o
6740: 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 pen file represe
6750: 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c nted by the [sql
6760: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 ite3_file] objec
6770: 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 t..**.** The fla
6780: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 gs argument to x
6790: 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 Sync may be one
67a0: 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f of [SQLITE_SYNC_
67b0: 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 NORMAL] or.** [S
67c0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d QLITE_SYNC_FULL]
67d0: 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f . The first cho
67e0: 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 ice is the norma
67f0: 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 l fsync()..** Th
6800: 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 e second choice
6810: 69 73 20 61 20 4d 61 63 20 4f 53 2d 58 20 73 74 is a Mac OS-X st
6820: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 yle fullsync. T
6830: 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f he [SQLITE_SYNC_
6840: 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 DATAONLY].** fla
6850: 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e g may be ORed in
6860: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 to indicate tha
6870: 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 t only the data
6880: 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 of the file.** a
6890: 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 nd not its inode
68a0: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e needs to be syn
68b0: 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 ced..**.** The i
68c0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f nteger values to
68d0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e xLock() and xUn
68e0: 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f lock() are one o
68f0: 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 f.** <ul>.** <li
6900: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e > [SQLITE_LOCK_N
6910: 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 ONE],.** <li> [S
6920: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 QLITE_LOCK_SHARE
6930: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c D],.** <li> [SQL
6940: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 ITE_LOCK_RESERVE
6950: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c D],.** <li> [SQL
6960: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 ITE_LOCK_PENDING
6970: 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 ], or.** <li> [S
6980: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 QLITE_LOCK_EXCLU
6990: 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a SIVE]..** </ul>.
69a0: 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 ** xLock() incre
69b0: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 ases the lock. x
69c0: 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 Unlock() decreas
69d0: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 es the lock..**
69e0: 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 The xCheckReserv
69f0: 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 edLock() method
6a00: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 checks whether a
6a10: 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ny database conn
6a20: 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 ection,.** eithe
6a30: 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 r in this proces
6a40: 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 s or in some oth
6a50: 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 er process, is h
6a60: 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 olding a RESERVE
6a70: 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f D,.** PENDING, o
6a80: 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b r EXCLUSIVE lock
6a90: 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 on the file. I
6aa0: 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a t returns true.*
6ab0: 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b * if such a lock
6ac0: 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 exists and fals
6ad0: 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a e otherwise..**.
6ae0: 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 ** The xFileCont
6af0: 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 rol() method is
6b00: 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 a generic interf
6b10: 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 ace that allows
6b20: 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d custom.** VFS im
6b30: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f plementations to
6b40: 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f directly contro
6b50: 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 l an open file u
6b60: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c sing the.** [sql
6b70: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
6b80: 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 l()] interface.
6b90: 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 The second "op"
6ba0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a argument is an.
6bb0: 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 ** integer opcod
6bc0: 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 e. The third ar
6bd0: 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 gument is a gene
6be0: 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 ric pointer inte
6bf0: 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 nded to.** point
6c00: 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 to a structure
6c10: 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e that may contain
6c20: 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 arguments or sp
6c30: 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a ace in which to.
6c40: 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 ** write return
6c50: 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 values. Potenti
6c60: 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c al uses for xFil
6c70: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 eControl() might
6c80: 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 be.** functions
6c90: 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b to enable block
6ca0: 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 ing locks with t
6cb0: 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e imeouts, to chan
6cc0: 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e ge the.** lockin
6cd0: 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 g strategy (for
6ce0: 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 example to use d
6cf0: 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 ot-file locks),
6d00: 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 to inquire.** ab
6d10: 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f out the status o
6d20: 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 f a lock, or to
6d30: 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b break stale lock
6d40: 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a s. The SQLite.*
6d50: 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 * core reserves
6d60: 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 all opcodes less
6d70: 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 than 100 for it
6d80: 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 s own use..** A
6d90: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f [SQLITE_FCNTL_LO
6da0: 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f CKSTATE | list o
6db0: 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 f opcodes] less
6dc0: 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 than 100 is avai
6dd0: 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 lable..** Applic
6de0: 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 ations that defi
6df0: 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c ne a custom xFil
6e00: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 eControl method
6e10: 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 should use opcod
6e20: 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 es.** greater th
6e30: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 an 100 to avoid
6e40: 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a conflicts..**.**
6e50: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 The xSectorSize
6e60: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e () method return
6e70: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a s the sector siz
6e80: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 e of the.** devi
6e90: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 ce that underlie
6ea0: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 s the file. The
6eb0: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 sector size is
6ec0: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 the.** minimum w
6ed0: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 rite that can be
6ee0: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f performed witho
6ef0: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a ut disturbing.**
6f00: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 other bytes in
6f10: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 the file. The x
6f20: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 DeviceCharacteri
6f30: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f stics().** metho
6f40: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 d returns a bit
6f50: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e vector describin
6f60: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 g behaviors of t
6f70: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 he.** underlying
6f80: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c device:.**.** <
6f90: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c ul>.** <li> [SQL
6fa0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
6fb0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
6fc0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 E_IOCAP_ATOMIC51
6fd0: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 2].** <li> [SQLI
6fe0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 TE_IOCAP_ATOMIC1
6ff0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
7000: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 TE_IOCAP_ATOMIC2
7010: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
7020: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 TE_IOCAP_ATOMIC4
7030: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
7040: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 TE_IOCAP_ATOMIC8
7050: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
7060: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 TE_IOCAP_ATOMIC1
7070: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 6K].** <li> [SQL
7080: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
7090: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 32K].** <li> [SQ
70a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
70b0: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 C64K].** <li> [S
70c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 QLITE_IOCAP_SAFE
70d0: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e _APPEND].** <li>
70e0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 [SQLITE_IOCAP_S
70f0: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f EQUENTIAL].** </
7100: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 ul>.**.** The SQ
7110: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
7120: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 C property means
7130: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 that all writes
7140: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 of.** any size
7150: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 are atomic. The
7160: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
7170: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a OMICnnn values.*
7180: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 * mean that writ
7190: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 es of blocks tha
71a0: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 t are nnn bytes
71b0: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 in size and.** a
71c0: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e re aligned to an
71d0: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 address which i
71e0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c s an integer mul
71f0: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 tiple of.** nnn
7200: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 are atomic. The
7210: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 SQLITE_IOCAP_SA
7220: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 FE_APPEND value
7230: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 means.** that wh
7240: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e en data is appen
7250: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 ded to a file, t
7260: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e he data is appen
7270: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 ded.** first the
7280: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 n the size of th
7290: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 e file is extend
72a0: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 ed, never the ot
72b0: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e her.** way aroun
72c0: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 d. The SQLITE_I
72d0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 OCAP_SEQUENTIAL
72e0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 property means t
72f0: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 hat.** informati
7300: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f on is written to
7310: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d disk in the sam
7320: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 e order as calls
7330: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e .** to xWrite().
7340: 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 .**.** If xRead(
7350: 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 ) returns SQLITE
7360: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 _IOERR_SHORT_REA
7370: 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 D it must also f
7380: 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e ill.** in the un
7390: 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 read portions of
73a0: 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68 the buffer with
73b0: 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 zeros. A VFS t
73c0: 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 hat.** fails to
73d0: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 zero-fill short
73e0: 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d reads might seem
73f0: 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 to work. Howev
7400: 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 er,.** failure t
7410: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 o zero-fill shor
7420: 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 t reads will eve
7430: 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a ntually lead to.
7440: 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 ** database corr
7450: 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 uption..*/.typed
7460: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
7470: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 3_io_methods sql
7480: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b ite3_io_methods;
7490: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
74a0: 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 io_methods {. i
74b0: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 nt iVersion;. i
74c0: 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c nt (*xClose)(sql
74d0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 ite3_file*);. i
74e0: 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 nt (*xRead)(sqli
74f0: 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a te3_file*, void*
7500: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 , int iAmt, sqli
7510: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 te3_int64 iOfst)
7520: 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 ;. int (*xWrite
7530: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
7540: 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
7550: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f t iAmt, sqlite3_
7560: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 int64 iOfst);.
7570: 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 int (*xTruncate)
7580: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
7590: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 sqlite3_int64 si
75a0: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 ze);. int (*xSy
75b0: 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 nc)(sqlite3_file
75c0: 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 *, int flags);.
75d0: 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 int (*xFileSize
75e0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
75f0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a sqlite3_int64 *
7600: 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a pSize);. int (*
7610: 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 xLock)(sqlite3_f
7620: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e ile*, int);. in
7630: 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c t (*xUnlock)(sql
7640: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 ite3_file*, int)
7650: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b ;. int (*xCheck
7660: 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 ReservedLock)(sq
7670: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 lite3_file*, int
7680: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e *pResOut);. in
7690: 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c t (*xFileControl
76a0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
76b0: 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 int op, void *p
76c0: 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 Arg);. int (*xS
76d0: 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 ectorSize)(sqlit
76e0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 e3_file*);. int
76f0: 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 (*xDeviceCharac
7700: 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 teristics)(sqlit
7710: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 e3_file*);. /*
7720: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f Additional metho
7730: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 ds may be added
7740: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
7750: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 es */.};../*.**
7760: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 CAPI3REF: Standa
7770: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 rd File Control
7780: 4f 70 63 6f 64 65 73 20 7b 48 31 31 33 31 30 7d Opcodes {H11310}
7790: 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S30800>.**.**
77a0: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f These integer co
77b0: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f nstants are opco
77c0: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c des for the xFil
77d0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a eControl method.
77e0: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ** of the [sqlit
77f0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f e3_io_methods] o
7800: 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 bject and for th
7810: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f e [sqlite3_file_
7820: 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e control()].** in
7830: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 terface..**.** T
7840: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
7850: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f _LOCKSTATE] opco
7860: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 de is used for d
7870: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a ebugging. This.
7880: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 ** opcode causes
7890: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f the xFileContro
78a0: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 l method to writ
78b0: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 e the current st
78c0: 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f ate of.** the lo
78d0: 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 ck (one of [SQLI
78e0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b TE_LOCK_NONE], [
78f0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 SQLITE_LOCK_SHAR
7900: 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ED],.** [SQLITE_
7910: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 LOCK_RESERVED],
7920: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e [SQLITE_LOCK_PEN
7930: 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 DING], or [SQLIT
7940: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 E_LOCK_EXCLUSIVE
7950: 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e ]).** into an in
7960: 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 teger that the p
7970: 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 Arg argument poi
7980: 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 nts to. This cap
7990: 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 ability.** is us
79a0: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e ed during testin
79b0: 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 g and only needs
79c0: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 to be supported
79d0: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 when SQLITE_TES
79e0: 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e T.** is defined.
79f0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
7a00: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 TE_FCNTL_LOCKSTA
7a10: 54 45 20 20 20 20 20 20 20 20 31 0a 0a 2f 2a 0a TE 1../*.
7a20: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 ** CAPI3REF: Mut
7a30: 65 78 20 48 61 6e 64 6c 65 20 7b 48 31 37 31 31 ex Handle {H1711
7a40: 30 7d 20 3c 53 32 30 31 33 30 3e 0a 2a 2a 0a 2a 0} <S20130>.**.*
7a50: 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 * The mutex modu
7a60: 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 le within SQLite
7a70: 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 defines [sqlite
7a80: 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 3_mutex] to be a
7a90: 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 n.** abstract ty
7aa0: 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f pe for a mutex o
7ab0: 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 bject. The SQLi
7ac0: 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f te core never lo
7ad0: 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e oks.** at the in
7ae0: 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 ternal represent
7af0: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c ation of an [sql
7b00: 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 ite3_mutex]. It
7b10: 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 only.** deals w
7b20: 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 ith pointers to
7b30: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 the [sqlite3_mut
7b40: 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a ex] object..**.*
7b50: 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 * Mutexes are cr
7b60: 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c eated using [sql
7b70: 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 ite3_mutex_alloc
7b80: 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ()]..*/.typedef
7b90: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d struct sqlite3_m
7ba0: 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 utex sqlite3_mut
7bb0: 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 ex;../*.** CAPI3
7bc0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 REF: OS Interfac
7bd0: 65 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 34 30 e Object {H11140
7be0: 7d 20 3c 53 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a } <S20100>.**.**
7bf0: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 An instance of
7c00: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 the sqlite3_vfs
7c10: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 object defines t
7c20: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 he interface bet
7c30: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 ween.** the SQLi
7c40: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 te core and the
7c50: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 underlying opera
7c60: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 ting system. Th
7c70: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 e "vfs".** in th
7c80: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 e name of the ob
7c90: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 ject stands for
7ca0: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 "virtual file sy
7cb0: 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 stem"..**.** The
7cc0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 value of the iV
7cd0: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 ersion field is
7ce0: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 initially 1 but
7cf0: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e may be larger in
7d00: 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 .** future versi
7d10: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 ons of SQLite.
7d20: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 Additional field
7d30: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 s may be appende
7d40: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a d to this.** obj
7d50: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 ect when the iVe
7d60: 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 rsion value is i
7d70: 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 ncreased. Note
7d80: 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 that the structu
7d90: 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c re.** of the sql
7da0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 ite3_vfs object
7db0: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 changes in the t
7dc0: 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 ransaction betwe
7dd0: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 en.** SQLite ver
7de0: 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 sion 3.5.9 and 3
7df0: 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 .6.0 and yet the
7e00: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 iVersion field
7e10: 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 was not.** modif
7e20: 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ied..**.** The s
7e30: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 zOsFile field is
7e40: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 the size of the
7e50: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c subclassed [sql
7e60: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 ite3_file].** st
7e70: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 ructure used by
7e80: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 this VFS. mxPat
7e90: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 hname is the max
7ea0: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a imum length of.*
7eb0: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 * a pathname in
7ec0: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 this VFS..**.**
7ed0: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 Registered sqlit
7ee0: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 e3_vfs objects a
7ef0: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e re kept on a lin
7f00: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 ked list formed
7f10: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 by.** the pNext
7f20: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 pointer. The [s
7f30: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 qlite3_vfs_regis
7f40: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 ter()].** and [s
7f50: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 qlite3_vfs_unreg
7f60: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 ister()] interfa
7f70: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 ces manage this
7f80: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 list.** in a thr
7f90: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 ead-safe way. T
7fa0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f he [sqlite3_vfs_
7fb0: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 find()] interfac
7fc0: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 e.** searches th
7fd0: 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 e list. Neither
7fe0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
7ff0: 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 code nor the VF
8000: 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 S.** implementat
8010: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 ion should use t
8020: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 he pNext pointer
8030: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 ..**.** The pNex
8040: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f t field is the o
8050: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 nly field in the
8060: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 sqlite3_vfs.**
8070: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 structure that S
8080: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 QLite will ever
8090: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 modify. SQLite
80a0: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 will only access
80b0: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 .** or modify th
80c0: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 is field while h
80d0: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 olding a particu
80e0: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 lar static mutex
80f0: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 ..** The applica
8100: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 tion should neve
8110: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e r modify anythin
8120: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c g within the sql
8130: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 ite3_vfs.** obje
8140: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 ct once the obje
8150: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 ct has been regi
8160: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 stered..**.** Th
8170: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f e zName field ho
8180: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 lds the name of
8190: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 the VFS module.
81a0: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a The name must.*
81b0: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f * be unique acro
81c0: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c ss all VFS modul
81d0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 es..**.** {H1114
81e0: 31 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67 1} SQLite will g
81f0: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 uarantee that th
8200: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 e zFilename para
8210: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a meter to xOpen.*
8220: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 * is either a NU
8230: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 LL pointer or st
8240: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a ring obtained.**
8250: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e from xFullPathn
8260: 61 6d 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66 ame(). SQLite f
8270: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 urther guarantee
8280: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 s that.** the st
8290: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c ring will be val
82a0: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 id and unchanged
82b0: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 until xClose()
82c0: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 7b 45 is.** called. {E
82d0: 4e 44 7d 20 20 42 65 63 61 75 73 65 20 6f 66 20 ND} Because of
82e0: 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e the previous sen
82f0: 74 65 6e 73 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 tense,.** the [s
8300: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e qlite3_file] can
8310: 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 safely store a
8320: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a pointer to the.*
8330: 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 * filename if it
8340: 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 needs to rememb
8350: 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 er the filename
8360: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e for some reason.
8370: 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 .** If the zFile
8380: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 name parameter i
8390: 73 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c s xOpen is a NUL
83a0: 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 L pointer then x
83b0: 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 Open.** must inv
83c0: 69 74 65 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 ite its own temp
83d0: 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 orary name for t
83e0: 68 65 20 66 69 6c 65 2e 20 20 57 68 65 6e 65 76 he file. Whenev
83f0: 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 er the .** xFile
8400: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 name parameter i
8410: 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 s NULL it will a
8420: 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 lso be the case
8430: 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 that the.** flag
8440: 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c s parameter will
8450: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 include [SQLITE
8460: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c _OPEN_DELETEONCL
8470: 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 OSE]..**.** {H11
8480: 31 34 32 7d 20 54 68 65 20 66 6c 61 67 73 20 61 142} The flags a
8490: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e rgument to xOpen
84a0: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 () includes all
84b0: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 bits set in.** t
84c0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e he flags argumen
84d0: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 t to [sqlite3_op
84e0: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 en_v2()]. Or if
84f0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
8500: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 ].** or [sqlite3
8510: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 _open16()] is us
8520: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 ed, then flags i
8530: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 ncludes at least
8540: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e .** [SQLITE_OPEN
8550: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 _READWRITE] | [S
8560: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
8570: 45 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 49 66 20 E]. {END}.** If
8580: 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 xOpen() opens a
8590: 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 file read-only t
85a0: 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 hen it sets *pOu
85b0: 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 tFlags to.** inc
85c0: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 lude [SQLITE_OPE
85d0: 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 N_READONLY]. Ot
85e0: 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 her bits in *pOu
85f0: 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 tFlags may be se
8600: 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 33 t..**.** {H11143
8610: 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c } SQLite will al
8620: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 so add one of th
8630: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 e following flag
8640: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 s to the xOpen()
8650: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 .** call, depend
8660: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 ing on the objec
8670: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a t being opened:.
8680: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
8690: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
86a0: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 _MAIN_DB].** <li
86b0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
86c0: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a MAIN_JOURNAL].**
86d0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
86e0: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 PEN_TEMP_DB].**
86f0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
8700: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d EN_TEMP_JOURNAL]
8710: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
8720: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 E_OPEN_TRANSIENT
8730: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 _DB].** <li> [S
8740: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f QLITE_OPEN_SUBJO
8750: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 URNAL].** <li>
8760: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 [SQLITE_OPEN_MAS
8770: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 TER_JOURNAL].**
8780: 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a </ul> {END}.**.*
8790: 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 * The file I/O i
87a0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 mplementation ca
87b0: 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 n use the object
87c0: 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a type flags to.*
87d0: 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 * change the way
87e0: 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 it deals with f
87f0: 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 iles. For examp
8800: 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 le, an applicati
8810: 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 on.** that does
8820: 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 not care about c
8830: 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 rash recovery or
8840: 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 rollback might
8850: 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e make.** the open
8860: 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 of a journal fi
8870: 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 le a no-op. Wri
8880: 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 tes to this jour
8890: 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 nal would.** als
88a0: 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 o be no-ops, and
88b0: 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 any attempt to
88c0: 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c read the journal
88d0: 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a would return.**
88e0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 SQLITE_IOERR.
88f0: 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 Or the implement
8900: 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f ation might reco
8910: 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 gnize that a dat
8920: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 abase.** file wi
8930: 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 ll be doing page
8940: 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 -aligned sector
8950: 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 reads and writes
8960: 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 in a random.**
8970: 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 order and set up
8980: 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 its I/O subsyst
8990: 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a em accordingly..
89a0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 **.** SQLite mig
89b0: 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 ht also add one
89c0: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 of the following
89d0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f flags to the xO
89e0: 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a pen method:.**.*
89f0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b * <ul>.** <li> [
8a00: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 SQLITE_OPEN_DELE
8a10: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c TEONCLOSE].** <l
8a20: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f i> [SQLITE_OPEN_
8a30: 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f EXCLUSIVE].** </
8a40: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 ul>.**.** {H1114
8a50: 35 7d 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 5} The [SQLITE_O
8a60: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 PEN_DELETEONCLOS
8a70: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 E] flag means th
8a80: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 e file should be
8a90: 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e .** deleted when
8aa0: 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 it is closed.
8ab0: 7b 48 31 31 31 34 36 7d 20 54 68 65 20 5b 53 51 {H11146} The [SQ
8ac0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 LITE_OPEN_DELETE
8ad0: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c ONCLOSE].** will
8ae0: 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 be set for TEMP
8af0: 20 20 64 61 74 61 62 61 73 65 73 2c 20 6a 6f 75 databases, jou
8b00: 72 6e 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 rnals and for su
8b10: 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a bjournals..**.**
8b20: 20 7b 48 31 31 31 34 37 7d 20 54 68 65 20 5b 53 {H11147} The [S
8b30: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 QLITE_OPEN_EXCLU
8b40: 53 49 56 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 SIVE] flag means
8b50: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 the file should
8b60: 20 62 65 20 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f be opened.** fo
8b70: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 r exclusive acce
8b80: 73 73 2e 20 20 54 68 69 73 20 66 6c 61 67 20 69 ss. This flag i
8b90: 73 20 73 65 74 20 66 6f 72 20 61 6c 6c 20 66 69 s set for all fi
8ba0: 6c 65 73 20 65 78 63 65 70 74 0a 2a 2a 20 66 6f les except.** fo
8bb0: 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 r the main datab
8bc0: 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 ase file..**.**
8bd0: 7b 48 31 31 31 34 38 7d 20 41 74 20 6c 65 61 73 {H11148} At leas
8be0: 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 t szOsFile bytes
8bf0: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 of memory are a
8c00: 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 llocated by SQLi
8c10: 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 te.** to hold th
8c20: 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 e [sqlite3_file
8c30: 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 ] structure pass
8c40: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a ed as the third.
8c50: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 ** argument to x
8c60: 4f 70 65 6e 2e 20 7b 45 4e 44 7d 20 20 54 68 65 Open. {END} The
8c70: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f xOpen method do
8c80: 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a es not have to.*
8c90: 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 * allocate the s
8ca0: 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f tructure; it sho
8cb0: 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 uld just fill it
8cc0: 20 69 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 in..**.** {H111
8cd0: 34 39 7d 20 54 68 65 20 66 6c 61 67 73 20 61 72 49} The flags ar
8ce0: 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 gument to xAcces
8cf0: 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 s() may be [SQLI
8d00: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 TE_ACCESS_EXISTS
8d10: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 ].** to test for
8d20: 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f the existence o
8d30: 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 f a file, or [SQ
8d40: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
8d50: 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 WRITE] to.** tes
8d60: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 t whether a file
8d70: 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 is readable and
8d80: 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 writable, or [S
8d90: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
8da0: 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 D].** to test wh
8db0: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 ether a file is
8dc0: 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c at least readabl
8dd0: 65 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20 66 69 e. {END} The fi
8de0: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 le can be a.** d
8df0: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 irectory..**.**
8e00: 7b 48 31 31 31 35 30 7d 20 53 51 4c 69 74 65 20 {H11150} SQLite
8e10: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f will always allo
8e20: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 cate at least mx
8e30: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 Pathname+1 bytes
8e40: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 for the.** outp
8e50: 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 ut buffer xFullP
8e60: 61 74 68 6e 61 6d 65 2e 20 7b 48 31 31 31 35 31 athname. {H11151
8e70: 7d 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 } The exact size
8e80: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 of the output b
8e90: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f uffer.** is also
8ea0: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 passed as a par
8eb0: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 ameter to both
8ec0: 6d 65 74 68 6f 64 73 2e 20 7b 45 4e 44 7d 20 20 methods. {END}
8ed0: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 If the output bu
8ee0: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c ffer.** is not l
8ef0: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 arge enough, [SQ
8f00: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 LITE_CANTOPEN] s
8f10: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 hould be returne
8f20: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 d. Since this is
8f30: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 .** handled as a
8f40: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 fatal error by
8f50: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c SQLite, vfs impl
8f60: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 ementations shou
8f70: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 ld endeavor.** t
8f80: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 o prevent this b
8f90: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 y setting mxPath
8fa0: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 name to a suffic
8fb0: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c iently large val
8fc0: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 ue..**.** The xR
8fd0: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c andomness(), xSl
8fe0: 65 65 70 28 29 2c 20 61 6e 64 20 78 43 75 72 72 eep(), and xCurr
8ff0: 65 6e 74 54 69 6d 65 28 29 20 69 6e 74 65 72 66 entTime() interf
9000: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 aces.** are not
9010: 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 strictly a part
9020: 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 of the filesyste
9030: 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a m, but they are.
9040: 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 ** included in t
9050: 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65 he VFS structure
9060: 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 for completenes
9070: 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f s..** The xRando
9080: 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e mness() function
9090: 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 attempts to ret
90a0: 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 urn nBytes bytes
90b0: 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c .** of good-qual
90c0: 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 ity randomness i
90d0: 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 nto zOut. The r
90e0: 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a eturn value is.*
90f0: 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d * the actual num
9100: 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 ber of bytes of
9110: 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 randomness obtai
9120: 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 ned..** The xSle
9130: 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 ep() method caus
9140: 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 es the calling t
9150: 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 hread to sleep f
9160: 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 or at.** least t
9170: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 he number of mic
9180: 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e roseconds given.
9190: 20 20 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 The xCurrentTi
91a0: 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 me().** method r
91b0: 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 eturns a Julian
91c0: 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 Day Number for t
91d0: 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 he current date
91e0: 61 6e 64 20 74 69 6d 65 2e 0a 2a 2f 0a 74 79 70 and time..*/.typ
91f0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
9200: 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f te3_vfs sqlite3_
9210: 76 66 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 vfs;.struct sqli
9220: 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 te3_vfs {. int
9230: 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 iVersion;
9240: 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 /* Structur
9250: 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 e version number
9260: 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 */. int szOsFi
9270: 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f le; /
9280: 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 * Size of subcla
9290: 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c ssed sqlite3_fil
92a0: 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 e */. int mxPat
92b0: 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 hname;
92c0: 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 /* Maximum file
92d0: 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 pathname length
92e0: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 */. sqlite3_vfs
92f0: 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a *pNext; /*
9300: 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64 Next registered
9310: 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 VFS */. const
9320: 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 char *zName;
9330: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 /* Name of th
9340: 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 is virtual file
9350: 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 system */. void
9360: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 *pAppData;
9370: 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 /* Pointer
9380: 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 to application-s
9390: 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a pecific data */.
93a0: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 int (*xOpen)(s
93b0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
93c0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
93d0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 sqlite3_file*,.
93e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e in
93f0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f t flags, int *pO
9400: 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 utFlags);. int
9410: 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 (*xDelete)(sqlit
9420: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 e3_vfs*, const c
9430: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 har *zName, int
9440: 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 syncDir);. int
9450: 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 (*xAccess)(sqlit
9460: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 e3_vfs*, const c
9470: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 har *zName, int
9480: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 flags, int *pRes
9490: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 Out);. int (*xF
94a0: 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c ullPathname)(sql
94b0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
94c0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e char *zName, in
94d0: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f t nOut, char *zO
94e0: 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 ut);. void *(*x
94f0: 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f DlOpen)(sqlite3_
9500: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
9510: 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 *zFilename);.
9520: 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 void (*xDlError)
9530: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 (sqlite3_vfs*, i
9540: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a nt nByte, char *
9550: 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 zErrMsg);. void
9560: 20 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 *(*xDlSym)(sqli
9570: 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 te3_vfs*,void*,
9580: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d const char *zSym
9590: 62 6f 6c 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 bol);. void (*x
95a0: 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 DlClose)(sqlite3
95b0: 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 _vfs*, void*);.
95c0: 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 int (*xRandomne
95d0: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ss)(sqlite3_vfs*
95e0: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 , int nByte, cha
95f0: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 r *zOut);. int
9600: 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 (*xSleep)(sqlite
9610: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 3_vfs*, int micr
9620: 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 oseconds);. int
9630: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 (*xCurrentTime)
9640: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 (sqlite3_vfs*, d
9650: 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 ouble*);. int (
9660: 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 *xGetLastError)(
9670: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e sqlite3_vfs*, in
9680: 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a t, char *);. /*
9690: 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 New fields may
96a0: 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 be appended in f
96b0: 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 igure versions.
96c0: 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 The iVersion.
96d0: 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e ** value will in
96e0: 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 crement whenever
96f0: 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 2a this happens. *
9700: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.};../*.** CAPI
9710: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 3REF: Flags for
9720: 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 the xAccess VFS
9730: 6d 65 74 68 6f 64 20 7b 48 31 31 31 39 30 7d 20 method {H11190}
9740: 3c 48 31 31 31 34 30 3e 0a 2a 2a 0a 2a 2a 20 7b <H11140>.**.** {
9750: 48 31 31 31 39 31 7d 20 54 68 65 73 65 20 69 6e H11191} These in
9760: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 teger constants
9770: 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 can be used as t
9780: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
9790: 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 er to.** the xAc
97a0: 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 cess method of a
97b0: 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 n [sqlite3_vfs]
97c0: 6f 62 6a 65 63 74 2e 20 7b 45 4e 44 7d 20 20 54 object. {END} T
97d0: 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a hey determine.**
97e0: 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 what kind of pe
97f0: 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 rmissions the xA
9800: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 ccess method is
9810: 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 looking for..**
9820: 7b 48 31 31 31 39 32 7d 20 57 69 74 68 20 53 51 {H11192} With SQ
9830: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 LITE_ACCESS_EXIS
9840: 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 TS, the xAccess
9850: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 method.** simply
9860: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 checks whether
9870: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e the file exists.
9880: 0a 2a 2a 20 7b 48 31 31 31 39 33 7d 20 57 69 74 .** {H11193} Wit
9890: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f h SQLITE_ACCESS_
98a0: 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 READWRITE, the x
98b0: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a Access method.**
98c0: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 checks whether
98d0: 74 68 65 20 66 69 6c 65 20 69 73 20 62 6f 74 68 the file is both
98e0: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 readable and wr
98f0: 69 74 61 62 6c 65 2e 0a 2a 2a 20 7b 48 31 31 31 itable..** {H111
9900: 39 34 7d 20 57 69 74 68 20 53 51 4c 49 54 45 5f 94} With SQLITE_
9910: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 ACCESS_READ, the
9920: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a xAccess method.
9930: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 ** checks whethe
9940: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 r the file is re
9950: 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 adable..*/.#defi
9960: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 ne SQLITE_ACCESS
9970: 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 _EXISTS 0.#de
9980: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 fine SQLITE_ACCE
9990: 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23 SS_READWRITE 1.#
99a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 define SQLITE_AC
99b0: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 CESS_READ 2
99c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
99d0: 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 : Initialize The
99e0: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 SQLite Library
99f0: 7b 48 31 30 31 33 30 7d 20 3c 53 32 30 30 30 30 {H10130} <S20000
9a00: 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 ><S30100>.**.**
9a10: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 The sqlite3_init
9a20: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 ialize() routine
9a30: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 initializes the
9a40: 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 .** SQLite libra
9a50: 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 ry. The sqlite3
9a60: 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 _shutdown() rout
9a70: 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 ine.** deallocat
9a80: 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 es any resources
9a90: 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 that were alloc
9aa0: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f ated by sqlite3_
9ab0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a initialize()..**
9ac0: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 .** A call to sq
9ad0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
9ae0: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 () is an "effect
9af0: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 ive" call if it
9b00: 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 is.** the first
9b10: 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 time sqlite3_ini
9b20: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 tialize() is inv
9b30: 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 oked during the
9b40: 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 lifetime of.** t
9b50: 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 he process, or i
9b60: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 f it is the firs
9b70: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 t time sqlite3_i
9b80: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 nitialize() is i
9b90: 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 nvoked.** follow
9ba0: 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 ing a call to sq
9bb0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
9bc0: 2e 20 20 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 . Only an effec
9bd0: 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 tive call.** of
9be0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
9bf0: 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e ze() does any in
9c00: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 itialization. A
9c10: 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a ll other calls.*
9c20: 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e * are harmless n
9c30: 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f o-ops..**.** Amo
9c40: 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c ng other things,
9c50: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
9c60: 69 7a 65 28 29 20 73 68 61 6c 6c 20 69 6e 76 6f ize() shall invo
9c70: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 ke.** sqlite3_os
9c80: 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 _init(). Simila
9c90: 72 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 68 75 rly, sqlite3_shu
9ca0: 74 64 6f 77 6e 28 29 0a 2a 2a 20 73 68 61 6c 6c tdown().** shall
9cb0: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f invoke sqlite3_
9cc0: 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 os_end()..**.**
9cd0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 The sqlite3_init
9ce0: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 ialize() routine
9cf0: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
9d00: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e _OK] on success.
9d10: 0a 2a 2a 20 49 66 20 66 6f 72 20 73 6f 6d 65 20 .** If for some
9d20: 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f reason, sqlite3_
9d30: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 initialize() is
9d40: 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 unable to initia
9d50: 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 lize.** the libr
9d60: 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 ary (perhaps it
9d70: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c is unable to all
9d80: 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 ocate a needed r
9d90: 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 esource such.**
9da0: 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 as a mutex) it r
9db0: 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 eturns an [error
9dc0: 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 code] other tha
9dd0: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a n [SQLITE_OK]..*
9de0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
9df0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f _initialize() ro
9e00: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 utine is called
9e10: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 internally by ma
9e20: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 ny other.** SQLi
9e30: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f te interfaces so
9e40: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 that an applica
9e50: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 tion usually doe
9e60: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a s not need to.**
9e70: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f invoke sqlite3_
9e80: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 initialize() dir
9e90: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d ectly. For exam
9ea0: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ple, [sqlite3_op
9eb0: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 en()].** calls s
9ec0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
9ed0: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 e() so the SQLit
9ee0: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 e library will b
9ef0: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a e automatically.
9f00: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 ** initialized w
9f10: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 hen [sqlite3_ope
9f20: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 n()] is called i
9f30: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 f it has not be
9f40: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 initialized.** a
9f50: 6c 72 65 61 64 79 2e 20 20 48 6f 77 65 76 65 72 lready. However
9f60: 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 , if SQLite is c
9f70: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 ompiled with the
9f80: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 [SQLITE_OMIT_AU
9f90: 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 TOINIT].** compi
9fa0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 le-time option,
9fb0: 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 then the automat
9fc0: 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 ic calls to sqli
9fd0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
9fe0: 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 .** are omitted
9ff0: 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 and the applicat
a000: 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 ion must call sq
a010: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
a020: 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 () directly.** p
a030: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e rior to using an
a040: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 y other SQLite i
a050: 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d nterface. For m
a060: 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 aximum portabili
a070: 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 ty,.** it is rec
a080: 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 ommended that ap
a090: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 plications alway
a0a0: 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 s invoke sqlite3
a0b0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a _initialize().**
a0c0: 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 directly prior
a0d0: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 to using any oth
a0e0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 er SQLite interf
a0f0: 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c ace. Future rel
a100: 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 eases.** of SQLi
a110: 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 te may require t
a120: 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 his. In other w
a130: 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 ords, the behavi
a140: 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 or exhibited.**
a150: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 when SQLite is c
a160: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 ompiled with [SQ
a170: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e LITE_OMIT_AUTOIN
a180: 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 IT] might become
a190: 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 the.** default
a1a0: 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 behavior in some
a1b0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 future release
a1c0: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a of SQLite..**.**
a1d0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f The sqlite3_os_
a1e0: 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 init() routine d
a1f0: 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 oes operating-sy
a200: 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a stem specific.**
a210: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 initialization
a220: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 of the SQLite li
a230: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 brary. The sqli
a240: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 te3_os_end().**
a250: 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 routine undoes t
a260: 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c he effect of sql
a270: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 ite3_os_init().
a280: 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a Typical tasks.*
a290: 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 * performed by t
a2a0: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e hese routines in
a2b0: 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e clude allocation
a2c0: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e or deallocation
a2d0: 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 .** of static re
a2e0: 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c sources, initial
a2f0: 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 ization of globa
a300: 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 l variables,.**
a310: 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 setting up a def
a320: 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 ault [sqlite3_vf
a330: 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 s] module, or se
a340: 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 tting up.** a de
a350: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 fault configurat
a360: 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ion using [sqlit
a370: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a e3_config()]..**
a380: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
a390: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 ion should never
a3a0: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 invoke either s
a3b0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
a3c0: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f .** or sqlite3_o
a3d0: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 s_end() directly
a3e0: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 . The applicati
a3f0: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 on should only i
a400: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 nvoke.** sqlite3
a410: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e _initialize() an
a420: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f d sqlite3_shutdo
a430: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 wn(). The sqlit
a440: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 e3_os_init().**
a450: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c interface is cal
a460: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c led automaticall
a470: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 y by sqlite3_ini
a480: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a tialize() and.**
a490: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
a4a0: 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 ) is called by s
a4b0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
a4c0: 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a ). Appropriate.
a4d0: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
a4e0: 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f ns for sqlite3_o
a4f0: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c s_init() and sql
a500: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a ite3_os_end().**
a510: 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 are built into
a520: 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 SQLite when it i
a530: 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 75 s compiled for u
a540: 6e 69 78 2c 20 77 69 6e 64 6f 77 73 2c 20 6f 72 nix, windows, or
a550: 20 6f 73 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 62 os/2..** When b
a560: 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 uilt for other p
a570: 6c 61 74 66 6f 72 6d 73 20 28 75 73 69 6e 67 20 latforms (using
a580: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f the [SQLITE_OS_O
a590: 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d THER=1] compile-
a5a0: 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 time.** option)
a5b0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
a5c0: 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 must supply a su
a5d0: 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 itable implement
a5e0: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c ation for.** sql
a5f0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 ite3_os_init() a
a600: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e nd sqlite3_os_en
a610: 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 d(). An applica
a620: 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a tion-supplied.**
a630: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
a640: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e of sqlite3_os_in
a650: 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f it() or sqlite3_
a660: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 os_end().** must
a670: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
a680: 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 OK] on success a
a690: 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 nd some other [e
a6a0: 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a rror code] upon.
a6b0: 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 ** failure..*/.i
a6c0: 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 nt sqlite3_initi
a6d0: 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 alize(void);.int
a6e0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
a6f0: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c n(void);.int sql
a700: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 ite3_os_init(voi
a710: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f d);.int sqlite3_
a720: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f os_end(void);../
a730: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
a740: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 onfiguring The S
a750: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b 48 QLite Library {H
a760: 31 34 31 30 30 7d 20 3c 53 32 30 30 30 30 3e 3c 14100} <S20000><
a770: 53 33 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 S30200>.** EXPER
a780: 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 IMENTAL.**.** Th
a790: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 e sqlite3_config
a7a0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
a7b0: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f used to make glo
a7c0: 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f bal configuratio
a7d0: 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 n.** changes to
a7e0: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 SQLite in order
a7f0: 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 to tune SQLite t
a800: 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e o the specific n
a810: 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 eeds of.** the a
a820: 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 pplication. The
a830: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 default configu
a840: 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d ration is recomm
a850: 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a ended for most.*
a860: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 * applications a
a870: 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 nd so this routi
a880: 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f ne is usually no
a890: 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 t necessary. It
a8a0: 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 is.** provided
a8b0: 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 to support rare
a8c0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 applications wit
a8d0: 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e h unusual needs.
a8e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
a8f0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 e3_config() inte
a900: 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 rface is not thr
a910: 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 eadsafe. The ap
a920: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 plication.** mus
a930: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f t insure that no
a940: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e other SQLite in
a950: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 terfaces are inv
a960: 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a oked by other.**
a970: 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 threads while s
a980: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
a990: 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 is running. Fur
a9a0: 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 thermore, sqlite
a9b0: 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 3_config().** ma
a9c0: 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 y only be invoke
a9d0: 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 d prior to libra
a9e0: 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f ry initializatio
a9f0: 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 n using.** [sqli
aa00: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
aa10: 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 ] or after shutd
aa20: 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f own by [sqlite3_
aa30: 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 shutdown()]..**
aa40: 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 Note, however, t
aa50: 68 61 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 hat sqlite3_conf
aa60: 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c ig() can be call
aa70: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 ed as part of th
aa80: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e.** implementat
aa90: 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 ion of an applic
aaa0: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 ation-defined [s
aab0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
aac0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 ]..**.** The fir
aad0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 st argument to s
aae0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
aaf0: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a is an integer.**
ab00: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
ab10: 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63 SINGLETHREAD | c
ab20: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
ab30: 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d ion] that determ
ab40: 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f ines.** what pro
ab50: 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 perty of SQLite
ab60: 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 is to be configu
ab70: 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 red. Subsequent
ab80: 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 arguments.** va
ab90: 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 ry depending on
aba0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 the [SQLITE_CONF
abb0: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 IG_SINGLETHREAD
abc0: 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 | configuration
abd0: 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 option].** in th
abe0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
abf0: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 63 ..**.** When a c
ac00: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
ac10: 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 ion is set, sqli
ac20: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 te3_config() ret
ac30: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d urns [SQLITE_OK]
ac40: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 74 69 ..** If the opti
ac50: 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 on is unknown or
ac60: 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c SQLite is unabl
ac70: 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 e to set the opt
ac80: 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 ion.** then this
ac90: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
aca0: 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 a non-zero [err
acb0: 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 or code]..**.**
acc0: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
acd0: 2a 20 7b 48 31 34 31 30 33 7d 20 41 20 73 75 63 * {H14103} A suc
ace0: 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 cessful invocati
acf0: 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 63 on of [sqlite3_c
ad00: 6f 6e 66 69 67 28 29 5d 20 73 68 61 6c 6c 20 72 onfig()] shall r
ad10: 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 eturn.**
ad20: 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a [SQLITE_OK]..*
ad30: 2a 0a 2a 2a 20 7b 48 31 34 31 30 36 7d 20 54 68 *.** {H14106} Th
ad40: 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 e [sqlite3_confi
ad50: 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 g()] interface s
ad60: 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c hall return [SQL
ad70: 49 54 45 5f 4d 49 53 55 53 45 5d 0a 2a 2a 20 20 ITE_MISUSE].**
ad80: 20 20 20 20 20 20 20 20 69 66 20 69 74 20 69 73 if it is
ad90: 20 69 6e 76 6f 6b 65 64 20 69 6e 20 62 65 74 77 invoked in betw
ada0: 65 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 een calls to [sq
adb0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
adc0: 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 ()] and.**
add0: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 [sqlite3_shu
ade0: 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 tdown()]..**.**
adf0: 7b 48 31 34 31 32 30 7d 20 41 20 73 75 63 63 65 {H14120} A succe
ae00: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 ssful call to [s
ae10: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b qlite3_config]([
ae20: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 SQLITE_CONFIG_SI
ae30: 4e 47 4c 45 54 48 52 45 41 44 5d 29 0a 2a 2a 20 NGLETHREAD]).**
ae40: 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 73 shall s
ae50: 65 74 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b et the default [
ae60: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
ae70: 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 to Single-thread
ae80: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 32 33 7d ..**.** {H14123}
ae90: 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 A successful ca
aea0: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ll to [sqlite3_c
aeb0: 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 onfig]([SQLITE_C
aec0: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 ONFIG_MULTITHREA
aed0: 44 5d 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 D]).**
aee0: 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 64 65 shall set the de
aef0: 66 61 75 6c 74 20 5b 74 68 72 65 61 64 69 6e 67 fault [threading
af00: 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d mode] to Multi-
af10: 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 thread..**.** {H
af20: 31 34 31 32 36 7d 20 41 20 73 75 63 63 65 73 73 14126} A success
af30: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ful call to [sql
af40: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 ite3_config]([SQ
af50: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 LITE_CONFIG_SERI
af60: 41 4c 49 5a 45 44 5d 29 0a 2a 2a 20 20 20 20 20 ALIZED]).**
af70: 20 20 20 20 20 73 68 61 6c 6c 20 73 65 74 20 74 shall set t
af80: 68 65 20 64 65 66 61 75 6c 74 20 5b 74 68 72 65 he default [thre
af90: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 ading mode] to S
afa0: 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a erialized..**.**
afb0: 20 7b 48 31 34 31 32 39 7d 20 41 20 73 75 63 63 {H14129} A succ
afc0: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b essful call to [
afd0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 sqlite3_config](
afe0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
aff0: 55 54 45 58 5d 2c 58 29 0a 2a 2a 20 20 20 20 20 UTEX],X).**
b000: 20 20 20 20 20 77 68 65 72 65 20 58 20 69 73 20 where X is
b010: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
b020: 69 6e 69 74 69 61 6c 69 7a 65 64 20 5b 73 71 6c initialized [sql
b030: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
b040: 64 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ds].**
b050: 6f 62 6a 65 63 74 20 73 68 61 6c 6c 20 63 61 75 object shall cau
b060: 73 65 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e se all subsequen
b070: 74 20 6d 75 74 65 78 20 6f 70 65 72 61 74 69 6f t mutex operatio
b080: 6e 73 20 70 65 72 66 6f 72 6d 65 64 0a 2a 2a 20 ns performed.**
b090: 20 20 20 20 20 20 20 20 20 62 79 20 53 51 4c 69 by SQLi
b0a0: 74 65 20 74 6f 20 75 73 65 20 74 68 65 20 6d 75 te to use the mu
b0b0: 74 65 78 20 6d 65 74 68 6f 64 73 20 74 68 61 74 tex methods that
b0c0: 20 77 65 72 65 20 70 72 65 73 65 6e 74 20 69 6e were present in
b0d0: 20 58 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 X.** d
b0e0: 75 72 69 6e 67 20 74 68 65 20 63 61 6c 6c 20 74 uring the call t
b0f0: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 o [sqlite3_confi
b100: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 g()]..**.** {H14
b110: 31 33 32 7d 20 41 20 73 75 63 63 65 73 73 66 75 132} A successfu
b120: 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 l call to [sqlit
b130: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 e3_config]([SQLI
b140: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 TE_CONFIG_GETMUT
b150: 45 58 5d 2c 58 29 0a 2a 2a 20 20 20 20 20 20 20 EX],X).**
b160: 20 20 20 77 68 65 72 65 20 58 20 69 73 20 61 20 where X is a
b170: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 pointer to an [s
b180: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
b190: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 0a 2a 2a hods] object .**
b1a0: 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 shall
b1b0: 6f 76 65 72 77 72 69 74 65 20 74 68 65 20 63 6f overwrite the co
b1c0: 6e 74 65 6e 74 20 6f 66 20 5b 73 71 6c 69 74 65 ntent of [sqlite
b1d0: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 3_mutex_methods]
b1e0: 20 6f 62 6a 65 63 74 0a 2a 2a 20 20 20 20 20 20 object.**
b1f0: 20 20 20 20 77 69 74 68 20 74 68 65 20 6d 75 74 with the mut
b200: 65 78 20 6d 65 74 68 6f 64 73 20 63 75 72 72 65 ex methods curre
b210: 6e 74 6c 79 20 69 6e 20 75 73 65 20 62 79 20 53 ntly in use by S
b220: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 QLite..**.** {H1
b230: 34 31 33 35 7d 20 41 20 73 75 63 63 65 73 73 66 4135} A successf
b240: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 ul call to [sqli
b250: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c te3_config]([SQL
b260: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f ITE_CONFIG_MALLO
b270: 43 5d 2c 4d 29 0a 2a 2a 20 20 20 20 20 20 20 20 C],M).**
b280: 20 20 77 68 65 72 65 20 4d 20 69 73 20 61 20 70 where M is a p
b290: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 69 ointer to an ini
b2a0: 74 69 61 6c 69 7a 65 64 20 5b 73 71 6c 69 74 65 tialized [sqlite
b2b0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 3_mem_methods].*
b2c0: 2a 20 20 20 20 20 20 20 20 20 20 6f 62 6a 65 63 * objec
b2d0: 74 20 73 68 61 6c 6c 20 63 61 75 73 65 20 61 6c t shall cause al
b2e0: 6c 20 73 75 62 73 65 71 75 65 6e 74 20 6d 65 6d l subsequent mem
b2f0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f ory allocation o
b300: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 20 20 20 perations.**
b310: 20 20 20 20 20 20 70 65 72 66 6f 72 6d 65 64 20 performed
b320: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 by SQLite to use
b330: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 74 68 61 the methods tha
b340: 74 20 77 65 72 65 20 70 72 65 73 65 6e 74 20 69 t were present i
b350: 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4d n .** M
b360: 20 64 75 72 69 6e 67 20 74 68 65 20 63 61 6c 6c during the call
b370: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e to [sqlite3_con
b380: 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 fig()]..**.** {H
b390: 31 34 31 33 38 7d 20 41 20 73 75 63 63 65 73 73 14138} A success
b3a0: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ful call to [sql
b3b0: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 ite3_config]([SQ
b3c0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
b3d0: 41 4c 4c 4f 43 5d 2c 4d 29 0a 2a 2a 20 20 20 20 ALLOC],M).**
b3e0: 20 20 20 20 20 20 77 68 65 72 65 20 4d 20 69 73 where M is
b3f0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
b400: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 [sqlite3_mem_me
b410: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 73 68 thods] object sh
b420: 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 all.**
b430: 6f 76 65 72 77 72 69 74 65 20 74 68 65 20 63 6f overwrite the co
b440: 6e 74 65 6e 74 20 6f 66 20 5b 73 71 6c 69 74 65 ntent of [sqlite
b450: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 6f 3_mem_methods] o
b460: 62 6a 65 63 74 20 77 69 74 68 20 0a 2a 2a 20 20 bject with .**
b470: 20 20 20 20 20 20 20 20 74 68 65 20 6d 65 6d 6f the memo
b480: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6d 65 ry allocation me
b490: 74 68 6f 64 73 20 63 75 72 72 65 6e 74 6c 79 20 thods currently
b4a0: 69 6e 20 75 73 65 20 62 79 0a 2a 2a 20 20 20 20 in use by.**
b4b0: 20 20 20 20 20 20 53 51 4c 69 74 65 2e 0a 2a 2a SQLite..**
b4c0: 0a 2a 2a 20 7b 48 31 34 31 34 31 7d 20 41 20 73 .** {H14141} A s
b4d0: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 uccessful call t
b4e0: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 o [sqlite3_confi
b4f0: 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 g]([SQLITE_CONFI
b500: 47 5f 4d 45 4d 53 54 41 54 55 53 5d 2c 31 29 0a G_MEMSTATUS],1).
b510: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c ** shal
b520: 6c 20 65 6e 61 62 6c 65 20 74 68 65 20 6d 65 6d l enable the mem
b530: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 ory allocation s
b540: 74 61 74 75 73 20 63 6f 6c 6c 65 63 74 69 6f 6e tatus collection
b550: 20 6c 6f 67 69 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48 logic..**.** {H
b560: 31 34 31 34 34 7d 20 41 20 73 75 63 63 65 73 73 14144} A success
b570: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ful call to [sql
b580: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 ite3_config]([SQ
b590: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 LITE_CONFIG_MEMS
b5a0: 54 41 54 55 53 5d 2c 30 29 0a 2a 2a 20 20 20 20 TATUS],0).**
b5b0: 20 20 20 20 20 20 73 68 61 6c 6c 20 64 69 73 61 shall disa
b5c0: 62 6c 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 ble the memory a
b5d0: 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 75 73 llocation status
b5e0: 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6c 6f 67 69 collection logi
b5f0: 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 34 37 c..**.** {H14147
b600: 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c } The memory all
b610: 6f 63 61 74 69 6f 6e 20 73 74 61 74 75 73 20 63 ocation status c
b620: 6f 6c 6c 65 63 74 69 6f 6e 20 6c 6f 67 69 63 20 ollection logic
b630: 73 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 20 shall be.**
b640: 20 20 20 20 20 65 6e 61 62 6c 65 64 20 62 79 20 enabled by
b650: 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b default..**.** {
b660: 48 31 34 31 35 30 7d 20 41 20 73 75 63 63 65 73 H14150} A succes
b670: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 sful call to [sq
b680: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 lite3_config]([S
b690: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 QLITE_CONFIG_SCR
b6a0: 41 54 43 48 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20 ATCH],S,Z,N).**
b6b0: 20 20 20 20 20 20 20 20 20 77 68 65 72 65 20 5a where Z
b6c0: 20 61 6e 64 20 4e 20 61 72 65 20 6e 6f 6e 2d 6e and N are non-n
b6d0: 65 67 61 74 69 76 65 20 69 6e 74 65 67 65 72 73 egative integers
b6e0: 20 61 6e 64 20 0a 2a 2a 20 20 20 20 20 20 20 20 and .**
b6f0: 20 20 53 20 69 73 20 61 20 70 6f 69 6e 74 65 72 S is a pointer
b700: 20 74 6f 20 61 6e 20 61 6c 69 67 6e 65 64 20 6d to an aligned m
b710: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 6e 6f 74 emory buffer not
b720: 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 less than.**
b730: 20 20 20 20 20 20 20 5a 2a 4e 20 62 79 74 65 73 Z*N bytes
b740: 20 69 6e 20 73 69 7a 65 20 73 68 61 6c 6c 20 63 in size shall c
b750: 61 75 73 65 20 53 20 74 6f 20 62 65 20 75 73 65 ause S to be use
b760: 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 d by the.**
b770: 20 20 20 20 20 5b 73 63 72 61 74 63 68 20 6d 65 [scratch me
b780: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 mory allocator]
b790: 66 6f 72 20 61 73 20 6d 61 6e 79 20 61 73 20 4e for as many as N
b7a0: 20 73 69 6d 75 6c 61 74 61 6e 65 6f 75 73 0a 2a simulataneous.*
b7b0: 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 * alloc
b7c0: 61 74 69 6f 6e 73 20 65 61 63 68 20 6f 66 20 73 ations each of s
b7d0: 69 7a 65 20 5a 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ize Z..**.** {H1
b7e0: 34 31 35 33 7d 20 41 20 73 75 63 63 65 73 73 66 4153} A successf
b7f0: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 ul call to [sqli
b800: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c te3_config]([SQL
b810: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 ITE_CONFIG_SCRAT
b820: 43 48 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 CH],S,Z,N).**
b830: 20 20 20 20 20 20 20 77 68 65 72 65 20 53 20 69 where S i
b840: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
b850: 20 73 68 61 6c 6c 20 64 69 73 61 62 6c 65 20 74 shall disable t
b860: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b he.** [
b870: 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 scratch memory a
b880: 6c 6c 6f 63 61 74 6f 72 5d 2e 0a 2a 2a 0a 2a 2a llocator]..**.**
b890: 20 7b 48 31 34 31 35 36 7d 20 41 20 73 75 63 63 {H14156} A succ
b8a0: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 0a 2a essful call to.*
b8b0: 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
b8c0: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c te3_config]([SQL
b8d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 ITE_CONFIG_PAGEC
b8e0: 41 43 48 45 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20 ACHE],S,Z,N).**
b8f0: 20 20 20 20 20 20 20 20 20 77 68 65 72 65 20 5a where Z
b900: 20 61 6e 64 20 4e 20 61 72 65 20 6e 6f 6e 2d 6e and N are non-n
b910: 65 67 61 74 69 76 65 20 69 6e 74 65 67 65 72 73 egative integers
b920: 20 61 6e 64 20 0a 2a 2a 20 20 20 20 20 20 20 20 and .**
b930: 20 20 53 20 69 73 20 61 20 70 6f 69 6e 74 65 72 S is a pointer
b940: 20 74 6f 20 61 6e 20 61 6c 69 67 6e 65 64 20 6d to an aligned m
b950: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 6e 6f 74 emory buffer not
b960: 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 less than.**
b970: 20 20 20 20 20 20 20 5a 2a 4e 20 62 79 74 65 73 Z*N bytes
b980: 20 69 6e 20 73 69 7a 65 20 73 68 61 6c 6c 20 63 in size shall c
b990: 61 75 73 65 20 53 20 74 6f 20 62 65 20 75 73 65 ause S to be use
b9a0: 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 d by the.**
b9b0: 20 20 20 20 20 5b 70 61 67 65 63 61 63 68 65 20 [pagecache
b9c0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
b9d0: 5d 20 66 6f 72 20 61 73 20 6d 61 6e 79 20 61 73 ] for as many as
b9e0: 20 4e 20 73 69 6d 75 6c 61 74 61 6e 65 6f 75 73 N simulataneous
b9f0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c .** all
ba00: 6f 63 61 74 69 6f 6e 73 20 65 61 63 68 20 6f 66 ocations each of
ba10: 20 73 69 7a 65 20 5a 2e 0a 2a 2a 0a 2a 2a 20 7b size Z..**.** {
ba20: 48 31 34 31 35 39 7d 20 41 20 73 75 63 63 65 73 H14159} A succes
ba30: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 sful call to.**
ba40: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
ba50: 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 3_config]([SQLIT
ba60: 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 E_CONFIG_PAGECAC
ba70: 48 45 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 HE],S,Z,N).**
ba80: 20 20 20 20 20 20 20 77 68 65 72 65 20 53 20 69 where S i
ba90: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
baa0: 20 73 68 61 6c 6c 20 64 69 73 61 62 6c 65 20 74 shall disable t
bab0: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b he.** [
bac0: 70 61 67 65 63 61 63 68 65 20 6d 65 6d 6f 72 79 pagecache memory
bad0: 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e 0a 2a 2a 0a allocator]..**.
bae0: 2a 2a 20 7b 48 31 34 31 36 32 7d 20 41 20 73 75 ** {H14162} A su
baf0: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f ccessful call to
bb00: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
bb10: 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ]([SQLITE_CONFIG
bb20: 5f 48 45 41 50 5d 2c 48 2c 5a 2c 4e 29 0a 2a 2a _HEAP],H,Z,N).**
bb30: 20 20 20 20 20 20 20 20 20 20 77 68 65 72 65 20 where
bb40: 5a 20 61 6e 64 20 4e 20 61 72 65 20 6e 6f 6e 2d Z and N are non-
bb50: 6e 65 67 61 74 69 76 65 20 69 6e 74 65 67 65 72 negative integer
bb60: 73 20 61 6e 64 20 0a 2a 2a 20 20 20 20 20 20 20 s and .**
bb70: 20 20 20 48 20 69 73 20 61 20 70 6f 69 6e 74 65 H is a pointe
bb80: 72 20 74 6f 20 61 6e 20 61 6c 69 67 6e 65 64 20 r to an aligned
bb90: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 6e 6f memory buffer no
bba0: 74 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 t less than.**
bbb0: 20 20 20 20 20 20 20 20 5a 20 62 79 74 65 73 20 Z bytes
bbc0: 69 6e 20 73 69 7a 65 20 73 68 61 6c 6c 20 65 6e in size shall en
bbd0: 61 62 6c 65 20 74 68 65 20 5b 6d 65 6d 73 79 73 able the [memsys
bbe0: 35 5d 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 5] memory alloca
bbf0: 74 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 tor.**
bc00: 61 6e 64 20 63 61 75 73 65 20 69 74 20 74 6f 20 and cause it to
bc10: 75 73 65 20 62 75 66 66 65 72 20 53 20 61 73 20 use buffer S as
bc20: 69 74 73 20 6d 65 6d 6f 72 79 20 73 6f 75 72 63 its memory sourc
bc30: 65 20 61 6e 64 20 74 6f 20 75 73 65 0a 2a 2a 20 e and to use.**
bc40: 20 20 20 20 20 20 20 20 20 61 20 6d 69 6e 69 6d a minim
bc50: 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 um allocation si
bc60: 7a 65 20 6f 66 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b ze of N..**.** {
bc70: 48 31 34 31 36 35 7d 20 41 20 73 75 63 63 65 73 H14165} A succes
bc80: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 sful call to [sq
bc90: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 lite3_config]([S
bca0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 QLITE_CONFIG_HEA
bcb0: 50 5d 2c 48 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 20 P],H,Z,N).**
bcc0: 20 20 20 20 20 20 77 68 65 72 65 20 48 20 69 73 where H is
bcd0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
bce0: 73 68 61 6c 6c 20 64 69 73 61 62 6c 65 20 74 68 shall disable th
bcf0: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 6d e.** [m
bd00: 65 6d 73 79 73 35 5d 20 6d 65 6d 6f 72 79 20 61 emsys5] memory a
bd10: 6c 6c 6f 63 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 llocator..**.**
bd20: 7b 48 31 34 31 36 38 7d 20 41 20 73 75 63 63 65 {H14168} A succe
bd30: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 ssful call to [s
bd40: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b qlite3_config]([
bd50: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f SQLITE_CONFIG_LO
bd60: 4f 4b 41 53 49 44 45 5d 2c 5a 2c 4e 29 0a 2a 2a OKASIDE],Z,N).**
bd70: 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 shall
bd80: 63 61 75 73 65 20 74 68 65 20 64 65 66 61 75 6c cause the defaul
bd90: 74 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d t [lookaside mem
bda0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 ory allocator] c
bdb0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 onfiguration.**
bdc0: 20 20 20 20 20 20 20 20 20 66 6f 72 20 6e 65 77 for new
bdd0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
bde0: 63 74 69 6f 6e 73 5d 20 74 6f 20 62 65 20 4e 20 ctions] to be N
bdf0: 73 6c 6f 74 73 20 6f 66 20 5a 20 62 79 74 65 73 slots of Z bytes
be00: 20 65 61 63 68 2e 0a 2a 2f 0a 53 51 4c 49 54 45 each..*/.SQLITE
be10: 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e _EXPERIMENTAL in
be20: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 t sqlite3_config
be30: 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a (int, ...);../*.
be40: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e ** CAPI3REF: Con
be50: 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20 figure database
be60: 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 20 7b 48 31 connections {H1
be70: 34 32 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 4200} <S20000>.*
be80: 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
be90: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
bea0: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 _db_config() int
beb0: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 erface is used t
bec0: 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 o make configura
bed0: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 tion.** changes
bee0: 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 to a [database c
bef0: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 onnection]. The
bf00: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 interface is si
bf10: 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c milar to.** [sql
bf20: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 ite3_config()] e
bf30: 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 xcept that the c
bf40: 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 hanges apply to
bf50: 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 a single.** [dat
bf60: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
bf70: 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 ] (specified in
bf80: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
bf90: 6e 74 29 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c nt). The.** sql
bfa0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
bfb0: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 6f interface can o
bfc0: 6e 6c 79 20 62 65 20 75 73 65 64 20 69 6d 6d 65 nly be used imme
bfd0: 64 69 61 74 65 6c 79 20 61 66 74 65 72 0a 2a 2a diately after.**
bfe0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
bff0: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 72 65 61 nnection is crea
c000: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ted using [sqlit
c010: 65 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b e3_open()],.** [
c020: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
c030: 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f ], or [sqlite3_o
c040: 70 65 6e 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a pen_v2()]. .**.
c050: 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 ** The second ar
c060: 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 gument to sqlite
c070: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 3_db_config(D,V,
c080: 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 ...) is the.**
c090: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 configuration ve
c0a0: 72 62 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 rb - an integer
c0b0: 63 6f 64 65 20 74 68 61 74 20 69 6e 64 69 63 61 code that indica
c0c0: 74 65 73 20 77 68 61 74 0a 2a 2a 20 61 73 70 65 tes what.** aspe
c0d0: 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 ct of the [datab
c0e0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
c0f0: 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 is being configu
c100: 72 65 64 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 red..** The only
c110: 20 63 68 6f 69 63 65 20 66 6f 72 20 74 68 69 73 choice for this
c120: 20 76 61 6c 75 65 20 69 73 20 5b 53 51 4c 49 54 value is [SQLIT
c130: 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 E_DBCONFIG_LOOKA
c140: 53 49 44 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 SIDE]..** New ve
c150: 72 62 73 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 rbs are likely t
c160: 6f 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 o be added in fu
c170: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 ture releases of
c180: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 41 64 64 69 SQLite..** Addi
c190: 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 tional arguments
c1a0: 20 64 65 70 65 6e 64 20 6f 6e 20 74 68 65 20 76 depend on the v
c1b0: 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 erb..**.** INVAR
c1c0: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 IANTS:.**.** {H1
c1d0: 34 32 30 33 7d 20 41 20 63 61 6c 6c 20 74 6f 20 4203} A call to
c1e0: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 [sqlite3_db_conf
c1f0: 69 67 28 44 2c 56 2c 2e 2e 2e 29 5d 20 73 68 61 ig(D,V,...)] sha
c200: 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 ll return [SQLIT
c210: 45 5f 4f 4b 5d 0a 2a 2a 20 20 20 20 20 20 20 20 E_OK].**
c220: 20 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 if and only if
c230: 20 74 68 65 20 63 61 6c 6c 20 69 73 20 73 75 63 the call is suc
c240: 63 65 73 73 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 7b cessful..**.** {
c250: 48 31 34 32 30 36 7d 20 49 66 20 6f 6e 65 20 6f H14206} If one o
c260: 72 20 6d 6f 72 65 20 73 6c 6f 74 73 20 6f 66 20 r more slots of
c270: 74 68 65 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d the [lookaside m
c280: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d emory allocator]
c290: 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 for.**
c2a0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
c2b0: 63 74 69 6f 6e 5d 20 44 20 61 72 65 20 69 6e 20 ction] D are in
c2c0: 75 73 65 2c 20 74 68 65 6e 20 61 20 63 61 6c 6c use, then a call
c2d0: 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 to.**
c2e0: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 [sqlite3_db_conf
c2f0: 69 67 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 44 42 ig](D,[SQLITE_DB
c300: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
c310: 5d 2c 2e 2e 2e 29 20 73 68 61 6c 6c 0a 2a 2a 20 ],...) shall.**
c320: 20 20 20 20 20 20 20 20 20 66 61 69 6c 20 77 69 fail wi
c330: 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 th an [SQLITE_BU
c340: 53 59 5d 20 72 65 74 75 72 6e 20 63 6f 64 65 2e SY] return code.
c350: 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 32 30 39 7d 20 .**.** {H14209}
c360: 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c A successful cal
c370: 6c 20 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20 l to .**
c380: 20 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f [sqlite3_db_co
c390: 6e 66 69 67 5d 28 44 2c 5b 53 51 4c 49 54 45 5f nfig](D,[SQLITE_
c3a0: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 DBCONFIG_LOOKASI
c3b0: 44 45 5d 2c 42 2c 5a 2c 4e 29 20 77 68 65 72 65 DE],B,Z,N) where
c3c0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 44 20 69 .** D i
c3d0: 73 20 61 6e 20 6f 70 65 6e 20 5b 64 61 74 61 62 s an open [datab
c3e0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
c3f0: 61 6e 64 20 5a 20 61 6e 64 20 4e 20 61 72 65 20 and Z and N are
c400: 70 6f 73 69 74 69 76 65 0a 2a 2a 20 20 20 20 20 positive.**
c410: 20 20 20 20 20 69 6e 74 65 67 65 72 73 20 61 6e integers an
c420: 64 20 42 20 69 73 20 61 6e 20 61 6c 69 67 6e 65 d B is an aligne
c430: 64 20 62 75 66 66 65 72 20 61 74 20 6c 65 61 73 d buffer at leas
c440: 74 20 5a 2a 4e 20 62 79 74 65 73 20 69 6e 20 73 t Z*N bytes in s
c450: 69 7a 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ize.**
c460: 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20 shall cause the
c470: 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 [lookaside memor
c480: 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 66 6f 72 y allocator] for
c490: 20 44 20 74 6f 20 75 73 65 20 62 75 66 66 65 72 D to use buffer
c4a0: 20 42 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 B .**
c4b0: 77 69 74 68 20 4e 20 73 6c 6f 74 73 20 6f 66 20 with N slots of
c4c0: 5a 20 62 79 74 65 73 20 65 61 63 68 2e 0a 2a 2a Z bytes each..**
c4d0: 0a 2a 2a 20 7b 48 31 34 32 31 32 7d 20 41 20 73 .** {H14212} A s
c4e0: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 uccessful call t
c4f0: 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b o .** [
c500: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
c510: 67 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 44 42 43 g](D,[SQLITE_DBC
c520: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d ONFIG_LOOKASIDE]
c530: 2c 42 2c 5a 2c 4e 29 20 77 68 65 72 65 0a 2a 2a ,B,Z,N) where.**
c540: 20 20 20 20 20 20 20 20 20 20 44 20 69 73 20 61 D is a
c550: 6e 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 n open [database
c560: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 connection] and
c570: 20 5a 20 61 6e 64 20 4e 20 61 72 65 20 70 6f 73 Z and N are pos
c580: 69 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 itive.**
c590: 20 20 69 6e 74 65 67 65 72 73 20 61 6e 64 20 42 integers and B
c5a0: 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 is NULL pointer
c5b0: 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65 shall cause the
c5c0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 6c 6f .** [lo
c5d0: 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 okaside memory a
c5e0: 6c 6c 6f 63 61 74 6f 72 5d 20 66 6f 72 20 44 20 llocator] for D
c5f0: 74 6f 20 61 20 6f 62 74 61 69 6e 20 5a 2a 4e 20 to a obtain Z*N
c600: 62 79 74 65 20 62 75 66 66 65 72 0a 2a 2a 20 20 byte buffer.**
c610: 20 20 20 20 20 20 20 20 66 72 6f 6d 20 74 68 65 from the
c620: 20 70 72 69 6d 61 72 79 20 6d 65 6d 6f 72 79 20 primary memory
c630: 61 6c 6c 6f 63 61 74 6f 72 20 61 6e 64 20 75 73 allocator and us
c640: 65 20 74 68 61 74 20 62 75 66 66 65 72 0a 2a 2a e that buffer.**
c650: 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20 4e with N
c660: 20 6c 6f 6f 6b 61 73 69 64 65 20 73 6c 6f 74 73 lookaside slots
c670: 20 6f 66 20 5a 20 62 79 74 65 73 20 65 61 63 68 of Z bytes each
c680: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 32 31 35 7d ..**.** {H14215}
c690: 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 A successful ca
c6a0: 6c 6c 20 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20 ll to .**
c6b0: 20 20 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 [sqlite3_db_c
c6c0: 6f 6e 66 69 67 5d 28 44 2c 5b 53 51 4c 49 54 45 onfig](D,[SQLITE
c6d0: 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 _DBCONFIG_LOOKAS
c6e0: 49 44 45 5d 2c 42 2c 5a 2c 4e 29 20 77 68 65 72 IDE],B,Z,N) wher
c6f0: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 44 20 e.** D
c700: 69 73 20 61 6e 20 6f 70 65 6e 20 5b 64 61 74 61 is an open [data
c710: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
c720: 20 61 6e 64 20 5a 20 61 6e 64 20 4e 20 61 72 65 and Z and N are
c730: 20 7a 65 72 6f 20 73 68 61 6c 6c 0a 2a 2a 20 20 zero shall.**
c740: 20 20 20 20 20 20 20 20 64 69 73 61 62 6c 65 20 disable
c750: 74 68 65 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d the [lookaside m
c760: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d emory allocator]
c770: 20 66 6f 72 20 44 2e 0a 2a 2a 0a 2a 2a 0a 2a 2f for D..**.**.*/
c780: 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 .SQLITE_EXPERIME
c790: 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 NTAL int sqlite3
c7a0: 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 _db_config(sqlit
c7b0: 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e e3*, int op, ...
c7c0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
c7d0: 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 EF: Memory Alloc
c7e0: 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b ation Routines {
c7f0: 48 31 30 31 35 35 7d 20 3c 53 32 30 31 32 30 3e H10155} <S20120>
c800: 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c .** EXPERIMENTAL
c810: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e .**.** An instan
c820: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 ce of this objec
c830: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e t defines the in
c840: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 terface between
c850: 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f SQLite.** and lo
c860: 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 w-level memory a
c870: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e llocation routin
c880: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f es..**.** This o
c890: 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e bject is used in
c8a0: 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 only one place
c8b0: 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e in the SQLite in
c8c0: 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f terface..** A po
c8d0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 inter to an inst
c8e0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a ance of this obj
c8f0: 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d ect is the argum
c900: 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 ent to.** [sqlit
c910: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 e3_config()] whe
c920: 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 n the configurat
c930: 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a ion option is.**
c940: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
c950: 4d 41 4c 4c 4f 43 5d 2e 20 20 42 79 20 63 72 65 MALLOC]. By cre
c960: 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 ating an instanc
c970: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 e of this object
c980: 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 .** and passing
c990: 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 it to [sqlite3_c
c9a0: 6f 6e 66 69 67 28 29 5d 20 64 75 72 69 6e 67 20 onfig()] during
c9b0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 configuration, a
c9c0: 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e n.** application
c9d0: 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 can specify an
c9e0: 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f alternative memo
c9f0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 ry allocation su
ca00: 62 73 79 73 74 65 6d 0a 2a 2a 20 66 6f 72 20 53 bsystem.** for S
ca10: 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 QLite to use for
ca20: 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 all of its dyna
ca30: 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 mic memory needs
ca40: 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ..**.** Note tha
ca50: 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 t SQLite comes w
ca60: 69 74 68 20 61 20 62 75 69 6c 74 2d 69 6e 20 6d ith a built-in m
ca70: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 emory allocator
ca80: 74 68 61 74 20 69 73 0a 2a 2a 20 70 65 72 66 65 that is.** perfe
ca90: 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f ctly adequate fo
caa0: 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 r the overwhelmi
cab0: 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 ng majority of a
cac0: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 pplications.** a
cad0: 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a nd that this obj
cae0: 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 ect is only usef
caf0: 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e ul to a tiny min
cb00: 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 ority of applica
cb10: 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 tions.** with sp
cb20: 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 ecialized memory
cb30: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 allocation requ
cb40: 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 irements. This
cb50: 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 object is.** als
cb60: 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 o used during te
cb70: 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 sting of SQLite
cb80: 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 in order to spec
cb90: 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 ify an alternati
cba0: 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c ve.** memory all
cbb0: 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 ocator that simu
cbc0: 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 lates memory out
cbd0: 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 -of-memory condi
cbe0: 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 tions in.** orde
cbf0: 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 r to verify that
cc00: 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 SQLite recovers
cc10: 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d gracefully from
cc20: 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 such.** conditi
cc30: 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ons..**.** The x
cc40: 4d 61 6c 6c 6f 63 2c 20 78 46 72 65 65 2c 20 61 Malloc, xFree, a
cc50: 6e 64 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68 nd xRealloc meth
cc60: 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 ods must work li
cc70: 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 ke the.** malloc
cc80: 28 29 2c 20 66 72 65 65 28 29 2c 20 61 6e 64 20 (), free(), and
cc90: 72 65 61 6c 6c 6f 63 28 29 20 66 75 6e 63 74 69 realloc() functi
cca0: 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 ons from the sta
ccb0: 6e 64 61 72 64 20 6c 69 62 72 61 72 79 2e 0a 2a ndard library..*
ccc0: 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c *.** xSize shoul
ccd0: 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c d return the all
cce0: 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 ocated size of a
ccf0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
cd00: 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 on.** previously
cd10: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 obtained from x
cd20: 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c Malloc or xReall
cd30: 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 oc. The allocat
cd40: 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c ed size.** is al
cd50: 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 ways at least as
cd60: 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75 big as the requ
cd70: 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d ested size but m
cd80: 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a ay be larger..**
cd90: 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 .** The xRoundup
cda0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 method returns
cdb0: 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 what would be th
cdc0: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 e allocated size
cdd0: 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 of.** a memory
cde0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e allocation given
cdf0: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 a particular re
ce00: 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d quested size. M
ce10: 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c ost memory.** al
ce20: 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 locators round u
ce30: 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 p memory allocat
ce40: 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f ions at least to
ce50: 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 the next multip
ce60: 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d le.** of 8. Som
ce70: 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 e allocators rou
ce80: 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 nd up to a large
ce90: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f r multiple or to
cea0: 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a a power of 2..*
ceb0: 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d *.** The xInit m
cec0: 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 ethod initialize
ced0: 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c s the memory all
cee0: 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 ocator. (For ex
cef0: 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 ample,.** it mig
cf00: 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 ht allocate any
cf10: 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 require mutexes
cf20: 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e or initialize in
cf30: 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 ternal data.** s
cf40: 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 tructures. The
cf50: 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 xShutdown method
cf60: 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 is invoked (ind
cf70: 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b irectly) by.** [
cf80: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
cf90: 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 ()] and should d
cfa0: 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 eallocate any re
cfb0: 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 sources acquired
cfc0: 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 .** by xInit. T
cfd0: 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e he pAppData poin
cfe0: 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 ter is used as t
cff0: 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 he only paramete
d000: 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e r to.** xInit an
d010: 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2f 0a d xShutdown..*/.
d020: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
d030: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
d040: 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d ds sqlite3_mem_m
d050: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 ethods;.struct s
d060: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
d070: 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 ds {. void *(*x
d080: 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 Malloc)(int);
d090: 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 /* Memory
d0a0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 allocation funct
d0b0: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a ion */. void (*
d0c0: 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 xFree)(void*);
d0d0: 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 /* Free
d0e0: 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 a prior allocati
d0f0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a on */. void *(*
d100: 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c xRealloc)(void*,
d110: 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 int); /* Resize
d120: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a an allocation *
d130: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 /. int (*xSize)
d140: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 (void*);
d150: 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 /* Return the
d160: 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f size of an allo
d170: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 cation */. int
d180: 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 (*xRoundup)(int)
d190: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f ; /* Ro
d1a0: 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 und up request s
d1b0: 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f ize to allocatio
d1c0: 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 n size */. int
d1d0: 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b (*xInit)(void*);
d1e0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e /* In
d1f0: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d itialize the mem
d200: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f ory allocator */
d210: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 . void (*xShutd
d220: 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 own)(void*);
d230: 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a /* Deinitializ
d240: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c e the memory all
d250: 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 ocator */. void
d260: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 *pAppData;
d270: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 /* Ar
d280: 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 gument to xInit(
d290: 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 ) and xShutdown(
d2a0: 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ) */.};../*.** C
d2b0: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 API3REF: Configu
d2c0: 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b ration Options {
d2d0: 48 31 30 31 36 30 7d 20 3c 53 32 30 30 30 30 3e H10160} <S20000>
d2e0: 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c .** EXPERIMENTAL
d2f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e .**.** These con
d300: 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 stants are the a
d310: 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 vailable integer
d320: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
d330: 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 ptions that.** c
d340: 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 an be passed as
d350: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
d360: 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 nt to the [sqlit
d370: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 e3_config()] int
d380: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 erface..**.** Ne
d390: 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 w configuration
d3a0: 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 options may be a
d3b0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 dded in future r
d3c0: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 eleases of SQLit
d3d0: 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 e..** Existing c
d3e0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
d3f0: 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 ions might be di
d400: 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 scontinued. App
d410: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f lications.** sho
d420: 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 uld check the re
d430: 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b turn code from [
d440: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
d450: 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 ] to make sure t
d460: 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 hat.** the call
d470: 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 worked. The [sq
d480: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
d490: 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 interface will r
d4a0: 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a eturn a.** non-z
d4b0: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d ero [error code]
d4c0: 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 if a discontinu
d4d0: 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 ed or unsupporte
d4e0: 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 d configuration
d4f0: 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 option.** is inv
d500: 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e oked..**.** <dl>
d510: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
d520: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 ONFIG_SINGLETHRE
d530: 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 AD</dt>.** <dd>T
d540: 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 here are no argu
d550: 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 ments to this op
d560: 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 tion. This opti
d570: 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 on disables.** a
d580: 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 ll mutexing and
d590: 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f puts SQLite into
d5a0: 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 a mode where it
d5b0: 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 can only be use
d5c0: 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 d.** by a single
d5d0: 20 74 68 72 65 61 64 2e 3c 2f 64 64 3e 0a 2a 2a thread.</dd>.**
d5e0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
d5f0: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 ONFIG_MULTITHREA
d600: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 D</dt>.** <dd>Th
d610: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d ere are no argum
d620: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 ents to this opt
d630: 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f ion. This optio
d640: 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 n disables.** mu
d650: 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 texing on [datab
d660: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
d670: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 and [prepared st
d680: 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 atement] objects
d690: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 ..** The applica
d6a0: 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 tion is responsi
d6b0: 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a ble for serializ
d6c0: 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a ing access to.**
d6d0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
d6e0: 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 ctions] and [pre
d6f0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 pared statements
d700: 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 ]. But other mu
d710: 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 texes.** are ena
d720: 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c bled so that SQL
d730: 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 ite will be safe
d740: 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c to use in a mul
d750: 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 ti-threaded.** e
d760: 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f nvironment as lo
d770: 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 ng as no two thr
d780: 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 eads attempt to
d790: 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 use the same.**
d7a0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
d7b0: 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d tion] at the sam
d7c0: 65 20 74 69 6d 65 2e 20 20 53 65 65 20 74 68 65 e time. See the
d7d0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
d7e0: 5d 0a 2a 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 ].** documentati
d7f0: 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 on for additiona
d800: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f l information.</
d810: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
d820: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 LITE_CONFIG_SERI
d830: 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c ALIZED</dt>.** <
d840: 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 dd>There are no
d850: 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 arguments to thi
d860: 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 s option. This
d870: 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a option enables.*
d880: 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e * all mutexes in
d890: 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 cluding the recu
d8a0: 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 rsive.** mutexes
d8b0: 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f on [database co
d8c0: 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 nnection] and [p
d8d0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
d8e0: 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 t] objects..** I
d8f0: 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 n this mode (whi
d900: 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c ch is the defaul
d910: 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 t when SQLite is
d920: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a compiled with.*
d930: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 * [SQLITE_THREAD
d940: 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c SAFE=1]) the SQL
d950: 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c ite library will
d960: 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a itself serializ
d970: 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b e access.** to [
d980: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
d990: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 ions] and [prepa
d9a0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 red statements]
d9b0: 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 so that the.** a
d9c0: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 pplication is fr
d9d0: 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 ee to use the sa
d9e0: 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e me [database con
d9f0: 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a nection] or the.
da00: 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 ** same [prepare
da10: 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 d statement] in
da20: 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 different thread
da30: 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 s at the same ti
da40: 6d 65 2e 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b me..** See the [
da50: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
da60: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f documentation fo
da70: 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 r additional inf
da80: 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a ormation.</dd>.*
da90: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
daa0: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 CONFIG_MALLOC</d
dab0: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f t>.** <dd>This o
dac0: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
dad0: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 ngle argument wh
dae0: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ich is a pointer
daf0: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e to an.** instan
db00: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ce of the [sqlit
db10: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 e3_mem_methods]
db20: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 structure. The
db30: 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 argument specifi
db40: 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 es.** alternativ
db50: 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f e low-level memo
db60: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f ry allocation ro
db70: 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 utines to be use
db80: 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a d in place of.**
db90: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f the memory allo
dba0: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 cation routines
dbb0: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 built into SQLit
dbc0: 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 e.</dd>.**.** <d
dbd0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
dbe0: 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a GETMALLOC</dt>.*
dbf0: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f * <dd>This optio
dc00: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
dc10: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
dc20: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
dc30: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f an.** instance o
dc40: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
dc50: 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 em_methods] stru
dc60: 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c cture. The [sql
dc70: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
dc80: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 ].** structure i
dc90: 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 s filled with th
dca0: 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 e currently defi
dcb0: 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ned memory alloc
dcc0: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a ation routines..
dcd0: 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 ** This option c
dce0: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 an be used to ov
dcf0: 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 erload the defau
dd00: 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 lt memory alloca
dd10: 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 tion.** routines
dd20: 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 with a wrapper
dd30: 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 that simulations
dd40: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
dd50: 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a on failure or.**
dd60: 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 tracks memory u
dd70: 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c sage, for exampl
dd80: 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 e.</dd>.**.** <d
dd90: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
dda0: 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a MEMSTATUS</dt>.*
ddb0: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f * <dd>This optio
ddc0: 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 n takes single a
ddd0: 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 rgument of type
dde0: 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 int, interpreted
ddf0: 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 as a .** boolea
de00: 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 n, which enables
de10: 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 or disables the
de20: 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d collection of m
de30: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
de40: 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e .** statistics.
de50: 20 57 68 65 6e 20 64 69 73 61 62 6c 65 64 2c 20 When disabled,
de60: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 the following SQ
de70: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 Lite interfaces
de80: 62 65 63 6f 6d 65 20 0a 2a 2a 20 6e 6f 6e 2d 6f become .** non-o
de90: 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 perational:.**
dea0: 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 <ul>.** <li>
deb0: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
dec0: 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 used()].** <li
ded0: 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 > [sqlite3_memor
dee0: 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a y_highwater()].*
def0: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 * <li> [sqlite
df00: 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 3_soft_heap_limi
df10: 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b t()].** <li> [
df20: 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 sqlite3_status()
df30: 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a 2a 20 ].** </ul>.**
df40: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
df50: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 SQLITE_CONFIG_SC
df60: 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 RATCH</dt>.** <d
df70: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 d>This option sp
df80: 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 ecifies a static
df90: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 memory buffer t
dfa0: 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 hat SQLite can u
dfb0: 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 se for.** scratc
dfc0: 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 h memory. There
dfd0: 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d are three argum
dfe0: 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 ents: A pointer
dff0: 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20 to the memory,
e000: 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 the.** size of e
e010: 61 63 68 20 73 63 72 61 74 63 68 20 62 75 66 66 ach scratch buff
e020: 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 er (sz), and the
e030: 20 6e 75 6d 62 65 72 20 6f 66 20 62 75 66 66 65 number of buffe
e040: 72 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a rs (N). The sz.
e050: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 ** argument must
e060: 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f be a multiple o
e070: 66 20 31 36 2e 20 54 68 65 20 73 7a 20 70 61 72 f 16. The sz par
e080: 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 ameter should be
e090: 20 61 20 66 65 77 20 62 79 74 65 73 0a 2a 2a 20 a few bytes.**
e0a0: 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 larger than the
e0b0: 61 63 74 75 61 6c 20 73 63 72 61 74 63 68 20 73 actual scratch s
e0c0: 70 61 63 65 20 72 65 71 75 69 72 65 64 20 64 75 pace required du
e0d0: 65 20 69 6e 74 65 72 6e 61 6c 20 6f 76 65 72 68 e internal overh
e0e0: 65 61 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 ead..** The firs
e0f0: 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 t.** argument sh
e100: 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e ould point to an
e110: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 allocation of a
e120: 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 t least sz*N byt
e130: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a es of memory..**
e140: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 SQLite will use
e150: 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e no more than on
e160: 65 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 e scratch buffer
e170: 20 61 74 20 6f 6e 63 65 20 70 65 72 20 74 68 72 at once per thr
e180: 65 61 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73 68 6f ead, so.** N sho
e190: 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 68 uld be set to th
e1a0: 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d e expected maxim
e1b0: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 um number of thr
e1c0: 65 61 64 73 2e 20 20 54 68 65 20 73 7a 0a 2a 2a eads. The sz.**
e1d0: 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c parameter shoul
e1e0: 64 20 62 65 20 36 20 74 69 6d 65 73 20 74 68 65 d be 6 times the
e1f0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 size of the lar
e200: 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 gest database pa
e210: 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 53 63 72 61 ge size..** Scra
e220: 74 63 68 20 62 75 66 66 65 72 73 20 61 72 65 20 tch buffers are
e230: 75 73 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 used as part of
e240: 74 68 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63 the btree balanc
e250: 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 49 66 e operation. If
e260: 0a 2a 2a 20 54 68 65 20 62 74 72 65 65 20 62 61 .** The btree ba
e270: 6c 61 6e 63 65 72 20 6e 65 65 64 73 20 61 64 64 lancer needs add
e280: 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 62 itional memory b
e290: 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 eyond what is pr
e2a0: 6f 76 69 64 65 64 20 62 79 0a 2a 2a 20 73 63 72 ovided by.** scr
e2b0: 61 74 63 68 20 62 75 66 66 65 72 73 20 6f 72 20 atch buffers or
e2c0: 69 66 20 6e 6f 20 73 63 72 61 74 63 68 20 62 75 if no scratch bu
e2d0: 66 66 65 72 20 73 70 61 63 65 20 69 73 20 73 70 ffer space is sp
e2e0: 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 53 51 ecified, then SQ
e2f0: 4c 69 74 65 0a 2a 2a 20 67 6f 65 73 20 74 6f 20 Lite.** goes to
e300: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
e310: 29 5d 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 )] to obtain the
e320: 20 6d 65 6d 6f 72 79 20 69 74 20 6e 65 65 64 73 memory it needs
e330: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
e340: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 >SQLITE_CONFIG_P
e350: 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a AGECACHE</dt>.**
e360: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e <dd>This option
e370: 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 specifies a sta
e380: 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 tic memory buffe
e390: 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 r that SQLite ca
e3a0: 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 n use for.** the
e3b0: 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 database page c
e3c0: 61 63 68 65 2e 20 20 54 68 65 72 65 20 61 72 65 ache. There are
e3d0: 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 three arguments
e3e0: 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 : A pointer to t
e3f0: 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 he.** memory, th
e400: 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 e size of each p
e410: 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c age buffer (sz),
e420: 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 and the number
e430: 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a of pages (N)..**
e440: 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 The sz argument
e450: 20 6d 75 73 74 20 62 65 20 61 20 70 6f 77 65 72 must be a power
e460: 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 of two between
e470: 35 31 32 20 61 6e 64 20 33 32 37 36 38 2e 20 20 512 and 32768.
e480: 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 The first.** arg
e490: 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 ument should poi
e4a0: 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 nt to an allocat
e4b0: 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 ion of at least
e4c0: 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 sz*N bytes of me
e4d0: 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 mory..** SQLite
e4e0: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d will use the mem
e4f0: 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 ory provided by
e500: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
e510: 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 nt to satisfy it
e520: 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 s.** memory need
e530: 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 s for the first
e540: 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20 N pages that it
e550: 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 adds to cache.
e560: 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a If additional.**
e570: 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f page cache memo
e580: 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 ry is needed bey
e590: 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 ond what is prov
e5a0: 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 ided by this opt
e5b0: 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c ion, then.** SQL
e5c0: 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c ite goes to [sql
e5d0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 ite3_malloc()] f
e5e0: 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 or the additiona
e5f0: 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e l storage space.
e600: 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e .** The implemen
e610: 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 75 73 65 tation might use
e620: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 one or more of
e630: 74 68 65 20 4e 20 62 75 66 66 65 72 73 20 74 6f the N buffers to
e640: 20 68 6f 6c 64 20 0a 2a 2a 20 6d 65 6d 6f 72 79 hold .** memory
e650: 20 61 63 63 6f 75 6e 74 69 6e 67 20 69 6e 66 6f accounting info
e660: 72 6d 61 74 69 6f 6e 2e 20 3c 2f 64 64 3e 0a 2a rmation. </dd>.*
e670: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
e680: 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e CONFIG_HEAP</dt>
e690: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 .** <dd>This opt
e6a0: 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 ion specifies a
e6b0: 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 static memory bu
e6c0: 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 ffer that SQLite
e6d0: 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 will use.** for
e6e0: 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 all of its dyna
e6f0: 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 mic memory alloc
e700: 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f ation needs beyo
e710: 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 nd those provide
e720: 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c d.** for by [SQL
e730: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 ITE_CONFIG_SCRAT
e740: 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f CH] and [SQLITE_
e750: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 CONFIG_PAGECACHE
e760: 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 ]..** There are
e770: 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a three arguments:
e780: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 A pointer to th
e790: 65 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 6e 75 e memory, the nu
e7a0: 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 mber of.** bytes
e7b0: 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 in the memory b
e7c0: 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d uffer, and the m
e7d0: 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f inimum allocatio
e7e0: 6e 20 73 69 7a 65 2e 20 20 49 66 0a 2a 2a 20 74 n size. If.** t
e7f0: 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 he first pointer
e800: 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 (the memory poi
e810: 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 nter) is NULL, t
e820: 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 hen SQLite rever
e830: 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 ts.** to using i
e840: 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 ts default memor
e850: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 y allocator (the
e860: 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 system malloc()
e870: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 implementation)
e880: 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 ,.** undoing any
e890: 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f prior invocatio
e8a0: 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e n of [SQLITE_CON
e8b0: 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 49 66 FIG_MALLOC]. If
e8c0: 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 the.** memory p
e8d0: 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 ointer is not NU
e8e0: 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 LL and either [S
e8f0: 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d QLITE_ENABLE_MEM
e900: 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c SYS3] or.** [SQL
e910: 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 ITE_ENABLE_MEMSY
e920: 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c S5] are defined,
e930: 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e then the altern
e940: 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 ative memory.**
e950: 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 allocator is eng
e960: 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 aged to handle a
e970: 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 ll of SQLites me
e980: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
e990: 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a needs.</dd>.**.*
e9a0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
e9b0: 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a FIG_MUTEX</dt>.*
e9c0: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f * <dd>This optio
e9d0: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
e9e0: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
e9f0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
ea00: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f an.** instance o
ea10: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
ea20: 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 utex_methods] st
ea30: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 ructure. The ar
ea40: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 gument specifies
ea50: 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 .** alternative
ea60: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 low-level mutex
ea70: 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 routines to be u
ea80: 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 sed in place.**
ea90: 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e the mutex routin
eaa0: 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 es built into SQ
eab0: 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a Lite.</dd>.**.**
eac0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
ead0: 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e IG_GETMUTEX</dt>
eae0: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 .** <dd>This opt
eaf0: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
eb00: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 le argument whic
eb10: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 h is a pointer t
eb20: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 o an.** instance
eb30: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
eb40: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 _mutex_methods]
eb50: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a structure. The.
eb60: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 ** [sqlite3_mute
eb70: 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 x_methods].** st
eb80: 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 ructure is fille
eb90: 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 d with the curre
eba0: 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 ntly defined mut
ebb0: 65 78 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 ex routines..**
ebc0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 This option can
ebd0: 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c be used to overl
ebe0: 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 oad the default
ebf0: 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e mutex allocation
ec00: 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 .** routines wit
ec10: 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64 h a wrapper used
ec20: 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 to track mutex
ec30: 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 usage for perfor
ec40: 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 mance.** profili
ec50: 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 ng or testing, f
ec60: 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e or example.</dd>
ec70: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
ec80: 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 E_CONFIG_LOOKASI
ec90: 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 DE</dt>.** <dd>T
eca0: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
ecb0: 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 two arguments t
ecc0: 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 hat determine th
ecd0: 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d e default.** mem
ece0: 6f 72 79 20 61 6c 6c 63 61 74 69 6f 6e 20 6c 6f ory allcation lo
ecf0: 6f 6b 61 73 69 64 65 20 6f 70 74 69 6d 69 7a 61 okaside optimiza
ed00: 74 69 6f 6e 2e 20 20 54 68 65 20 66 69 72 73 74 tion. The first
ed10: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
ed20: 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 .** size of each
ed30: 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 lookaside buffe
ed40: 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 r slot and the s
ed50: 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d econd is the num
ed60: 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 ber of.** slots
ed70: 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 allocated to eac
ed80: 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 h database conne
ed90: 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a ction.</dd>.**.*
eda0: 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 * </dl>.*/.#defi
edb0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
edc0: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 _SINGLETHREAD 1
edd0: 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 /* nil */.#def
ede0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
edf0: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 G_MULTITHREAD
ee00: 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 2 /* nil */.#de
ee10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
ee20: 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 IG_SERIALIZED
ee30: 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 3 /* nil */.#d
ee40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
ee50: 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 FIG_MALLOC
ee60: 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 4 /* sqlite3_
ee70: 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a mem_methods* */.
ee80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
ee90: 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 ONFIG_GETMALLOC
eea0: 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 5 /* sqlite
eeb0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 3_mem_methods* *
eec0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
eed0: 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 _CONFIG_SCRATCH
eee0: 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 6 /* void
eef0: 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e *, int sz, int N
ef00: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
ef10: 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 TE_CONFIG_PAGECA
ef20: 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f CHE 7 /* vo
ef30: 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 id*, int sz, int
ef40: 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 N */.#define SQ
ef50: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 LITE_CONFIG_HEAP
ef60: 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 8 /*
ef70: 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 void*, int nByte
ef80: 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 , int min */.#de
ef90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
efa0: 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 IG_MEMSTATUS
efb0: 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 9 /* boolean *
efc0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
efd0: 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 _CONFIG_MUTEX
efe0: 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 10 /* sqli
eff0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 te3_mutex_method
f000: 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 s* */.#define SQ
f010: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
f020: 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 UTEX 11 /*
f030: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 sqlite3_mutex_me
f040: 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e thods* */.#defin
f050: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
f060: 43 48 55 4e 4b 41 4c 4c 4f 43 20 20 20 31 32 20 CHUNKALLOC 12
f070: 20 2f 2a 20 69 6e 74 20 74 68 72 65 73 68 6f 6c /* int threshol
f080: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
f090: 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 ITE_CONFIG_LOOKA
f0a0: 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 SIDE 13 /* i
f0b0: 6e 74 20 69 6e 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a nt int */../*.**
f0c0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 CAPI3REF: Confi
f0d0: 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 guration Options
f0e0: 20 7b 48 31 30 31 37 30 7d 20 3c 53 32 30 30 30 {H10170} <S2000
f0f0: 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 0>.** EXPERIMENT
f100: 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 AL.**.** These c
f110: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 onstants are the
f120: 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 available integ
f130: 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e er configuration
f140: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a options that.**
f150: 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 can be passed a
f160: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 s the second arg
f170: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 ument to the [sq
f180: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
f190: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a )] interface..**
f1a0: 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 .** New configur
f1b0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 ation options ma
f1c0: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 y be added in fu
f1d0: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 ture releases of
f1e0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 SQLite..** Exis
f1f0: 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 ting configurati
f200: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 on options might
f210: 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 be discontinued
f220: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a . Applications.
f230: 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 ** should check
f240: 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 the return code
f250: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 from [sqlite3_db
f260: 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 _config()] to ma
f270: 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 ke sure that.**
f280: 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e the call worked.
f290: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 The [sqlite3_d
f2a0: 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 b_config()] inte
f2b0: 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 rface will retur
f2c0: 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 n a.** non-zero
f2d0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 [error code] if
f2e0: 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f a discontinued o
f2f0: 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f r unsupported co
f300: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
f310: 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 on.** is invoked
f320: 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 ..**.** <dl>.**
f330: 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e <dt>SQLITE_DBCON
f340: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 FIG_LOOKASIDE</d
f350: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f t>.** <dd>This o
f360: 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 ption takes thre
f370: 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 e additional arg
f380: 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 uments that dete
f390: 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c rmine the .** [l
f3a0: 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 ookaside memory
f3b0: 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 allocator] confi
f3c0: 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 guration for the
f3d0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
f3e0: 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 ction]..** The f
f3f0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 irst argument (t
f400: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
f410: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 er to [sqlite3_d
f420: 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 b_config()] is a
f430: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 .** pointer to a
f440: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 memory buffer t
f450: 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 o use for lookas
f460: 69 64 65 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 ide memory. The
f470: 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 first.** argume
f480: 6e 74 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 nt may be NULL i
f490: 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c n which case SQL
f4a0: 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 ite will allocat
f4b0: 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a e the lookaside.
f4c0: 2a 2a 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 ** buffer itself
f4d0: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
f4e0: 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 malloc()]. The
f4f0: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
f500: 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f is the.** size o
f510: 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 f each lookaside
f520: 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 buffer slot and
f530: 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d the third argum
f540: 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 ent is the numbe
f550: 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 r of.** slots.
f560: 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 The size of the
f570: 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 buffer in the fi
f580: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 rst argument mus
f590: 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61 t be greater tha
f5a0: 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f n.** or equal to
f5b0: 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 the product of
f5c0: 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 the second and t
f5d0: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 3c hird arguments.<
f5e0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e /dd>.**.** </dl>
f5f0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
f600: 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
f610: 41 53 49 44 45 20 20 20 20 31 30 30 31 20 20 2f ASIDE 1001 /
f620: 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 * void* int int
f630: 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */.../*.** CAPI3
f640: 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 REF: Enable Or D
f650: 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 isable Extended
f660: 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 Result Codes {H1
f670: 32 32 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2200} <S10700>.*
f680: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
f690: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 _extended_result
f6a0: 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 _codes() routine
f6b0: 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 enables or disa
f6c0: 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 bles the.** [ext
f6d0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
f6e0: 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 es] feature of S
f6f0: 51 4c 69 74 65 2e 20 54 68 65 20 65 78 74 65 6e QLite. The exten
f700: 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f ded result.** co
f710: 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 des are disabled
f720: 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 by default for
f730: 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 historical compa
f740: 74 69 62 69 6c 69 74 79 20 63 6f 6e 73 69 64 65 tibility conside
f750: 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 rations..**.** I
f760: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
f770: 20 7b 48 31 32 32 30 31 7d 20 45 61 63 68 20 6e {H12201} Each n
f780: 65 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ew [database con
f790: 6e 65 63 74 69 6f 6e 5d 20 73 68 61 6c 6c 20 68 nection] shall h
f7a0: 61 76 65 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 ave the.**
f7b0: 20 20 20 20 5b 65 78 74 65 6e 64 65 64 20 72 65 [extended re
f7c0: 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 sult codes] feat
f7d0: 75 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 ure disabled by
f7e0: 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b default..**.** {
f7f0: 48 31 32 32 30 32 7d 20 54 68 65 20 5b 73 71 6c H12202} The [sql
f800: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 ite3_extended_re
f810: 73 75 6c 74 5f 63 6f 64 65 73 28 44 2c 46 29 5d sult_codes(D,F)]
f820: 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c interface shall
f830: 20 65 6e 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 enable.**
f840: 20 20 20 20 5b 65 78 74 65 6e 64 65 64 20 72 65 [extended re
f850: 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 6f 72 20 sult codes] for
f860: 74 68 65 20 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
f870: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 onnection] D.**
f880: 20 20 20 20 20 20 20 20 20 69 66 20 74 68 65 20 if the
f890: 46 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 F parameter is t
f8a0: 72 75 65 2c 20 6f 72 20 64 69 73 61 62 6c 65 20 rue, or disable
f8b0: 74 68 65 6d 20 69 66 20 46 20 69 73 20 66 61 6c them if F is fal
f8c0: 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 se..*/.int sqlit
f8d0: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 e3_extended_resu
f8e0: 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 lt_codes(sqlite3
f8f0: 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a *, int onoff);..
f900: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
f910: 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 Last Insert Rowi
f920: 64 20 7b 48 31 32 32 32 30 7d 20 3c 53 31 30 37 d {H12220} <S107
f930: 30 30 3e 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 00>.**.** Each e
f940: 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 ntry in an SQLit
f950: 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e e table has a un
f960: 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e ique 64-bit sign
f970: 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 ed.** integer ke
f980: 79 20 63 61 6c 6c 65 64 20 74 68 65 20 22 72 6f y called the "ro
f990: 77 69 64 22 2e 20 54 68 65 20 72 6f 77 69 64 20 wid". The rowid
f9a0: 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 is always availa
f9b0: 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 ble.** as an und
f9c0: 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e eclared column n
f9d0: 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c amed ROWID, OID,
f9e0: 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c or _ROWID_ as l
f9f0: 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 ong as those.**
fa00: 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c names are not al
fa10: 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 so used by expli
fa20: 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 citly declared c
fa30: 6f 6c 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74 68 olumns. If.** th
fa40: 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f e table has a co
fa50: 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 49 4e 54 lumn of type INT
fa60: 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 EGER PRIMARY KEY
fa70: 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d then that colum
fa80: 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 n.** is another
fa90: 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f alias for the ro
faa0: 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 wid..**.** This
fab0: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
fac0: 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 the rowid of the
fad0: 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 most recent.**
fae0: 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 successful [INSE
faf0: 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74 RT] into the dat
fb00: 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b abase from the [
fb10: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
fb20: 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 ion].** in the f
fb30: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 irst argument.
fb40: 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c If no successful
fb50: 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 [INSERT]s.** ha
fb60: 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 ve ever occurred
fb70: 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61 73 on that databas
fb80: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 e connection, ze
fb90: 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a ro is returned..
fba0: 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 5b 49 4e 53 **.** If an [INS
fbb0: 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 ERT] occurs with
fbc0: 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 in a trigger, th
fbd0: 65 6e 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 en the rowid of
fbe0: 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 the inserted.**
fbf0: 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 row is returned
fc00: 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 by this routine
fc10: 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 as long as the t
fc20: 72 69 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e rigger is runnin
fc30: 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 g..** But once t
fc40: 68 65 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 he trigger termi
fc50: 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 nates, the value
fc60: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 returned by thi
fc70: 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 s routine.** rev
fc80: 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 erts to the last
fc90: 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 value inserted
fca0: 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 before the trigg
fcb0: 65 72 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 er fired..**.**
fcc0: 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 An [INSERT] that
fcd0: 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 fails due to a
fce0: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 constraint viola
fcf0: 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a tion is not a.**
fd00: 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 successful [INS
fd10: 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f ERT] and does no
fd20: 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c t change the val
fd30: 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 ue returned by t
fd40: 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 his.** routine.
fd50: 20 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 Thus INSERT OR
fd60: 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 FAIL, INSERT OR
fd70: 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f IGNORE, INSERT O
fd80: 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 R ROLLBACK,.** a
fd90: 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f nd INSERT OR ABO
fda0: 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 RT make no chang
fdb0: 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e es to the return
fdc0: 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a value of this.*
fdd0: 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 * routine when t
fde0: 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 heir insertion f
fdf0: 61 69 6c 73 2e 20 20 57 68 65 6e 20 49 4e 53 45 ails. When INSE
fe00: 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a RT OR REPLACE.**
fe10: 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f encounters a co
fe20: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 nstraint violati
fe30: 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 on, it does not
fe40: 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e fail. The.** IN
fe50: 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 SERT continues t
fe60: 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 o completion aft
fe70: 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 er deleting rows
fe80: 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 that caused.**
fe90: 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 the constraint p
fea0: 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 roblem so INSERT
feb0: 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c OR REPLACE will
fec0: 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a always change.*
fed0: 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c * the return val
fee0: 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 ue of this inter
fef0: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 face..**.** For
ff00: 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 the purposes of
ff10: 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e this routine, an
ff20: 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e [INSERT] is con
ff30: 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 sidered to.** be
ff40: 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e successful even
ff50: 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 if it is subseq
ff60: 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 uently rolled ba
ff70: 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 ck..**.** INVARI
ff80: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 ANTS:.**.** {H12
ff90: 32 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 221} The [sqlite
ffa0: 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 3_last_insert_ro
ffb0: 77 69 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 wid()] function
ffc0: 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 shall return the
ffd0: 20 72 6f 77 69 64 0a 2a 2a 20 20 20 20 20 20 20 rowid.**
ffe0: 20 20 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 of the most r
fff0: 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c ecent successful
10000 20 5b 49 4e 53 45 52 54 5d 20 70 65 72 66 6f 72 [INSERT] perfor
10010 6d 65 64 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a med on the same.
10020 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 ** [dat
10030 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
10040 5d 20 61 6e 64 20 77 69 74 68 69 6e 20 74 68 65 ] and within the
10050 20 73 61 6d 65 20 6f 72 20 68 69 67 68 65 72 20 same or higher
10060 6c 65 76 65 6c 0a 2a 2a 20 20 20 20 20 20 20 20 level.**
10070 20 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 trigger contex
10080 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66 20 74 68 t, or zero if th
10090 65 72 65 20 68 61 76 65 20 62 65 65 6e 20 6e 6f ere have been no
100a0 20 71 75 61 6c 69 66 79 69 6e 67 0a 2a 2a 20 20 qualifying.**
100b0 20 20 20 20 20 20 20 20 5b 49 4e 53 45 52 54 5d [INSERT]
100c0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a statements..**.
100d0 2a 2a 20 7b 48 31 32 32 32 33 7d 20 54 68 65 20 ** {H12223} The
100e0 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e [sqlite3_last_in
100f0 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 66 75 sert_rowid()] fu
10100 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74 nction shall ret
10110 75 72 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 urn the.**
10120 20 20 20 20 73 61 6d 65 20 76 61 6c 75 65 20 77 same value w
10130 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 hen called from
10140 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 the same trigger
10150 20 63 6f 6e 74 65 78 74 0a 2a 2a 20 20 20 20 20 context.**
10160 20 20 20 20 20 69 6d 6d 65 64 69 61 74 65 6c 79 immediately
10170 20 62 65 66 6f 72 65 20 61 6e 64 20 61 66 74 65 before and afte
10180 72 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a r a [ROLLBACK]..
10190 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e **.** ASSUMPTION
101a0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 33 32 S:.**.** {A12232
101b0 7d 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 } If a separate
101c0 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 thread performs
101d0 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f a new [INSERT] o
101e0 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 n the same.**
101f0 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65 20 database
10200 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 connection while
10210 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 the [sqlite3_la
10220 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 st_insert_rowid(
10230 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 )].** f
10240 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 unction is runni
10250 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e ng and thus chan
10260 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 ges the last ins
10270 65 72 74 20 72 6f 77 69 64 2c 0a 2a 2a 20 20 20 ert rowid,.**
10280 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 then the
10290 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
102a0 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f y [sqlite3_last_
102b0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 insert_rowid()]
102c0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 is.** u
102d0 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 npredictable and
102e0 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c might not equal
102f0 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 either the old
10300 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 20 20 or the new.**
10310 20 20 20 20 20 20 20 6c 61 73 74 20 69 6e 73 65 last inse
10320 72 74 20 72 6f 77 69 64 2e 0a 2a 2f 0a 73 71 6c rt rowid..*/.sql
10330 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 ite3_int64 sqlit
10340 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 e3_last_insert_r
10350 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a owid(sqlite3*);.
10360 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
10370 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 Count The Numbe
10380 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 r Of Rows Modifi
10390 65 64 20 7b 48 31 32 32 34 30 7d 20 3c 53 31 30 ed {H12240} <S10
103a0 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 600>.**.** This
103b0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
103c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 the number of d
103d0 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 atabase rows tha
103e0 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a t were changed.*
103f0 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 * or inserted or
10400 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 deleted by the
10410 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f most recently co
10420 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 mpleted SQL stat
10430 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 ement.** on the
10440 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
10450 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 tion] specified
10460 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72 by the first par
10470 61 6d 65 74 65 72 2e 0a 2a 2a 20 4f 6e 6c 79 20 ameter..** Only
10480 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 changes that are
10490 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 directly specif
104a0 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 ied by the [INSE
104b0 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a RT], [UPDATE],.*
104c0 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 * or [DELETE] st
104d0 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e atement are coun
104e0 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 ted. Auxiliary
104f0 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 changes caused b
10500 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 61 72 y.** triggers ar
10510 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 55 e not counted. U
10520 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f se the [sqlite3_
10530 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d total_changes()]
10540 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 function.** to
10550 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e find the total n
10560 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 umber of changes
10570 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 including chang
10580 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69 es caused by tri
10590 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 ggers..**.** A "
105a0 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 row change" is a
105b0 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e change to a sin
105c0 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e gle row of a sin
105d0 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 gle table.** cau
105e0 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 sed by an INSERT
105f0 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 , DELETE, or UPD
10600 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 ATE statement.
10610 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 Rows that.** are
10620 20 63 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 changed as side
10630 20 65 66 66 65 63 74 73 20 6f 66 20 52 45 50 4c effects of REPL
10640 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 ACE constraint r
10650 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f esolution,.** ro
10660 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 llback, ABORT pr
10670 6f 63 65 73 73 69 6e 67 2c 20 44 52 4f 50 20 54 ocessing, DROP T
10680 41 42 4c 45 2c 20 6f 72 20 62 79 20 61 6e 79 20 ABLE, or by any
10690 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 other.** mechani
106a0 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 sms do not count
106b0 20 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 as direct row c
106c0 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 hanges..**.** A
106d0 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 "trigger context
106e0 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 " is a scope of
106f0 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 execution that b
10700 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 egins and.** end
10710 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69 70 s with the scrip
10720 74 20 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20 t of a trigger.
10730 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d Most SQL statem
10740 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c ents are.** eval
10750 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 uated outside of
10760 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 any trigger. T
10770 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 his is the "top
10780 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 level".** trigge
10790 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 r context. If a
107a0 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66 trigger fires f
107b0 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 rom the top leve
107c0 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 l, a.** new trig
107d0 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 ger context is e
107e0 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 ntered for the d
107f0 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 uration of that
10800 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 one.** trigger.
10810 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65 Subtriggers cre
10820 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 ate subcontexts
10830 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69 for their durati
10840 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e on..**.** Callin
10850 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 g [sqlite3_exec(
10860 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 )] or [sqlite3_s
10870 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 tep()] recursive
10880 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 ly does.** not c
10890 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 reate a new trig
108a0 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a ger context..**.
108b0 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e ** This function
108c0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
108d0 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f ber of direct ro
108e0 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 w changes in the
108f0 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 .** most recent
10900 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 INSERT, UPDATE,
10910 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d or DELETE statem
10920 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 ent within the s
10930 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 ame.** trigger c
10940 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 ontext..**.** Th
10950 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 us, when called
10960 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 from the top lev
10970 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f el, this functio
10980 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a n returns the.**
10990 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 number of chang
109a0 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 es in the most r
109b0 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 ecent INSERT, UP
109c0 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a DATE, or DELETE.
109d0 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 ** that also occ
109e0 75 72 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 urred at the top
109f0 20 6c 65 76 65 6c 2e 20 20 57 69 74 68 69 6e 20 level. Within
10a00 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 the body of a tr
10a10 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 igger,.** the sq
10a20 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 lite3_changes()
10a30 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 interface can be
10a40 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 called to find
10a50 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a the number of.**
10a60 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 changes in the
10a70 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f most recently co
10a80 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 mpleted INSERT,
10a90 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 UPDATE, or DELET
10aa0 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 E.** statement w
10ab0 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f ithin the body o
10ac0 66 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 f the same trigg
10ad0 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 er..** However,
10ae0 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 the number retur
10af0 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 ned does not inc
10b00 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 lude changes.**
10b10 63 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69 caused by subtri
10b20 67 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 ggers since thos
10b30 65 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e e have their own
10b40 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 context..**.**
10b50 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 SQLite implement
10b60 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 s the command "D
10b70 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 ELETE FROM table
10b80 22 20 77 69 74 68 6f 75 74 20 61 20 57 48 45 52 " without a WHER
10b90 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64 E clause.** by d
10ba0 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72 ropping and recr
10bb0 65 61 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65 eating the table
10bc0 2e 20 20 44 6f 69 6e 67 20 73 6f 20 69 73 20 6d . Doing so is m
10bd0 75 63 68 20 66 61 73 74 65 72 20 74 68 61 6e 20 uch faster than
10be0 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 going.** through
10bf0 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e and deleting in
10c00 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 dividual element
10c10 73 20 66 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 s from the table
10c20 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 . Because of th
10c30 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 is.** optimizati
10c40 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74 69 6f 6e on, the deletion
10c50 73 20 69 6e 20 22 44 45 4c 45 54 45 20 46 52 4f s in "DELETE FRO
10c60 4d 20 74 61 62 6c 65 22 20 61 72 65 20 6e 6f 74 M table" are not
10c70 20 72 6f 77 20 63 68 61 6e 67 65 73 20 61 6e 64 row changes and
10c80 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 .** will not be
10c90 63 6f 75 6e 74 65 64 20 62 79 20 74 68 65 20 73 counted by the s
10ca0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 qlite3_changes()
10cb0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 or [sqlite3_tot
10cc0 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a al_changes()].**
10cd0 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72 65 67 61 functions, rega
10ce0 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75 rdless of the nu
10cf0 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 mber of elements
10d00 20 74 68 61 74 20 77 65 72 65 20 6f 72 69 67 69 that were origi
10d10 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68 65 20 nally.** in the
10d20 74 61 62 6c 65 2e 20 20 54 6f 20 67 65 74 20 61 table. To get a
10d30 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74 n accurate count
10d40 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f of the number o
10d50 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 f rows deleted,
10d60 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 use.** "DELETE F
10d70 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 ROM table WHERE
10d80 31 22 20 69 6e 73 74 65 61 64 2e 20 20 4f 72 20 1" instead. Or
10d90 72 65 63 6f 6d 70 69 6c 65 20 75 73 69 6e 67 20 recompile using
10da0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f the.** [SQLITE_O
10db0 4d 49 54 5f 54 52 55 4e 43 41 54 45 5f 4f 50 54 MIT_TRUNCATE_OPT
10dc0 49 4d 49 5a 41 54 49 4f 4e 5d 20 63 6f 6d 70 69 IMIZATION] compi
10dd0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 le-time option t
10de0 6f 20 64 69 73 61 62 6c 65 20 74 68 65 0a 2a 2a o disable the.**
10df0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 6f 6e optimization on
10e00 20 61 6c 6c 20 71 75 65 72 69 65 73 2e 0a 2a 2a all queries..**
10e10 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
10e20 2a 2a 0a 2a 2a 20 7b 48 31 32 32 34 31 7d 20 54 **.** {H12241} T
10e30 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e he [sqlite3_chan
10e40 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 ges()] function
10e50 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 shall return the
10e60 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 number of.**
10e70 20 20 20 20 20 20 20 72 6f 77 20 63 68 61 6e 67 row chang
10e80 65 73 20 63 61 75 73 65 64 20 62 79 20 74 68 65 es caused by the
10e90 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 most recent INS
10ea0 45 52 54 2c 20 55 50 44 41 54 45 2c 0a 2a 2a 20 ERT, UPDATE,.**
10eb0 20 20 20 20 20 20 20 20 20 6f 72 20 44 45 4c 45 or DELE
10ec0 54 45 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 TE statement on
10ed0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
10ee0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 e connection and
10ef0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 .** wit
10f00 68 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 20 hin the same or
10f10 68 69 67 68 65 72 20 74 72 69 67 67 65 72 20 63 higher trigger c
10f20 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20 ontext, or zero
10f30 69 66 20 74 68 65 72 65 20 68 61 76 65 0a 2a 2a if there have.**
10f40 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20 62 65 not be
10f50 65 6e 20 61 6e 79 20 71 75 61 6c 69 66 79 69 6e en any qualifyin
10f60 67 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a g row changes..*
10f70 2a 0a 2a 2a 20 7b 48 31 32 32 34 33 7d 20 53 74 *.** {H12243} St
10f80 61 74 65 6d 65 6e 74 73 20 6f 66 20 74 68 65 20 atements of the
10f90 66 6f 72 6d 20 22 44 45 4c 45 54 45 20 46 52 4f form "DELETE FRO
10fa0 4d 20 74 61 62 6c 65 6e 61 6d 65 22 20 77 69 74 M tablename" wit
10fb0 68 20 6e 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 h no.**
10fc0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 73 68 WHERE clause sh
10fd0 61 6c 6c 20 63 61 75 73 65 20 73 75 62 73 65 71 all cause subseq
10fe0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a uent calls to.**
10ff0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
11000 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 74 6f e3_changes()] to
11010 20 72 65 74 75 72 6e 20 7a 65 72 6f 2c 20 72 65 return zero, re
11020 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 0a gardless of the.
11030 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 ** numb
11040 65 72 20 6f 66 20 72 6f 77 73 20 6f 72 69 67 69 er of rows origi
11050 6e 61 6c 6c 79 20 69 6e 20 74 68 65 20 74 61 62 nally in the tab
11060 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 le..**.** ASSUMP
11070 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 TIONS:.**.** {A1
11080 32 32 35 32 7d 20 49 66 20 61 20 73 65 70 61 72 2252} If a separ
11090 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 ate thread makes
110a0 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 changes on the
110b0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f same database co
110c0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 nnection.**
110d0 20 20 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 while [sqli
110e0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 te3_changes()] i
110f0 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 s running then t
11100 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
11110 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 d.** is
11120 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 unpredictable a
11130 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 nd not meaningfu
11140 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 l..*/.int sqlite
11150 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 3_changes(sqlite
11160 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 3*);../*.** CAPI
11170 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 3REF: Total Numb
11180 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 er Of Rows Modif
11190 69 65 64 20 7b 48 31 32 32 36 30 7d 20 3c 53 31 ied {H12260} <S1
111a0 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 0600>.**.** This
111b0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e function return
111c0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
111d0 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 row changes caus
111e0 65 64 20 62 79 20 49 4e 53 45 52 54 2c 0a 2a 2a ed by INSERT,.**
111f0 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 UPDATE or DELET
11200 45 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e E statements sin
11210 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 ce the [database
11220 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 connection] was
11230 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 opened..** The
11240 63 6f 75 6e 74 20 69 6e 63 6c 75 64 65 73 20 61 count includes a
11250 6c 6c 20 63 68 61 6e 67 65 73 20 66 72 6f 6d 20 ll changes from
11260 61 6c 6c 20 74 72 69 67 67 65 72 20 63 6f 6e 74 all trigger cont
11270 65 78 74 73 2e 20 20 48 6f 77 65 76 65 72 2c 0a exts. However,.
11280 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 ** the count doe
11290 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 s not include ch
112a0 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d anges used to im
112b0 70 6c 65 6d 65 6e 74 20 52 45 50 4c 41 43 45 20 plement REPLACE
112c0 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 constraints,.**
112d0 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 do rollbacks or
112e0 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 ABORT processing
112f0 2c 20 6f 72 20 44 52 4f 50 20 74 61 62 6c 65 20 , or DROP table
11300 70 72 6f 63 65 73 73 69 6e 67 2e 0a 2a 2a 20 54 processing..** T
11310 68 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 he changes are c
11320 6f 75 6e 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 ounted as soon a
11330 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 s the statement
11340 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 that makes them
11350 69 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 is.** completed
11360 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d (when the statem
11370 65 6e 74 20 68 61 6e 64 6c 65 20 69 73 20 70 61 ent handle is pa
11380 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 ssed to [sqlite3
11390 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 _reset()] or.**
113a0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
113b0 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c e()])..**.** SQL
113c0 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 ite implements t
113d0 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 he command "DELE
113e0 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 TE FROM table" w
113f0 69 74 68 6f 75 74 20 61 20 57 48 45 52 45 20 63 ithout a WHERE c
11400 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70 lause.** by drop
11410 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74 ping and recreat
11420 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20 ing the table.
11430 28 54 68 69 73 20 69 73 20 6d 75 63 68 20 66 61 (This is much fa
11440 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a ster than going.
11450 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64 ** through and d
11460 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75 eleting individu
11470 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d al elements from
11480 20 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42 65 the table.) Be
11490 63 61 75 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a cause of this.**
114a0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 optimization, t
114b0 68 65 20 64 65 6c 65 74 69 6f 6e 73 20 69 6e 20 he deletions in
114c0 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 "DELETE FROM tab
114d0 6c 65 22 20 61 72 65 20 6e 6f 74 20 72 6f 77 20 le" are not row
114e0 63 68 61 6e 67 65 73 20 61 6e 64 0a 2a 2a 20 77 changes and.** w
114f0 69 6c 6c 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 ill not be count
11500 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 ed by the sqlite
11510 33 5f 63 68 61 6e 67 65 73 28 29 20 6f 72 20 5b 3_changes() or [
11520 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 sqlite3_total_ch
11530 61 6e 67 65 73 28 29 5d 0a 2a 2a 20 66 75 6e 63 anges()].** func
11540 74 69 6f 6e 73 2c 20 72 65 67 61 72 64 6c 65 73 tions, regardles
11550 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 s of the number
11560 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 of elements that
11570 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 were originally
11580 0a 2a 2a 20 69 6e 20 74 68 65 20 74 61 62 6c 65 .** in the table
11590 2e 20 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63 . To get an acc
115a0 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 urate count of t
115b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 he number of row
115c0 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a s deleted, use.*
115d0 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 * "DELETE FROM t
115e0 61 62 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e able WHERE 1" in
115f0 73 74 65 61 64 2e 20 20 20 4f 72 20 72 65 63 6f stead. Or reco
11600 6d 70 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a mpile using the.
11610 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f ** [SQLITE_OMIT_
11620 54 52 55 4e 43 41 54 45 5f 4f 50 54 49 4d 49 5a TRUNCATE_OPTIMIZ
11630 41 54 49 4f 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 ATION] compile-t
11640 69 6d 65 20 6f 70 74 69 6f 6e 20 74 6f 20 64 69 ime option to di
11650 73 61 62 6c 65 20 74 68 65 0a 2a 2a 20 6f 70 74 sable the.** opt
11660 69 6d 69 7a 61 74 69 6f 6e 20 6f 6e 20 61 6c 6c imization on all
11670 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 queries..**.**
11680 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 See also the [sq
11690 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d lite3_changes()]
116a0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a interface..**.*
116b0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
116c0 0a 2a 2a 20 7b 48 31 32 32 36 31 7d 20 54 68 65 .** {H12261} The
116d0 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f [sqlite3_total_
116e0 63 68 61 6e 67 65 73 28 29 5d 20 72 65 74 75 72 changes()] retur
116f0 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d ns the total num
11700 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ber.**
11710 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 of row changes c
11720 61 75 73 65 64 20 62 79 20 49 4e 53 45 52 54 2c aused by INSERT,
11730 20 55 50 44 41 54 45 2c 20 61 6e 64 2f 6f 72 20 UPDATE, and/or
11740 44 45 4c 45 54 45 0a 2a 2a 20 20 20 20 20 20 20 DELETE.**
11750 20 20 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e statements on
11760 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 the same [datab
11770 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c ase connection],
11780 20 69 6e 20 61 6e 79 0a 2a 2a 20 20 20 20 20 20 in any.**
11790 20 20 20 20 74 72 69 67 67 65 72 20 63 6f 6e 74 trigger cont
117a0 65 78 74 2c 20 73 69 6e 63 65 20 74 68 65 20 64 ext, since the d
117b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
117c0 6f 6e 20 77 61 73 20 63 72 65 61 74 65 64 2e 0a on was created..
117d0 2a 2a 0a 2a 2a 20 7b 48 31 32 32 36 33 7d 20 53 **.** {H12263} S
117e0 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 74 68 65 tatements of the
117f0 20 66 6f 72 6d 20 22 44 45 4c 45 54 45 20 46 52 form "DELETE FR
11800 4f 4d 20 74 61 62 6c 65 6e 61 6d 65 22 20 77 69 OM tablename" wi
11810 74 68 20 6e 6f 0a 2a 2a 20 20 20 20 20 20 20 20 th no.**
11820 20 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 73 WHERE clause s
11830 68 61 6c 6c 20 6e 6f 74 20 63 68 61 6e 67 65 20 hall not change
11840 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
11850 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 ed.** b
11860 79 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c y [sqlite3_total
11870 5f 63 68 61 6e 67 65 73 28 29 5d 2e 0a 2a 2a 0a _changes()]..**.
11880 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a ** ASSUMPTIONS:.
11890 2a 2a 0a 2a 2a 20 7b 41 31 32 32 36 34 7d 20 49 **.** {A12264} I
118a0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 f a separate thr
118b0 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 ead makes change
118c0 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 s on the same da
118d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
118e0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 n.** wh
118f0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 ile [sqlite3_tot
11900 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 al_changes()] is
11910 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 running then th
11920 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 e value.**
11930 20 20 20 20 72 65 74 75 72 6e 65 64 20 69 73 20 returned is
11940 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e unpredictable an
11950 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c d not meaningful
11960 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
11970 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 _total_changes(s
11980 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
11990 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 CAPI3REF: Inter
119a0 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e rupt A Long-Runn
119b0 69 6e 67 20 51 75 65 72 79 20 7b 48 31 32 32 37 ing Query {H1227
119c0 30 7d 20 3c 53 33 30 35 30 30 3e 0a 2a 2a 0a 2a 0} <S30500>.**.*
119d0 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 * This function
119e0 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 causes any pendi
119f0 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 ng database oper
11a00 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 ation to abort a
11a10 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 nd.** return at
11a20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 its earliest opp
11a30 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 ortunity. This r
11a40 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 outine is typica
11a50 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e lly.** called in
11a60 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 response to a u
11a70 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 ser action such
11a80 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e as pressing "Can
11a90 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d cel".** or Ctrl-
11aa0 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72 C where the user
11ab0 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 wants a long qu
11ac0 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f ery operation to
11ad0 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 halt.** immedia
11ae0 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 tely..**.** It i
11af0 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 s safe to call t
11b00 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d his routine from
11b10 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72 a thread differ
11b20 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 ent from the.**
11b30 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63 thread that is c
11b40 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 urrently running
11b50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 the database op
11b60 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 eration. But it
11b70 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 .** is not safe
11b80 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 to call this rou
11b90 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 tine with a [dat
11ba0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
11bb0 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f ] that.** is clo
11bc0 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f sed or might clo
11bd0 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 se before sqlite
11be0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 3_interrupt() re
11bf0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 turns..**.** If
11c00 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e an SQL operation
11c10 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 is very nearly
11c20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 finished at the
11c30 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c time when.** sql
11c40 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
11c50 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e is called, then
11c60 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 it might not ha
11c70 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 ve an opportunit
11c80 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 y.** to be inter
11c90 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 rupted and might
11ca0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d continue to com
11cb0 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 41 pletion..**.** A
11cc0 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 n SQL operation
11cd0 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 that is interrup
11ce0 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ted will return
11cf0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 [SQLITE_INTERRUP
11d00 54 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69 6e T]..** If the in
11d10 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 terrupted SQL op
11d20 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e eration is an IN
11d30 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 SERT, UPDATE, or
11d40 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 DELETE.** that
11d50 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 is inside an exp
11d60 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f licit transactio
11d70 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 n, then the enti
11d80 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a re transaction.*
11d90 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 * will be rolled
11da0 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 back automatica
11db0 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c lly..**.** A cal
11dc0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 l to sqlite3_int
11dd0 65 72 72 75 70 74 28 29 20 68 61 73 20 6e 6f 20 errupt() has no
11de0 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 effect on SQL st
11df0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 atements.** that
11e00 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 are started aft
11e10 65 72 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 er sqlite3_inter
11e20 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a rupt() returns..
11e30 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
11e40 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 37 31 7d :.**.** {H12271}
11e50 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e The [sqlite3_in
11e60 74 65 72 72 75 70 74 28 29 5d 20 69 6e 74 65 72 terrupt()] inter
11e70 66 61 63 65 20 77 69 6c 6c 20 66 6f 72 63 65 20 face will force
11e80 61 6c 6c 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 20 all running.**
11e90 20 20 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 SQL stat
11ea0 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 ements associate
11eb0 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 d with the same
11ec0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
11ed0 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ion.**
11ee0 74 6f 20 68 61 6c 74 20 61 66 74 65 72 20 70 72 to halt after pr
11ef0 6f 63 65 73 73 69 6e 67 20 61 74 20 6d 6f 73 74 ocessing at most
11f00 20 6f 6e 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 one additional
11f10 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a row of data..**.
11f20 2a 2a 20 7b 48 31 32 32 37 32 7d 20 41 6e 79 20 ** {H12272} Any
11f30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 SQL statement th
11f40 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 at is interrupte
11f50 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 69 6e d by [sqlite3_in
11f60 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20 terrupt()].**
11f70 20 20 20 20 20 20 20 77 69 6c 6c 20 72 65 74 75 will retu
11f80 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 rn [SQLITE_INTER
11f90 52 55 50 54 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 RUPT]..**.** ASS
11fa0 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 UMPTIONS:.**.**
11fb0 7b 41 31 32 32 37 39 7d 20 49 66 20 74 68 65 20 {A12279} If the
11fc0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
11fd0 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 ion closes while
11fe0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 [sqlite3_interr
11ff0 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 upt()].**
12000 20 20 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 is running th
12010 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 en bad things wi
12020 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e ll likely happen
12030 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 ..*/.void sqlite
12040 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 3_interrupt(sqli
12050 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 te3*);../*.** CA
12060 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e PI3REF: Determin
12070 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 e If An SQL Stat
12080 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 ement Is Complet
12090 65 20 7b 48 31 30 35 31 30 7d 20 3c 53 37 30 32 e {H10510} <S702
120a0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 00>.**.** These
120b0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 routines are use
120c0 66 75 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d ful for command-
120d0 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 line input to de
120e0 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a termine if the.*
120f0 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 * currently ente
12100 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 red text seems t
12110 6f 20 66 6f 72 6d 20 63 6f 6d 70 6c 65 74 65 20 o form complete
12120 61 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 a SQL statement
12130 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f or.** if additio
12140 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 nal input is nee
12150 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 ded before sendi
12160 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f ng the text into
12170 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 .** SQLite for p
12180 61 72 73 69 6e 67 2e 20 20 54 68 65 73 65 20 72 arsing. These r
12190 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 outines return t
121a0 72 75 65 20 69 66 20 74 68 65 20 69 6e 70 75 74 rue if the input
121b0 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 string.** appea
121c0 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c rs to be a compl
121d0 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ete SQL statemen
121e0 74 2e 20 20 41 20 73 74 61 74 65 6d 65 6e 74 20 t. A statement
121f0 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a is judged to be.
12200 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 ** complete if i
12210 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 t ends with a se
12220 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e micolon token an
12230 64 20 69 73 20 6e 6f 74 20 61 20 66 72 61 67 6d d is not a fragm
12240 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 43 52 45 41 ent of a.** CREA
12250 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 TE TRIGGER state
12260 6d 65 6e 74 2e 20 20 53 65 6d 69 63 6f 6c 6f 6e ment. Semicolon
12270 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 s that are embed
12280 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 ded within.** st
12290 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 ring literals or
122a0 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 quoted identifi
122b0 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d er names or comm
122c0 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 ents are not.**
122d0 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 independent toke
122e0 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72 ns (they are par
122f0 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 t of the token i
12300 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65 n which they are
12310 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e .** embedded) an
12320 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f d thus do not co
12330 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 unt as a stateme
12340 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a nt terminator..*
12350 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
12360 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 nes do not parse
12370 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
12380 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c nts thus.** will
12390 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 not detect synt
123a0 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 actically incorr
123b0 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 49 ect SQL..**.** I
123c0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
123d0 20 7b 48 31 30 35 31 31 7d 20 41 20 73 75 63 63 {H10511} A succ
123e0 65 73 73 66 75 6c 20 65 76 61 6c 75 61 74 69 6f essful evaluatio
123f0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 63 6f n of [sqlite3_co
12400 6d 70 6c 65 74 65 28 29 5d 20 6f 72 0a 2a 2a 20 mplete()] or.**
12410 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
12420 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 3_complete16()]
12430 66 75 6e 63 74 69 6f 6e 73 20 73 68 61 6c 6c 0a functions shall.
12440 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 ** retu
12450 72 6e 20 61 20 6e 75 6d 65 72 69 63 20 31 20 69 rn a numeric 1 i
12460 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 f and only if th
12470 65 20 6c 61 73 74 20 6e 6f 6e 2d 77 68 69 74 65 e last non-white
12480 73 70 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 space.**
12490 20 20 74 6f 6b 65 6e 20 69 6e 20 74 68 65 69 72 token in their
124a0 20 69 6e 70 75 74 20 69 73 20 61 20 73 65 6d 69 input is a semi
124b0 63 6f 6c 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f colon that is no
124c0 74 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 t in between.**
124d0 20 20 20 20 20 20 20 20 20 74 68 65 20 42 45 47 the BEG
124e0 49 4e 20 61 6e 64 20 45 4e 44 20 6f 66 20 61 20 IN and END of a
124f0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 CREATE TRIGGER s
12500 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 tatement..**.**
12510 7b 48 31 30 35 31 32 7d 20 49 66 20 61 20 6d 65 {H10512} If a me
12520 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
12530 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 error occurs dur
12540 69 6e 67 20 61 6e 20 69 6e 76 6f 63 61 74 69 6f ing an invocatio
12550 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 n.** of
12560 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 [sqlite3_comple
12570 74 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 te()] or [sqlite
12580 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 3_complete16()]
12590 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 then the.**
125a0 20 20 20 20 20 72 6f 75 74 69 6e 65 20 73 68 61 routine sha
125b0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 ll return [SQLIT
125c0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 E_NOMEM]..**.**
125d0 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a ASSUMPTIONS:.**.
125e0 2a 2a 20 7b 41 31 30 35 31 32 7d 20 54 68 65 20 ** {A10512} The
125f0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 input to [sqlite
12600 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 3_complete()] mu
12610 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 st be a zero-ter
12620 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 minated.**
12630 20 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 UTF-8 string
12640 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 30 35 31 33 7d ..**.** {A10513}
12650 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 The input to [s
12660 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 qlite3_complete1
12670 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 6()] must be a z
12680 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a ero-terminated.*
12690 2a 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 31 * UTF-1
126a0 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 6 string in nati
126b0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a ve byte order..*
126c0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f /.int sqlite3_co
126d0 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 mplete(const cha
126e0 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c r *sql);.int sql
126f0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 ite3_complete16(
12700 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 const void *sql)
12710 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
12720 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61 F: Register A Ca
12730 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 llback To Handle
12740 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 SQLITE_BUSY Err
12750 6f 72 73 20 7b 48 31 32 33 31 30 7d 20 3c 53 34 ors {H12310} <S4
12760 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 0400>.**.** This
12770 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 routine sets a
12780 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
12790 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 n that might be
127a0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 invoked whenever
127b0 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 .** an attempt i
127c0 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 s made to open a
127d0 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 database table
127e0 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 that another thr
127f0 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 ead.** or proces
12800 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a s has locked..**
12810 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79 20 .** If the busy
12820 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c callback is NULL
12830 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 , then [SQLITE_B
12840 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f USY] or [SQLITE_
12850 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a IOERR_BLOCKED].*
12860 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d * is returned im
12870 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 mediately upon e
12880 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 ncountering the
12890 6c 6f 63 6b 2e 20 49 66 20 74 68 65 20 62 75 73 lock. If the bus
128a0 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 y callback.** is
128b0 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 not NULL, then
128c0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c the callback wil
128d0 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 l be invoked wit
128e0 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e h two arguments.
128f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 .**.** The first
12900 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
12910 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f handler is a co
12920 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 py of the void*
12930 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a pointer which.**
12940 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72 is the third ar
12950 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 gument to sqlite
12960 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 3_busy_handler()
12970 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 . The second ar
12980 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 gument to.** the
12990 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 handler callbac
129a0 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 k is the number
129b0 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 of times that th
129c0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 e busy handler h
129d0 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b as.** been invok
129e0 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b ed for this lock
129f0 69 6e 67 20 65 76 65 6e 74 2e 20 20 49 66 20 74 ing event. If t
12a00 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 he.** busy callb
12a10 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 ack returns 0, t
12a20 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 hen no additiona
12a30 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d l attempts are m
12a40 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 ade to.** access
12a50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e the database an
12a60 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 d [SQLITE_BUSY]
12a70 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 or [SQLITE_IOERR
12a80 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 _BLOCKED] is ret
12a90 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 urned..** If the
12aa0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
12ab0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e s non-zero, then
12ac0 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 another attempt
12ad0 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f .** is made to o
12ae0 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 pen the database
12af0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 for reading and
12b00 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 the cycle repea
12b10 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 ts..**.** The pr
12b20 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 esence of a busy
12b30 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f handler does no
12b40 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 t guarantee that
12b50 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f it will be invo
12b60 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 ked.** when ther
12b70 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e e is lock conten
12b80 74 69 6f 6e 2e 20 49 66 20 53 51 4c 69 74 65 20 tion. If SQLite
12b90 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 determines that
12ba0 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 invoking the bus
12bb0 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 y.** handler cou
12bc0 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 ld result in a d
12bd0 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c eadlock, it will
12be0 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 go ahead and re
12bf0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 turn [SQLITE_BUS
12c00 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 Y].** or [SQLITE
12c10 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 _IOERR_BLOCKED]
12c20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b instead of invok
12c30 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e ing the busy han
12c40 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 dler..** Conside
12c50 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 r a scenario whe
12c60 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 re one process i
12c70 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 s holding a read
12c80 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 lock that.** it
12c90 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 is trying to pr
12ca0 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 omote to a reser
12cb0 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 ved lock and.**
12cc0 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 a second process
12cd0 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 is holding a re
12ce0 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 served lock that
12cf0 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a it is trying.**
12d00 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 to promote to a
12d10 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b n exclusive lock
12d20 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f . The first pro
12d30 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 cess cannot proc
12d40 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 eed.** because i
12d50 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 t is blocked by
12d60 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 the second and t
12d70 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 he second proces
12d80 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 s cannot.** proc
12d90 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 eed because it i
12da0 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 s blocked by the
12db0 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 first. If both
12dc0 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e processes.** in
12dd0 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 voke the busy ha
12de0 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 ndlers, neither
12df0 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 will make any pr
12e00 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f ogress. Therefo
12e10 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 re,.** SQLite re
12e20 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 turns [SQLITE_BU
12e30 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 SY] for the firs
12e40 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e t process, hopin
12e50 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 g that this.** w
12e60 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 ill induce the f
12e70 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 irst process to
12e80 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 release its read
12e90 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a lock and allow.
12ea0 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 ** the second pr
12eb0 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 ocess to proceed
12ec0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 ..**.** The defa
12ed0 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 ult busy callbac
12ee0 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a k is NULL..**.**
12ef0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 The [SQLITE_BUS
12f00 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 Y] error is conv
12f10 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 erted to [SQLITE
12f20 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a _IOERR_BLOCKED].
12f30 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 ** when SQLite i
12f40 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 s in the middle
12f50 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 of a large trans
12f60 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c action where all
12f70 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 the.** changes
12f80 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 will not fit int
12f90 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 o the in-memory
12fa0 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 cache. SQLite w
12fb0 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 ill.** already h
12fc0 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c old a RESERVED l
12fd0 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 ock on the datab
12fe0 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 ase file, but it
12ff0 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f needs.** to pro
13000 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 mote this lock t
13010 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 o EXCLUSIVE so t
13020 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c hat it can spill
13030 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 cache.** pages
13040 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 into the databas
13050 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 e file without h
13060 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e arm to concurren
13070 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 49 t.** readers. I
13080 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 f it is unable t
13090 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f o promote the lo
130a0 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d ck, then the in-
130b0 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 memory.** cache
130c0 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 will be left in
130d0 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 an inconsistent
130e0 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 state and so the
130f0 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 error.** code i
13100 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 s promoted from
13110 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 the relatively b
13120 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 enign [SQLITE_BU
13130 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f SY] to.** the mo
13140 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 re severe [SQLIT
13150 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d E_IOERR_BLOCKED]
13160 2e 20 20 54 68 69 73 20 65 72 72 6f 72 20 63 6f . This error co
13170 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 de promotion.**
13180 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 forces an automa
13190 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 tic rollback of
131a0 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 the changes. Se
131b0 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 e the.** <a href
131c0 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f ="/cvstrac/wiki?
131d0 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c p=CorruptionFoll
131e0 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e owingBusyError">
131f0 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f .** CorruptionFo
13200 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 llowingBusyError
13210 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 </a> wiki page f
13220 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 or a discussion
13230 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 of why.** this i
13240 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a s important..**.
13250 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c ** There can onl
13260 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 y be a single bu
13270 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e sy handler defin
13280 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b ed for each.** [
13290 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
132a0 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 ion]. Setting a
132b0 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 new busy handle
132c0 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 r clears any.**
132d0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 previously set h
132e0 61 6e 64 6c 65 72 2e 20 20 4e 6f 74 65 20 74 68 andler. Note th
132f0 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 at calling [sqli
13300 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 te3_busy_timeout
13310 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f ()].** will also
13320 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 set or clear th
13330 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a e busy handler..
13340 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 **.** The busy c
13350 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e allback should n
13360 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 ot take any acti
13370 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 ons which modify
13380 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 the.** database
13390 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 connection that
133a0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 invoked the bus
133b0 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 y handler. Any
133c0 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 such actions.**
133d0 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 result in undefi
133e0 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a ned behavior..**
133f0 20 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a .** INVARIANTS:
13400 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 31 7d 20 .**.** {H12311}
13410 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 The [sqlite3_bus
13420 79 5f 68 61 6e 64 6c 65 72 28 44 2c 43 2c 41 29 y_handler(D,C,A)
13430 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c ] function shall
13440 20 72 65 70 6c 61 63 65 0a 2a 2a 20 20 20 20 20 replace.**
13450 20 20 20 20 20 62 75 73 79 20 63 61 6c 6c 62 61 busy callba
13460 63 6b 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 ck in the [datab
13470 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
13480 44 20 77 69 74 68 20 61 20 6e 65 77 0a 2a 2a 20 D with a new.**
13490 20 20 20 20 20 20 20 20 20 61 20 6e 65 77 20 62 a new b
134a0 75 73 79 20 68 61 6e 64 6c 65 72 20 43 20 61 6e usy handler C an
134b0 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 d application da
134c0 74 61 20 70 6f 69 6e 74 65 72 20 41 2e 0a 2a 2a ta pointer A..**
134d0 0a 2a 2a 20 7b 48 31 32 33 31 32 7d 20 4e 65 77 .** {H12312} New
134e0 6c 79 20 63 72 65 61 74 65 64 20 5b 64 61 74 61 ly created [data
134f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
13500 5d 20 73 68 61 6c 6c 20 68 61 76 65 20 61 20 62 ] shall have a b
13510 75 73 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 usy.**
13520 68 61 6e 64 6c 65 72 20 6f 66 20 4e 55 4c 4c 2e handler of NULL.
13530 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 34 7d 20 .**.** {H12314}
13540 57 68 65 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 When two or more
13550 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
13560 63 74 69 6f 6e 73 5d 20 73 68 61 72 65 20 61 0a ctions] share a.
13570 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
13580 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 ite3_enable_shar
13590 65 64 5f 63 61 63 68 65 20 7c 20 63 6f 6d 6d 6f ed_cache | commo
135a0 6e 20 63 61 63 68 65 5d 2c 0a 2a 2a 20 20 20 20 n cache],.**
135b0 20 20 20 20 20 20 74 68 65 20 62 75 73 79 20 68 the busy h
135c0 61 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 20 64 andler for the d
135d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
135e0 6f 6e 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 on currently usi
135f0 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 ng.** t
13600 68 65 20 63 61 63 68 65 20 73 68 61 6c 6c 20 62 he cache shall b
13610 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 e invoked when t
13620 68 65 20 63 61 63 68 65 20 65 6e 63 6f 75 6e 74 he cache encount
13630 65 72 73 20 61 20 6c 6f 63 6b 2e 0a 2a 2a 0a 2a ers a lock..**.*
13640 2a 20 7b 48 31 32 33 31 36 7d 20 49 66 20 61 20 * {H12316} If a
13650 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c busy handler cal
13660 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 7a 65 lback returns ze
13670 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c ro, then the SQL
13680 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a ite interface.**
13690 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 70 that p
136a0 72 6f 76 6f 6b 65 64 20 74 68 65 20 6c 6f 63 6b rovoked the lock
136b0 69 6e 67 20 65 76 65 6e 74 20 73 68 61 6c 6c 20 ing event shall
136c0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 return [SQLITE_B
136d0 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 USY]..**.** {H12
136e0 33 31 38 7d 20 53 51 4c 69 74 65 20 73 68 61 6c 318} SQLite shal
136f0 6c 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 62 75 l invokes the bu
13700 73 79 20 68 61 6e 64 6c 65 72 20 77 69 74 68 20 sy handler with
13710 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 77 68 two arguments wh
13720 69 63 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ich.**
13730 61 72 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 are a copy of th
13740 65 20 70 6f 69 6e 74 65 72 20 73 75 70 70 6c 69 e pointer suppli
13750 65 64 20 62 79 20 74 68 65 20 33 72 64 20 70 61 ed by the 3rd pa
13760 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 rameter to.**
13770 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
13780 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 busy_handler()]
13790 61 6e 64 20 61 20 63 6f 75 6e 74 20 6f 66 20 74 and a count of t
137a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 72 69 he number of pri
137b0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 or.** i
137c0 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 nvocations of th
137d0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 e busy handler f
137e0 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b or the same lock
137f0 69 6e 67 20 65 76 65 6e 74 2e 0a 2a 2a 0a 2a 2a ing event..**.**
13800 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a ASSUMPTIONS:.**
13810 0a 2a 2a 20 7b 41 31 32 33 31 39 7d 20 41 20 62 .** {A12319} A b
13820 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 usy handler must
13830 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 not close the d
13840 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
13850 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f on.** o
13860 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 r [prepared stat
13870 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f ement] that invo
13880 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e ked the busy han
13890 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c dler..*/.int sql
138a0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 ite3_busy_handle
138b0 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 r(sqlite3*, int(
138c0 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 *)(void*,int), v
138d0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 oid*);../*.** CA
138e0 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 PI3REF: Set A Bu
138f0 73 79 20 54 69 6d 65 6f 75 74 20 7b 48 31 32 33 sy Timeout {H123
13900 34 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 40} <S40410>.**.
13910 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
13920 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f sets a [sqlite3_
13930 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 busy_handler | b
13940 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 usy handler] tha
13950 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 t sleeps.** for
13960 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 a specified amou
13970 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 nt of time when
13980 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 a table is locke
13990 64 2e 20 20 54 68 65 20 68 61 6e 64 6c 65 72 0a d. The handler.
139a0 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 ** will sleep mu
139b0 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 ltiple times unt
139c0 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 il at least "ms"
139d0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 milliseconds of
139e0 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 sleeping.** hav
139f0 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 7b e accumulated. {
13a00 48 31 32 33 34 33 7d 20 41 66 74 65 72 20 22 6d H12343} After "m
13a10 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 s" milliseconds
13a20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 of sleeping,.**
13a30 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 the handler retu
13a40 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 rns 0 which caus
13a50 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 es [sqlite3_step
13a60 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a ()] to return.**
13a70 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f [SQLITE_BUSY] o
13a80 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f r [SQLITE_IOERR_
13a90 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 BLOCKED]..**.**
13aa0 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 Calling this rou
13ab0 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 tine with an arg
13ac0 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 ument less than
13ad0 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f or equal to zero
13ae0 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c .** turns off al
13af0 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e l busy handlers.
13b00 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e .**.** There can
13b10 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c only be a singl
13b20 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 e busy handler f
13b30 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a or a particular.
13b40 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
13b50 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 nection] any any
13b60 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 given moment.
13b70 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 If another busy
13b80 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 handler.** was d
13b90 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b efined (using [
13ba0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e sqlite3_busy_han
13bb0 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 dler()]) prior t
13bc0 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 o calling.** thi
13bd0 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 s routine, that
13be0 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c other busy handl
13bf0 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a er is cleared..*
13c00 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
13c10 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34 31 7d 20 .**.** {H12341}
13c20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 The [sqlite3_bus
13c30 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 66 75 6e y_timeout()] fun
13c40 63 74 69 6f 6e 20 73 68 61 6c 6c 20 6f 76 65 72 ction shall over
13c50 72 69 64 65 20 61 6e 79 20 70 72 69 6f 72 0a 2a ride any prior.*
13c60 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
13c70 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 te3_busy_timeout
13c80 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
13c90 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 busy_handler()]
13ca0 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 20 setting.**
13cb0 20 20 20 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 on the same
13cc0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
13cd0 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 tion]..**.** {H1
13ce0 32 33 34 33 7d 20 49 66 20 74 68 65 20 32 6e 64 2343} If the 2nd
13cf0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 parameter to [s
13d00 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 qlite3_busy_time
13d10 6f 75 74 28 29 5d 20 69 73 20 6c 65 73 73 20 74 out()] is less t
13d20 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 han.**
13d30 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f or equal to zero
13d40 2c 20 74 68 65 6e 20 74 68 65 20 62 75 73 79 20 , then the busy
13d50 68 61 6e 64 6c 65 72 20 73 68 61 6c 6c 20 62 65 handler shall be
13d60 20 63 6c 65 61 72 65 64 20 73 6f 20 74 68 61 74 cleared so that
13d70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c .** all
13d80 20 73 75 62 73 65 71 75 65 6e 74 20 6c 6f 63 6b subsequent lock
13d90 69 6e 67 20 65 76 65 6e 74 73 20 69 6d 6d 65 64 ing events immed
13da0 69 61 74 65 6c 79 20 72 65 74 75 72 6e 20 5b 53 iately return [S
13db0 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a QLITE_BUSY]..**.
13dc0 2a 2a 20 7b 48 31 32 33 34 34 7d 20 49 66 20 74 ** {H12344} If t
13dd0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 he 2nd parameter
13de0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 to [sqlite3_bus
13df0 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 20 y_timeout()] is
13e00 61 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 20 20 a positive.**
13e10 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 4e 2c number N,
13e20 20 74 68 65 6e 20 61 20 62 75 73 79 20 68 61 6e then a busy han
13e30 64 6c 65 72 20 73 68 61 6c 6c 20 62 65 20 73 65 dler shall be se
13e40 74 20 74 68 61 74 20 72 65 70 65 61 74 65 64 6c t that repeatedl
13e50 79 20 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 y calls.**
13e60 20 20 20 20 74 68 65 20 78 53 6c 65 65 70 28 29 the xSleep()
13e70 20 6d 65 74 68 6f 64 20 69 6e 20 74 68 65 20 5b method in the [
13e80 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 sqlite3_vfs | VF
13e90 53 20 69 6e 74 65 72 66 61 63 65 5d 20 75 6e 74 S interface] unt
13ea0 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 il.** e
13eb0 69 74 68 65 72 20 74 68 65 20 6c 6f 63 6b 20 63 ither the lock c
13ec0 6c 65 61 72 73 20 6f 72 20 75 6e 74 69 6c 20 74 lears or until t
13ed0 68 65 20 63 75 6d 75 6c 61 74 69 76 65 20 73 6c he cumulative sl
13ee0 65 65 70 20 74 69 6d 65 0a 2a 2a 20 20 20 20 20 eep time.**
13ef0 20 20 20 20 20 72 65 70 6f 72 74 65 64 20 62 61 reported ba
13f00 63 6b 20 62 79 20 78 53 6c 65 65 70 28 29 20 65 ck by xSleep() e
13f10 78 63 65 65 64 73 20 4e 20 6d 69 6c 6c 69 73 65 xceeds N millise
13f20 63 6f 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 conds..*/.int sq
13f30 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f lite3_busy_timeo
13f40 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 ut(sqlite3*, int
13f50 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ms);../*.** CAP
13f60 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e I3REF: Convenien
13f70 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 ce Routines For
13f80 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 20 Running Queries
13f90 7b 48 31 32 33 37 30 7d 20 3c 53 31 30 30 30 30 {H12370} <S10000
13fa0 3e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 >.**.** Definiti
13fb0 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 on: A <b>result
13fc0 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d table</b> is mem
13fd0 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 ory data structu
13fe0 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 re created by th
13ff0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 e.** [sqlite3_ge
14000 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 t_table()] inter
14010 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 face. A result
14020 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 table records th
14030 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 e.** complete qu
14040 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d ery results from
14050 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 one or more que
14060 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ries..**.** The
14070 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c table conceptual
14080 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 ly has a number
14090 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 of rows and colu
140a0 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 mns. But.** the
140b0 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e se numbers are n
140c0 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 ot part of the r
140d0 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 esult table itse
140e0 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 lf. These.** nu
140f0 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e mbers are obtain
14100 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 ed separately.
14110 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d Let N be the num
14120 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 ber of rows.** a
14130 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 nd M be the numb
14140 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a er of columns..*
14150 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 *.** A result ta
14160 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 ble is an array
14170 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a of pointers to z
14180 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 ero-terminated U
14190 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a TF-8 strings..**
141a0 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 There are (N+1)
141b0 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 *M elements in t
141c0 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 he array. The f
141d0 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 irst M pointers
141e0 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f point.** to zero
141f0 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 -terminated stri
14200 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 ngs that contai
14210 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 n the names of t
14220 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 he columns..** T
14230 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 he remaining ent
14240 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 ries all point t
14250 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e o query results.
14260 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 NULL values re
14270 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 sult.** in NULL
14280 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f pointers. All o
14290 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 ther values are
142a0 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a in their UTF-8 z
142b0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a ero-terminated.*
142c0 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 * string represe
142d0 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 ntation as retur
142e0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ned by [sqlite3_
142f0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a column_text()]..
14300 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 **.** A result t
14310 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 able might consi
14320 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 st of one or mor
14330 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
14340 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e ions..** It is n
14350 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 ot safe to pass
14360 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 a result table d
14370 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 irectly to [sqli
14380 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 te3_free()]..**
14390 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 A result table s
143a0 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 hould be dealloc
143b0 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 ated using [sqli
143c0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 te3_free_table()
143d0 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 ]..**.** As an e
143e0 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 xample of the re
143f0 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 sult table forma
14400 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 t, suppose a que
14410 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 ry result.** is
14420 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a as follows:.**.*
14430 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
14440 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 re>.** Na
14450 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a me | Age.
14460 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d ** ------
14470 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
14480 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 -.** Alic
14490 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 e | 43.**
144a0 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 Bob
144b0 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 | 28.**
144c0 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 Cindy |
144d0 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 21.** </pre></bl
144e0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
144f0 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f There are two co
14500 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 lumn (M==2) and
14510 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 three rows (N==3
14520 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 ). Thus the.**
14530 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 result table has
14540 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 8 entries. Sup
14550 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 pose the result
14560 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a table is stored.
14570 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e ** in an array n
14580 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 ames azResult.
14590 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f Then azResult ho
145a0 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 lds this content
145b0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
145c0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 ote><pre>.**
145d0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
145e0 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a ;0] = "Name";.**
145f0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
14600 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b [1] = "Age";
14610 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
14620 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c ult[2] = "Al
14630 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 ice";.**
14640 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 azResult[3]
14650 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 = "43";.**
14660 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 azResult[4
14670 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 ] = "Bob";.**
14680 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
14690 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 1;5] = "28";.**
146a0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
146b0 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 #91;6] = "Cindy"
146c0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
146d0 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 sult[7] = "2
146e0 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 1";.** </pre></b
146f0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
14700 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 The sqlite3_get
14710 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f _table() functio
14720 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 n evaluates one
14730 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 or more.** semic
14740 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 olon-separated S
14750 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e QL statements in
14760 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e the zero-termin
14770 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 ated UTF-8.** st
14780 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 ring of its 2nd
14790 70 61 72 61 6d 65 74 65 72 2e 20 20 49 74 20 72 parameter. It r
147a0 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 eturns a result
147b0 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 table to the.**
147c0 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e pointer given in
147d0 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 its 3rd paramet
147e0 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 er..**.** After
147f0 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 the calling func
14800 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 tion has finishe
14810 64 20 75 73 69 6e 67 20 74 68 65 20 72 65 73 75 d using the resu
14820 6c 74 2c 20 69 74 20 73 68 6f 75 6c 64 0a 2a 2a lt, it should.**
14830 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 pass the pointe
14840 72 20 74 6f 20 74 68 65 20 72 65 73 75 6c 74 20 r to the result
14850 74 61 62 6c 65 20 74 6f 20 73 71 6c 69 74 65 33 table to sqlite3
14860 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e _free_table() in
14870 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c order to.** rel
14880 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 ease the memory
14890 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 that was malloce
148a0 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 d. Because of t
148b0 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 he way the.** [s
148c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
148d0 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 happens within
148e0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
148f0 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 e(), the calling
14900 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 .** function mus
14910 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c t not try to cal
14920 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 l [sqlite3_free(
14930 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e )] directly. On
14940 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 ly.** [sqlite3_f
14950 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 ree_table()] is
14960 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 able to release
14970 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 the memory prope
14980 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a rly and safely..
14990 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
149a0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 3_get_table() in
149b0 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 terface is imple
149c0 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 mented as a wrap
149d0 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 per around.** [s
149e0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 qlite3_exec()].
149f0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 The sqlite3_get
14a00 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 _table() routine
14a10 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 does not have a
14a20 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 ccess.** to any
14a30 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 internal data st
14a40 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 ructures of SQLi
14a50 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c te. It uses onl
14a60 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 y the public.**
14a70 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 interface define
14a80 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f d here. As a co
14a90 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 nsequence, error
14aa0 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 s that occur in
14ab0 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c the.** wrapper l
14ac0 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 ayer outside of
14ad0 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 the internal [sq
14ae0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 lite3_exec()] ca
14af0 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 ll are not.** re
14b00 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 flected in subse
14b10 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b quent calls to [
14b20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
14b30 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 )] or [sqlite3_e
14b40 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 rrmsg()]..**.**
14b50 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
14b60 2a 20 7b 48 31 32 33 37 31 7d 20 49 66 20 61 20 * {H12371} If a
14b70 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 [sqlite3_get_tab
14b80 6c 65 28 29 5d 20 66 61 69 6c 73 20 61 20 6d 65 le()] fails a me
14b90 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c mory allocation,
14ba0 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 then.**
14bb0 20 20 69 74 20 73 68 61 6c 6c 20 66 72 65 65 20 it shall free
14bc0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 the result table
14bd0 20 75 6e 64 65 72 20 63 6f 6e 73 74 72 75 63 74 under construct
14be0 69 6f 6e 2c 20 61 62 6f 72 74 20 74 68 65 0a 2a ion, abort the.*
14bf0 2a 20 20 20 20 20 20 20 20 20 20 71 75 65 72 79 * query
14c00 20 69 6e 20 70 72 6f 63 65 73 73 2c 20 73 6b 69 in process, ski
14c10 70 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 p any subsequent
14c20 20 71 75 65 72 69 65 73 2c 20 73 65 74 20 74 68 queries, set th
14c30 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 2a 70 e.** *p
14c40 61 7a 52 65 73 75 6c 74 20 6f 75 74 70 75 74 20 azResult output
14c50 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20 pointer to NULL
14c60 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 and return [SQLI
14c70 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a TE_NOMEM]..**.**
14c80 20 7b 48 31 32 33 37 33 7d 20 49 66 20 74 68 65 {H12373} If the
14c90 20 70 6e 43 6f 6c 75 6d 6e 20 70 61 72 61 6d 65 pnColumn parame
14ca0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
14cb0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 get_table()] is
14cc0 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 not NULL.**
14cd0 20 20 20 20 20 74 68 65 6e 20 61 20 73 75 63 63 then a succ
14ce0 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f essful invocatio
14cf0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 n of [sqlite3_ge
14d00 74 5f 74 61 62 6c 65 28 29 5d 20 73 68 61 6c 6c t_table()] shall
14d10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 72 69 .** wri
14d20 74 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 te the number of
14d30 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a columns in the.
14d40 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75 ** resu
14d50 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20 71 75 lt set of the qu
14d60 65 72 79 20 69 6e 74 6f 20 2a 70 6e 43 6f 6c 75 ery into *pnColu
14d70 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 mn..**.** {H1237
14d80 34 7d 20 49 66 20 74 68 65 20 70 6e 52 6f 77 20 4} If the pnRow
14d90 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 parameter to [sq
14da0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
14db0 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a )] is not NULL.*
14dc0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 * then
14dd0 61 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 a successful inv
14de0 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 ocation of [sqli
14df0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d te3_get_table()]
14e00 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 shall.**
14e10 20 20 20 77 72 69 74 65 73 20 74 68 65 20 6e 75 writes the nu
14e20 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 20 mber of rows in
14e30 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
14e40 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 result set of th
14e50 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a 70 6e e query into *pn
14e60 52 6f 77 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 Row..**.** {H123
14e70 37 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 76} A successful
14e80 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b invocation of [
14e90 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
14ea0 65 28 29 5d 20 74 68 61 74 20 63 6f 6d 70 75 74 e()] that comput
14eb0 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e es.** N
14ec0 20 72 6f 77 73 20 6f 66 20 72 65 73 75 6c 74 20 rows of result
14ed0 77 69 74 68 20 43 20 63 6f 6c 75 6d 6e 73 20 70 with C columns p
14ee0 65 72 20 72 6f 77 20 73 68 61 6c 6c 20 6d 61 6b er row shall mak
14ef0 65 20 2a 70 61 7a 52 65 73 75 6c 74 0a 2a 2a 20 e *pazResult.**
14f00 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 20 74 point t
14f10 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f o an array of po
14f20 69 6e 74 65 72 73 20 74 6f 20 28 4e 2b 31 29 2a inters to (N+1)*
14f30 43 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 C strings where
14f40 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 the first.**
14f50 20 20 20 20 20 20 43 20 73 74 72 69 6e 67 73 20 C strings
14f60 61 72 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 are column names
14f70 20 61 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f as obtained fro
14f80 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 m.** [s
14f90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
14fa0 6d 65 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 me()] and the re
14fb0 73 74 20 61 72 65 20 63 6f 6c 75 6d 6e 20 72 65 st are column re
14fc0 73 75 6c 74 20 76 61 6c 75 65 73 0a 2a 2a 20 20 sult values.**
14fd0 20 20 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64 obtained
14fe0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 from [sqlite3_c
14ff0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a olumn_text()]..*
15000 2a 0a 2a 2a 20 7b 48 31 32 33 37 39 7d 20 54 68 *.** {H12379} Th
15010 65 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20 e values in the
15020 70 61 7a 52 65 73 75 6c 74 20 61 72 72 61 79 20 pazResult array
15030 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c returned by [sql
15040 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
15050 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 ].** sh
15060 61 6c 6c 20 72 65 6d 61 69 6e 20 76 61 6c 69 64 all remain valid
15070 20 75 6e 74 69 6c 20 63 6c 65 61 72 65 64 20 62 until cleared b
15080 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f y [sqlite3_free_
15090 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 table()]..**.**
150a0 7b 48 31 32 33 38 32 7d 20 57 68 65 6e 20 61 6e {H12382} When an
150b0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 error occurs du
150c0 72 69 6e 67 20 65 76 61 6c 75 61 74 69 6f 6e 20 ring evaluation
150d0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f of [sqlite3_get_
150e0 74 61 62 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20 table()].**
150f0 20 20 20 20 20 74 68 65 20 66 75 6e 63 74 69 6f the functio
15100 6e 20 73 68 61 6c 6c 20 73 65 74 20 2a 70 61 7a n shall set *paz
15110 52 65 73 75 6c 74 20 74 6f 20 4e 55 4c 4c 2c 20 Result to NULL,
15120 77 72 69 74 65 20 61 6e 20 65 72 72 6f 72 20 6d write an error m
15130 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 essage.**
15140 20 20 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f into memory o
15150 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
15160 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c lite3_malloc()],
15170 20 6d 61 6b 65 0a 2a 2a 20 20 20 20 20 20 20 20 make.**
15180 20 20 2a 2a 70 7a 45 72 72 6d 73 67 20 70 6f 69 **pzErrmsg poi
15190 6e 74 20 74 6f 20 74 68 61 74 20 65 72 72 6f 72 nt to that error
151a0 20 6d 65 73 73 61 67 65 2c 20 61 6e 64 20 72 65 message, and re
151b0 74 75 72 6e 20 61 0a 2a 2a 20 20 20 20 20 20 20 turn a.**
151c0 20 20 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b appropriate [
151d0 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a error code]..*/.
151e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f int sqlite3_get_
151f0 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 table(. sqlite3
15200 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f *db, /
15210 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 * An open databa
15220 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 se */. const ch
15230 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a ar *zSql, /*
15240 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 SQL to be evalu
15250 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a ated */. char *
15260 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 **pazResult,
15270 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 /* Results of th
15280 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 e query */. int
15290 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 *pnRow,
152a0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 /* Number of
152b0 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 result rows writ
152c0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e ten here */. in
152d0 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 t *pnColumn,
152e0 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 /* Number of
152f0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 result columns
15300 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a written here */.
15310 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 char **pzErrms
15320 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 g /* Error
15330 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 msg written her
15340 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c e */.);.void sql
15350 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 ite3_free_table(
15360 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a char **result);.
15370 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
15380 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e Formatted Strin
15390 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 g Printing Funct
153a0 69 6f 6e 73 20 7b 48 31 37 34 30 30 7d 20 3c 53 ions {H17400} <S
153b0 37 30 30 30 30 3e 3c 53 32 30 30 30 30 3e 0a 2a 70000><S20000>.*
153c0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
153d0 6e 65 73 20 61 72 65 20 77 6f 72 6b 61 6c 69 6b nes are workalik
153e0 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 es of the "print
153f0 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 f()" family of f
15400 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d unctions.** from
15410 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 the standard C
15420 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 library..**.** T
15430 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e he sqlite3_mprin
15440 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 tf() and sqlite3
15450 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 _vmprintf() rout
15460 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 ines write their
15470 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f .** results into
15480 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 memory obtained
15490 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
154a0 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 alloc()]..** The
154b0 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 strings returne
154c0 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 d by these two r
154d0 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 outines should b
154e0 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 e.** released by
154f0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
15500 5d 2e 20 20 42 6f 74 68 20 72 6f 75 74 69 6e 65 ]. Both routine
15510 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 s return a.** NU
15520 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 LL pointer if [s
15530 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
15540 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c is unable to al
15550 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a locate enough.**
15560 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 memory to hold
15570 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 the resulting st
15580 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 ring..**.** In s
15590 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
155a0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d ) routine is sim
155b0 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 ilar to "snprint
155c0 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 f()" from.** the
155d0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 standard C libr
155e0 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 ary. The result
155f0 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f is written into
15600 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 the.** buffer s
15610 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 upplied as the s
15620 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
15630 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 whose size is gi
15640 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 ven by.** the fi
15650 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e rst parameter. N
15660 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 ote that the ord
15670 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 er of the.** fir
15680 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 st two parameter
15690 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 s is reversed fr
156a0 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 20 20 om snprintf().
156b0 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 This is an.** hi
156c0 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e storical acciden
156d0 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 t that cannot be
156e0 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 fixed without b
156f0 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 reaking.** backw
15700 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 ards compatibili
15710 74 79 2e 20 20 4e 6f 74 65 20 61 6c 73 6f 20 74 ty. Note also t
15720 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 hat sqlite3_snpr
15730 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e intf().** return
15740 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 s a pointer to i
15750 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 ts buffer instea
15760 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 d of the number
15770 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 of.** characters
15780 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 actually writte
15790 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 n into the buffe
157a0 72 2e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 r. We admit tha
157b0 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 t.** the number
157c0 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 of characters wr
157d0 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 itten would be a
157e0 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 more useful ret
157f0 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 urn.** value but
15800 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 we cannot chang
15810 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 e the implementa
15820 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f tion of sqlite3_
15830 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f snprintf().** no
15840 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 w without breaki
15850 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ng compatibility
15860 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 ..**.** As long
15870 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 as the buffer si
15880 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 ze is greater th
15890 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 an zero, sqlite3
158a0 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 _snprintf().** g
158b0 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 uarantees that t
158c0 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 he buffer is alw
158d0 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 ays zero-termina
158e0 74 65 64 2e 20 20 54 68 65 20 66 69 72 73 74 0a ted. The first.
158f0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 ** parameter "n"
15900 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 is the total si
15910 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 ze of the buffer
15920 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 , including spac
15930 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 e for.** the zer
15940 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 o terminator. S
15950 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 o the longest st
15960 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 ring that can be
15970 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 completely.** w
15980 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e ritten will be n
15990 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a -1 characters..*
159a0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
159b0 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e nes all implemen
159c0 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 t some additiona
159d0 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 l formatting.**
159e0 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 options that are
159f0 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 useful for cons
15a00 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 tructing SQL sta
15a10 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 tements..** All
15a20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 of the usual pri
15a30 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 ntf() formatting
15a40 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 options apply.
15a50 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 In addition, th
15a60 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 ere.** is are "%
15a70 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 q", "%Q", and "%
15a80 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a z" options..**.*
15a90 2a 20 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 * The %q option
15aa0 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e works like %s in
15ab0 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 that it substit
15ac0 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d utes a null-term
15ad0 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 inated.** string
15ae0 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 from the argume
15af0 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 nt list. But %q
15b00 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 also doubles ev
15b10 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 ery '\'' charact
15b20 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 er..** %q is des
15b30 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e igned for use in
15b40 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 side a string li
15b50 74 65 72 61 6c 2e 20 20 42 79 20 64 6f 75 62 6c teral. By doubl
15b60 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a ing each '\''.**
15b70 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73 character it es
15b80 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61 capes that chara
15b90 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 cter and allows
15ba0 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 it to be inserte
15bb0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 d into.** the st
15bc0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 ring..**.** For
15bd0 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 example, assume
15be0 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 the string varia
15bf0 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 ble zText contai
15c00 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f ns text as follo
15c10 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b ws:.**.** <block
15c20 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
15c30 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 char *zText = "I
15c40 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 t's a happy day!
15c50 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c ";.** </pre></bl
15c60 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
15c70 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 One can use this
15c80 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 text in an SQL
15c90 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c statement as fol
15ca0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f lows:.**.** <blo
15cb0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
15cc0 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 char *zSQL = s
15cd0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 qlite3_mprintf("
15ce0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c INSERT INTO tabl
15cf0 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c e VALUES('%q')",
15d00 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c zText);.** sql
15d10 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 ite3_exec(db, zS
15d20 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a QL, 0, 0, 0);.**
15d30 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a sqlite3_free(z
15d40 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c SQL);.** </pre><
15d50 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
15d60 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25 ** Because the %
15d70 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 q format string
15d80 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 is used, the '\'
15d90 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a ' character in z
15da0 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 Text.** is escap
15db0 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 ed and the SQL g
15dc0 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66 enerated is as f
15dd0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ollows:.**.** <b
15de0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
15df0 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 ** INSERT INTO
15e00 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 table1 VALUES('I
15e10 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79 t''s a happy day
15e20 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 !').** </pre></b
15e30 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
15e40 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 This is correct
15e50 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25 . Had we used %
15e60 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c s instead of %q,
15e70 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 the generated S
15e80 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 QL.** would have
15e90 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 looked like thi
15ea0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 s:.**.** <blockq
15eb0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 uote><pre>.** I
15ec0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 NSERT INTO table
15ed0 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 1 VALUES('It's a
15ee0 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a happy day!');.*
15ef0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
15f00 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 uote>.**.** This
15f10 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 second example
15f20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 is an SQL syntax
15f30 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 error. As a ge
15f40 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 neral rule you s
15f50 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 hould.** always
15f60 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f use %q instead o
15f70 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 f %s when insert
15f80 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 ing text into a
15f90 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a string literal..
15fa0 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f 70 74 **.** The %Q opt
15fb0 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 ion works like %
15fc0 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f q except it also
15fd0 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f adds single quo
15fe0 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 tes around.** th
15ff0 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 e outside of the
16000 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 total string.
16010 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 Additionally, if
16020 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 the parameter i
16030 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e n the.** argumen
16040 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c t list is a NULL
16050 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 pointer, %Q sub
16060 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 stitutes the tex
16070 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 t "NULL" (withou
16080 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 t.** single quot
16090 65 73 29 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 es) in place of
160a0 74 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e 20 20 the %Q option.
160b0 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c So, for example,
160c0 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a one could say:.
160d0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
160e0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 e><pre>.** char
160f0 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 *zSQL = sqlite3
16100 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 _mprintf("INSERT
16110 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 INTO table VALU
16120 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b ES(%Q)", zText);
16130 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 .** sqlite3_exe
16140 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 c(db, zSQL, 0, 0
16150 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 , 0);.** sqlite
16160 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 3_free(zSQL);.**
16170 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
16180 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 ote>.**.** The c
16190 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 ode above will r
161a0 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 ender a correct
161b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e SQL statement in
161c0 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 the zSQL.** var
161d0 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 iable even if th
161e0 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 e zText variable
161f0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
16200 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22 25 er..**.** The "%
16210 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 z" formatting op
16220 74 69 6f 6e 20 77 6f 72 6b 73 20 65 78 61 63 74 tion works exact
16230 6c 79 20 6c 69 6b 65 20 22 25 73 22 20 77 69 74 ly like "%s" wit
16240 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f h the.** additio
16250 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 n that after the
16260 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e string has been
16270 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 read and copied
16280 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 into.** the res
16290 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 ult, [sqlite3_fr
162a0 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 ee()] is called
162b0 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 on the input str
162c0 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a ing. {END}.**.**
162d0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
162e0 2a 2a 20 7b 48 31 37 34 30 33 7d 20 20 54 68 65 ** {H17403} The
162f0 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 [sqlite3_mprint
16300 66 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 f()] and [sqlite
16310 33 5f 76 6d 70 72 69 6e 74 66 28 29 5d 20 69 6e 3_vmprintf()] in
16320 74 65 72 66 61 63 65 73 0a 2a 2a 20 20 20 20 20 terfaces.**
16330 20 20 20 20 20 20 72 65 74 75 72 6e 20 65 69 74 return eit
16340 68 65 72 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 her pointers to
16350 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
16360 55 54 46 2d 38 20 73 74 72 69 6e 67 73 20 68 65 UTF-8 strings he
16370 6c 64 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 ld in.**
16380 20 20 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e memory obtain
16390 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
163a0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 4e 55 _malloc()] or NU
163b0 4c 4c 20 70 6f 69 6e 74 65 72 73 20 69 66 0a 2a LL pointers if.*
163c0 2a 20 20 20 20 20 20 20 20 20 20 20 61 20 63 61 * a ca
163d0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d ll to [sqlite3_m
163e0 61 6c 6c 6f 63 28 29 5d 20 66 61 69 6c 73 2e 0a alloc()] fails..
163f0 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 36 7d 20 20 **.** {H17406}
16400 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 The [sqlite3_snp
16410 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61 rintf()] interfa
16420 63 65 20 77 72 69 74 65 73 20 61 20 7a 65 72 6f ce writes a zero
16430 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 -terminated.**
16440 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 20 73 UTF-8 s
16450 74 72 69 6e 67 20 69 6e 74 6f 20 74 68 65 20 62 tring into the b
16460 75 66 66 65 72 20 70 6f 69 6e 74 65 64 20 74 6f uffer pointed to
16470 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 by the second p
16480 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 arameter.**
16490 20 20 20 20 20 20 70 72 6f 76 69 64 65 64 20 74 provided t
164a0 68 61 74 20 74 68 65 20 66 69 72 73 74 20 70 61 hat the first pa
164b0 72 61 6d 65 74 65 72 20 69 73 20 67 72 65 61 74 rameter is great
164c0 65 72 20 74 68 61 6e 20 7a 65 72 6f 2e 0a 2a 2a er than zero..**
164d0 0a 2a 2a 20 7b 48 31 37 34 30 37 7d 20 20 54 68 .** {H17407} Th
164e0 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 e [sqlite3_snpri
164f0 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ntf()] interface
16500 20 64 6f 65 73 20 6e 6f 74 20 77 72 69 74 65 20 does not write
16510 73 6c 6f 74 73 20 6f 66 0a 2a 2a 20 20 20 20 20 slots of.**
16520 20 20 20 20 20 20 69 74 73 20 6f 75 74 70 75 74 its output
16530 20 62 75 66 66 65 72 20 28 74 68 65 20 73 65 63 buffer (the sec
16540 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 29 20 6f ond parameter) o
16550 75 74 73 69 64 65 20 74 68 65 20 72 61 6e 67 65 utside the range
16560 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 66 .** of
16570 20 30 20 74 68 72 6f 75 67 68 20 4e 2d 31 20 28 0 through N-1 (
16580 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 66 where N is the f
16590 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a irst parameter).
165a0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 67 ** reg
165b0 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6c ardless of the l
165c0 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 ength of the str
165d0 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ing.**
165e0 20 72 65 71 75 65 73 74 65 64 20 62 79 20 74 68 requested by th
165f0 65 20 66 6f 72 6d 61 74 20 73 70 65 63 69 66 69 e format specifi
16600 63 61 74 69 6f 6e 2e 0a 2a 2f 0a 63 68 61 72 20 cation..*/.char
16610 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 *sqlite3_mprintf
16620 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e (const char*,...
16630 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 );.char *sqlite3
16640 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 _vmprintf(const
16650 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b char*, va_list);
16660 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 .char *sqlite3_s
16670 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 nprintf(int,char
16680 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e *,const char*, .
16690 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ..);../*.** CAPI
166a0 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 3REF: Memory All
166b0 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 ocation Subsyste
166c0 6d 20 7b 48 31 37 33 30 30 7d 20 3c 53 32 30 30 m {H17300} <S200
166d0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 00>.**.** The SQ
166e0 4c 69 74 65 20 63 6f 72 65 20 20 75 73 65 73 20 Lite core uses
166f0 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 these three rout
16700 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 ines for all of
16710 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 its own.** inter
16720 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 nal memory alloc
16730 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f ation needs. "Co
16740 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 re" in the previ
16750 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 ous sentence.**
16760 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 does not include
16770 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 operating-syste
16780 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 m specific VFS i
16790 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 mplementation.
167a0 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 The.** Windows V
167b0 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d FS uses native m
167c0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 alloc() and free
167d0 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 () for some oper
167e0 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 ations..**.** Th
167f0 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 e sqlite3_malloc
16800 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 () routine retur
16810 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
16820 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 a block.** of me
16830 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 mory at least N
16840 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c bytes in length,
16850 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 where N is the
16860 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 49 66 parameter..** If
16870 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
16880 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f ) is unable to o
16890 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 btain sufficient
168a0 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c free.** memory,
168b0 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 it returns a NU
168c0 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 LL pointer. If
168d0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 the parameter N
168e0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 to.** sqlite3_ma
168f0 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f lloc() is zero o
16900 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 r negative then
16910 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
16920 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 returns.** a NU
16930 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
16940 2a 20 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 * Calling sqlite
16950 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20 3_free() with a
16960 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 pointer previous
16970 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 ly returned.** b
16980 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 y sqlite3_malloc
16990 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 () or sqlite3_re
169a0 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 alloc() releases
169b0 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a that memory so.
169c0 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 ** that it might
169d0 20 62 65 20 72 65 75 73 65 64 2e 20 20 54 68 65 be reused. The
169e0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 sqlite3_free()
169f0 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 routine is.** a
16a00 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c no-op if is call
16a10 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 ed with a NULL p
16a20 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 ointer. Passing
16a30 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a a NULL pointer.
16a40 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 ** to sqlite3_fr
16a50 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 ee() is harmless
16a60 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 . After being f
16a70 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 reed, memory.**
16a80 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 should neither b
16a90 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 e read nor writt
16aa0 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e en. Even readin
16ab0 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 g previously fre
16ac0 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 ed.** memory mig
16ad0 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 ht result in a s
16ae0 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c egmentation faul
16af0 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 t or other sever
16b00 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f e error..** Memo
16b10 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 ry corruption, a
16b20 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 segmentation fa
16b30 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 ult, or other se
16b40 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 vere error.** mi
16b50 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 ght result if sq
16b60 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 lite3_free() is
16b70 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f called with a no
16b80 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 n-NULL pointer t
16b90 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f hat.** was not o
16ba0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c btained from sql
16bb0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 ite3_malloc() or
16bc0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
16bd0 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ()..**.** The sq
16be0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 lite3_realloc()
16bf0 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 interface attemp
16c00 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a ts to resize a.*
16c10 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 * prior memory a
16c20 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 llocation to be
16c30 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 at least N bytes
16c40 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 , where N is the
16c50 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d .** second param
16c60 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 eter. The memor
16c70 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 y allocation to
16c80 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 be resized is th
16c90 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d e first.** param
16ca0 65 74 65 72 2e 20 20 49 66 20 74 68 65 20 66 69 eter. If the fi
16cb0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f rst parameter to
16cc0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
16cd0 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 ().** is a NULL
16ce0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 pointer then its
16cf0 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 behavior is ide
16d00 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e ntical to callin
16d10 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c g.** sqlite3_mal
16d20 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 loc(N) where N i
16d30 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 s the second par
16d40 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
16d50 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 3_realloc()..**
16d60 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 If the second pa
16d70 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
16d80 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 e3_realloc() is
16d90 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 zero or.** negat
16da0 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 ive then the beh
16db0 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 avior is exactly
16dc0 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c the same as cal
16dd0 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ling.** sqlite3_
16de0 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20 free(P) where P
16df0 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 is the first par
16e00 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
16e10 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 3_realloc()..**
16e20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
16e30 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e ) returns a poin
16e40 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 ter to a memory
16e50 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 allocation.** of
16e60 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 at least N byte
16e70 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c s in size or NUL
16e80 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 L if sufficient
16e90 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 memory is unavai
16ea0 6c 61 62 6c 65 2e 0a 2a 2a 20 49 66 20 4d 20 69 lable..** If M i
16eb0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 s the size of th
16ec0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 e prior allocati
16ed0 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d on, then min(N,M
16ee0 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 ) bytes.** of th
16ef0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 e prior allocati
16f00 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e on are copied in
16f10 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 to the beginning
16f20 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72 of buffer retur
16f30 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 ned.** by sqlite
16f40 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 3_realloc() and
16f50 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 the prior alloca
16f60 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a tion is freed..*
16f70 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 * If sqlite3_rea
16f80 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e lloc() returns N
16f90 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 ULL, then the pr
16fa0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a ior allocation.*
16fb0 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a * is not freed..
16fc0 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 **.** The memory
16fd0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
16fe0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e ite3_malloc() an
16ff0 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f d sqlite3_reallo
17000 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 c().** is always
17010 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c aligned to at l
17020 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 east an 8 byte b
17030 6f 75 6e 64 61 72 79 2e 20 7b 45 4e 44 7d 0a 2a oundary. {END}.*
17040 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 *.** The default
17050 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
17060 6f 66 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c of the memory al
17070 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 location subsyst
17080 65 6d 20 75 73 65 73 0a 2a 2a 20 74 68 65 20 6d em uses.** the m
17090 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 alloc(), realloc
170a0 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 70 72 () and free() pr
170b0 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 73 74 ovided by the st
170c0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 andard C library
170d0 2e 0a 2a 2a 20 7b 48 31 37 33 38 32 7d 20 48 6f ..** {H17382} Ho
170e0 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 wever, if SQLite
170f0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
17100 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f h the.** SQLITE_
17110 4d 45 4d 4f 52 59 5f 53 49 5a 45 3d 3c 69 3e 4e MEMORY_SIZE=<i>N
17120 4e 4e 3c 2f 69 3e 20 43 20 70 72 65 70 72 6f 63 NN</i> C preproc
17130 65 73 73 6f 72 20 6d 61 63 72 6f 20 28 77 68 65 essor macro (whe
17140 72 65 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 0a 2a 2a re <i>NNN</i>.**
17150 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 29 2c is an integer),
17160 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 72 65 then SQLite cre
17170 61 74 65 20 61 20 73 74 61 74 69 63 20 61 72 72 ate a static arr
17180 61 79 20 6f 66 20 61 74 20 6c 65 61 73 74 0a 2a ay of at least.*
17190 2a 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 74 * <i>NNN</i> byt
171a0 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 20 75 es in size and u
171b0 73 65 73 20 74 68 61 74 20 61 72 72 61 79 20 66 ses that array f
171c0 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 or all of its dy
171d0 6e 61 6d 69 63 0a 2a 2a 20 6d 65 6d 6f 72 79 20 namic.** memory
171e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 allocation needs
171f0 2e 20 7b 45 4e 44 7d 20 20 41 64 64 69 74 69 6f . {END} Additio
17200 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 nal memory alloc
17210 61 74 6f 72 20 6f 70 74 69 6f 6e 73 0a 2a 2a 20 ator options.**
17220 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 may be added in
17230 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e future releases.
17240 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 .**.** In SQLite
17250 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 version 3.5.0 a
17260 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 nd 3.5.1, it was
17270 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 possible to def
17280 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 ine.** the SQLIT
17290 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c E_OMIT_MEMORY_AL
172a0 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 LOCATION which w
172b0 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 ould cause the b
172c0 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 uilt-in.** imple
172d0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 mentation of the
172e0 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 se routines to b
172f0 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 e omitted. That
17300 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 capability.** i
17310 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 s no longer prov
17320 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c ided. Only buil
17330 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f t-in memory allo
17340 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 cators can be us
17350 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 ed..**.** The Wi
17360 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 ndows OS interfa
17370 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a ce layer calls.*
17380 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c * the system mal
17390 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 loc() and free()
173a0 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 directly when c
173b0 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c onverting.** fil
173c0 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 enames between t
173d0 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e he UTF-8 encodin
173e0 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 g used by SQLite
173f0 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 .** and whatever
17400 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 filename encodi
17410 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 ng is used by th
17420 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e e particular Win
17430 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 dows.** installa
17440 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c tion. Memory al
17450 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 location errors
17460 61 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 are detected, bu
17470 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 t.** they are re
17480 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b ported back as [
17490 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d SQLITE_CANTOPEN]
174a0 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 or.** [SQLITE_I
174b0 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 OERR] rather tha
174c0 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d n [SQLITE_NOMEM]
174d0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
174e0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 TS:.**.** {H1730
174f0 33 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 3} The [sqlite3
17500 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 _malloc(N)] inte
17510 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 rface returns ei
17520 74 68 65 72 20 61 20 70 6f 69 6e 74 65 72 20 74 ther a pointer t
17530 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 o.** a
17540 20 6e 65 77 6c 79 20 63 68 65 63 6b 65 64 2d 6f newly checked-o
17550 75 74 20 62 6c 6f 63 6b 20 6f 66 20 61 74 20 6c ut block of at l
17560 65 61 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 east N bytes of
17570 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 memory.**
17580 20 20 20 20 74 68 61 74 20 69 73 20 38 2d 62 79 that is 8-by
17590 74 65 20 61 6c 69 67 6e 65 64 2c 20 6f 72 20 69 te aligned, or i
175a0 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 t returns NULL i
175b0 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 0a 2a f it is unable.*
175c0 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 66 * to f
175d0 75 6c 66 69 6c 6c 20 74 68 65 20 72 65 71 75 65 ulfill the reque
175e0 73 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 st..**.** {H1730
175f0 34 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 4} The [sqlite3
17600 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 _malloc(N)] inte
17610 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
17620 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 0a NULL pointer if.
17630 2a 2a 20 20 20 20 20 20 20 20 20 20 20 4e 20 69 ** N i
17640 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 s less than or e
17650 71 75 61 6c 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a qual to zero..**
17660 0a 2a 2a 20 7b 48 31 37 33 30 35 7d 20 20 54 68 .** {H17305} Th
17670 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 e [sqlite3_free(
17680 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 P)] interface re
17690 6c 65 61 73 65 73 20 6d 65 6d 6f 72 79 20 70 72 leases memory pr
176a0 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 eviously.**
176b0 20 20 20 20 20 20 72 65 74 75 72 6e 65 64 20 66 returned f
176c0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c rom [sqlite3_mal
176d0 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 loc()] or [sqlit
176e0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a e3_realloc()],.*
176f0 2a 20 20 20 20 20 20 20 20 20 20 20 6d 61 6b 69 * maki
17700 6e 67 20 69 74 20 61 76 61 69 6c 61 62 6c 65 20 ng it available
17710 66 6f 72 20 72 65 75 73 65 2e 0a 2a 2a 0a 2a 2a for reuse..**.**
17720 20 7b 48 31 37 33 30 36 7d 20 20 41 20 63 61 6c {H17306} A cal
17730 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 l to [sqlite3_fr
17740 65 65 28 4e 55 4c 4c 29 5d 20 69 73 20 61 20 68 ee(NULL)] is a h
17750 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a armless no-op..*
17760 2a 0a 2a 2a 20 7b 48 31 37 33 31 30 7d 20 20 41 *.** {H17310} A
17770 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
17780 33 5f 72 65 61 6c 6c 6f 63 28 30 2c 4e 29 5d 20 3_realloc(0,N)]
17790 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f is equivalent to
177a0 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 a call.**
177b0 20 20 20 20 20 74 6f 20 5b 73 71 6c 69 74 65 33 to [sqlite3
177c0 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 2e 0a 2a 2a 0a _malloc(N)]..**.
177d0 2a 2a 20 7b 48 31 37 33 31 32 7d 20 20 41 20 63 ** {H17312} A c
177e0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
177f0 72 65 61 6c 6c 6f 63 28 50 2c 30 29 5d 20 69 73 realloc(P,0)] is
17800 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 61 equivalent to a
17810 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 call.**
17820 20 20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 to [sqlite3_f
17830 72 65 65 28 50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b ree(P)]..**.** {
17840 48 31 37 33 31 35 7d 20 20 54 68 65 20 53 51 4c H17315} The SQL
17850 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 5b 73 ite core uses [s
17860 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
17870 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c , [sqlite3_reall
17880 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 oc()],.**
17890 20 20 20 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 and [sqlite3
178a0 5f 66 72 65 65 28 29 5d 20 66 6f 72 20 61 6c 6c _free()] for all
178b0 20 6f 66 20 69 74 73 20 6d 65 6d 6f 72 79 20 61 of its memory a
178c0 6c 6c 6f 63 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a llocation and.**
178d0 20 20 20 20 20 20 20 20 20 20 20 64 65 61 6c 6c deall
178e0 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a ocation needs..*
178f0 2a 0a 2a 2a 20 7b 48 31 37 33 31 38 7d 20 20 54 *.** {H17318} T
17900 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c he [sqlite3_real
17910 6c 6f 63 28 50 2c 4e 29 5d 20 69 6e 74 65 72 66 loc(P,N)] interf
17920 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 ace returns eith
17930 65 72 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 er a pointer.**
17940 20 20 20 20 20 20 20 20 20 20 74 6f 20 61 20 62 to a b
17950 6c 6f 63 6b 20 6f 66 20 63 68 65 63 6b 65 64 2d lock of checked-
17960 6f 75 74 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 out memory of at
17970 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 least N bytes i
17980 6e 20 73 69 7a 65 0a 2a 2a 20 20 20 20 20 20 20 n size.**
17990 20 20 20 20 74 68 61 74 20 69 73 20 38 2d 62 79 that is 8-by
179a0 74 65 20 61 6c 69 67 6e 65 64 2c 20 6f 72 20 61 te aligned, or a
179b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a NULL pointer..*
179c0 2a 0a 2a 2a 20 7b 48 31 37 33 32 31 7d 20 20 57 *.** {H17321} W
179d0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 hen [sqlite3_rea
179e0 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 lloc(P,N)] retur
179f0 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f ns a non-NULL po
17a00 69 6e 74 65 72 2c 20 69 74 20 66 69 72 73 74 0a inter, it first.
17a10 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f 70 ** cop
17a20 69 65 73 20 74 68 65 20 66 69 72 73 74 20 4b 20 ies the first K
17a30 62 79 74 65 73 20 6f 66 20 63 6f 6e 74 65 6e 74 bytes of content
17a40 20 66 72 6f 6d 20 50 20 69 6e 74 6f 20 74 68 65 from P into the
17a50 20 6e 65 77 6c 79 0a 2a 2a 20 20 20 20 20 20 20 newly.**
17a60 20 20 20 20 61 6c 6c 6f 63 61 74 65 64 20 62 6c allocated bl
17a70 6f 63 6b 2c 20 77 68 65 72 65 20 4b 20 69 73 20 ock, where K is
17a80 74 68 65 20 6c 65 73 73 65 72 20 6f 66 20 4e 20 the lesser of N
17a90 61 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 0a and the size of.
17aa0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 65 ** the
17ab0 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a buffer P..**.**
17ac0 20 7b 48 31 37 33 32 32 7d 20 20 57 68 65 6e 20 {H17322} When
17ad0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
17ae0 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 (P,N)] returns a
17af0 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 non-NULL pointe
17b00 72 2c 20 69 74 20 66 69 72 73 74 0a 2a 2a 20 20 r, it first.**
17b10 20 20 20 20 20 20 20 20 20 72 65 6c 65 61 73 65 release
17b20 73 20 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a s the buffer P..
17b30 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32 33 7d 20 20 **.** {H17323}
17b40 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 When [sqlite3_re
17b50 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 alloc(P,N)] retu
17b60 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 20 62 75 rns NULL, the bu
17b70 66 66 65 72 20 50 20 69 73 0a 2a 2a 20 20 20 20 ffer P is.**
17b80 20 20 20 20 20 20 20 6e 6f 74 20 6d 6f 64 69 66 not modif
17b90 69 65 64 20 6f 72 20 72 65 6c 65 61 73 65 64 2e ied or released.
17ba0 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f .**.** ASSUMPTIO
17bb0 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 37 33 35 NS:.**.** {A1735
17bc0 30 7d 20 20 54 68 65 20 70 6f 69 6e 74 65 72 20 0} The pointer
17bd0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 arguments to [sq
17be0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e lite3_free()] an
17bf0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c d [sqlite3_reall
17c00 6f 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 oc()].**
17c10 20 20 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 must be eithe
17c20 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 r NULL or else p
17c30 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 ointers obtained
17c40 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a from a prior.**
17c50 20 20 20 20 20 20 20 20 20 20 20 69 6e 76 6f 63 invoc
17c60 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 ation of [sqlite
17c70 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 3_malloc()] or [
17c80 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
17c90 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 )] that have.**
17ca0 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20 79 65 not ye
17cb0 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e t been released.
17cc0 0a 2a 2a 0a 2a 2a 20 7b 41 31 37 33 35 31 7d 20 .**.** {A17351}
17cd0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
17ce0 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f must not read o
17cf0 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 r write any part
17d00 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 of.**
17d10 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f a block of memo
17d20 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 ry after it has
17d30 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 been released us
17d40 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ing.**
17d50 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
17d60 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 ] or [sqlite3_re
17d70 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 alloc()]..*/.voi
17d80 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f d *sqlite3_mallo
17d90 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 c(int);.void *sq
17da0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f lite3_realloc(vo
17db0 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 id*, int);.void
17dc0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 sqlite3_free(voi
17dd0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d*);../*.** CAPI
17de0 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 3REF: Memory All
17df0 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 ocator Statistic
17e00 73 20 7b 48 31 37 33 37 30 7d 20 3c 53 33 30 32 s {H17370} <S302
17e10 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 10>.**.** SQLite
17e20 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 provides these
17e30 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 two interfaces f
17e40 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 or reporting on
17e50 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 the status.** of
17e60 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 the [sqlite3_ma
17e70 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 lloc()], [sqlite
17e80 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 3_free()], and [
17e90 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
17ea0 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 )].** routines,
17eb0 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 which form the b
17ec0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 uilt-in memory a
17ed0 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 llocation subsys
17ee0 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 tem..**.** INVAR
17ef0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 IANTS:.**.** {H1
17f00 37 33 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 7371} The [sqlit
17f10 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 e3_memory_used()
17f20 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ] routine return
17f30 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
17f40 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 bytes.**
17f50 20 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 of memory curr
17f60 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e ently outstandin
17f70 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 g (malloced but
17f80 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 0a 2a not freed)..**.*
17f90 2a 20 7b 48 31 37 33 37 33 7d 20 54 68 65 20 5b * {H17373} The [
17fa0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 sqlite3_memory_h
17fb0 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 ighwater()] rout
17fc0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ine returns the
17fd0 6d 61 78 69 6d 75 6d 0a 2a 2a 20 20 20 20 20 20 maximum.**
17fe0 20 20 20 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 value of [sq
17ff0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 lite3_memory_use
18000 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 d()] since the h
18010 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a igh-water mark.*
18020 2a 20 20 20 20 20 20 20 20 20 20 77 61 73 20 6c * was l
18030 61 73 74 20 72 65 73 65 74 2e 0a 2a 2a 0a 2a 2a ast reset..**.**
18040 20 7b 48 31 37 33 37 34 7d 20 54 68 65 20 76 61 {H17374} The va
18050 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 lues returned by
18060 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
18070 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 _used()] and.**
18080 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
18090 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 3_memory_highwat
180a0 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e er()] include an
180b0 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 20 20 y overhead.**
180c0 20 20 20 20 20 20 20 61 64 64 65 64 20 62 79 20 added by
180d0 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d SQLite in its im
180e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
180f0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
18100 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 )],.**
18110 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 but not overhead
18120 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e added by the an
18130 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 y underlying sys
18140 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 20 tem library.**
18150 20 20 20 20 20 20 20 20 72 6f 75 74 69 6e 65 73 routines
18160 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d that [sqlite3_m
18170 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c alloc()] may cal
18180 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 35 l..**.** {H17375
18190 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 } The memory hig
181a0 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 h-water mark is
181b0 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 reset to the cur
181c0 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a rent value of.**
181d0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
181e0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 e3_memory_used()
181f0 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 ] if and only if
18200 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 the parameter t
18210 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 o.** [s
18220 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
18230 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 ghwater()] is tr
18240 75 65 2e 20 20 54 68 65 20 76 61 6c 75 65 20 72 ue. The value r
18250 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 eturned.**
18260 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f by [sqlite3_
18270 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
18280 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 (1)] is the high
18290 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 20 -water mark.**
182a0 20 20 20 20 20 20 20 20 70 72 69 6f 72 20 74 6f prior to
182b0 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 the reset..*/.s
182c0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c qlite3_int64 sql
182d0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 ite3_memory_used
182e0 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f (void);.sqlite3_
182f0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 int64 sqlite3_me
18300 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 mory_highwater(i
18310 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a nt resetFlag);..
18320 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
18330 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 Pseudo-Random Nu
18340 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 20 7b mber Generator {
18350 48 31 37 33 39 30 7d 20 3c 53 32 30 30 30 30 3e H17390} <S20000>
18360 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f .**.** SQLite co
18370 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 ntains a high-qu
18380 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e ality pseudo-ran
18390 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 dom number gener
183a0 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 ator (PRNG) used
183b0 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 to.** select ra
183c0 6e 64 6f 6d 20 52 4f 57 49 44 73 20 77 68 65 6e ndom ROWIDs when
183d0 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 inserting new r
183e0 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 ecords into a ta
183f0 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 ble that.** alre
18400 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 ady uses the lar
18410 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 52 4f gest possible RO
18420 57 49 44 2e 20 20 54 68 65 20 50 52 4e 47 20 69 WID. The PRNG i
18430 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a s also used for.
18440 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 ** the build-in
18450 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e random() and ran
18460 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 domblob() SQL fu
18470 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 nctions. This i
18480 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a nterface allows.
18490 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 ** applications
184a0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 to access the sa
184b0 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 me PRNG for othe
184c0 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a r purposes..**.*
184d0 2a 20 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 * A call to this
184e0 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 routine stores
184f0 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f N bytes of rando
18500 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 mness into buffe
18510 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 r P..**.** The f
18520 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 irst time this r
18530 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 outine is invoke
18540 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e d (either intern
18550 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 ally or by.** th
18560 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 e application) t
18570 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 he PRNG is seede
18580 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 d using randomne
18590 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 ss obtained.** f
185a0 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e rom the xRandomn
185b0 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 ess method of th
185c0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 e default [sqlit
185d0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a e3_vfs] object..
185e0 2a 2a 20 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 ** On all subseq
185f0 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 uent invocations
18600 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e , the pseudo-ran
18610 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 domness is gener
18620 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c ated.** internal
18630 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 ly and without r
18640 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b ecourse to the [
18650 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 sqlite3_vfs] xRa
18660 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 ndomness.** meth
18670 6f 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 od..**.** INVARI
18680 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 ANTS:.**.** {H17
18690 33 39 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 392} The [sqlite
186a0 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 4e 2c 50 3_randomness(N,P
186b0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 72 69 )] interface wri
186c0 74 65 73 20 4e 20 62 79 74 65 73 20 6f 66 0a 2a tes N bytes of.*
186d0 2a 20 20 20 20 20 20 20 20 20 20 68 69 67 68 2d * high-
186e0 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 quality pseudo-r
186f0 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 andomness into b
18700 75 66 66 65 72 20 50 2e 0a 2a 2f 0a 76 6f 69 64 uffer P..*/.void
18710 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e sqlite3_randomn
18720 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 ess(int N, void
18730 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 *P);../*.** CAPI
18740 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 3REF: Compile-Ti
18750 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e me Authorization
18760 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 35 Callbacks {H125
18770 30 30 7d 20 3c 53 37 30 31 30 30 3e 0a 2a 2a 0a 00} <S70100>.**.
18780 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
18790 72 65 67 69 73 74 65 72 73 20 61 20 61 75 74 68 registers a auth
187a0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
187b0 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 with a particula
187c0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 r.** [database c
187d0 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 onnection], supp
187e0 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 lied in the firs
187f0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 t argument..** T
18800 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
18810 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
18820 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 d as SQL stateme
18830 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f nts are being co
18840 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 mpiled.** by [sq
18850 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d lite3_prepare()]
18860 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 or its variants
18870 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
18880 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c e_v2()],.** [sql
18890 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
188a0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 ] and [sqlite3_p
188b0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 repare16_v2()].
188c0 20 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 At various.** p
188d0 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 oints during the
188e0 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f compilation pro
188f0 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 cess, as logic i
18900 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a s being created.
18910 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 ** to perform va
18920 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 rious actions, t
18930 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
18940 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
18950 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 d to.** see if t
18960 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 hose actions are
18970 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20 61 allowed. The a
18980 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
18990 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 ck should.** ret
189a0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 urn [SQLITE_OK]
189b0 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 to allow the act
189c0 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e ion, [SQLITE_IGN
189d0 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 ORE] to disallow
189e0 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 the.** specific
189f0 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f action but allo
18a00 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d w the SQL statem
18a10 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 ent to continue
18a20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 to be.** compile
18a30 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 d, or [SQLITE_DE
18a40 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 NY] to cause the
18a50 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 entire SQL stat
18a60 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 ement to be.** r
18a70 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 ejected with an
18a80 65 72 72 6f 72 2e 20 20 49 66 20 74 68 65 20 61 error. If the a
18a90 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
18aa0 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e ck returns.** an
18ab0 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 y value other th
18ac0 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 an [SQLITE_IGNOR
18ad0 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c E], [SQLITE_OK],
18ae0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 or [SQLITE_DENY
18af0 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 ].** then the [s
18b00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
18b10 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 2()] or equivale
18b20 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 nt call that tri
18b30 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 ggered.** the au
18b40 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 thorizer will fa
18b50 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 il with an error
18b60 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 message..**.**
18b70 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 When the callbac
18b80 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 k returns [SQLIT
18b90 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e E_OK], that mean
18ba0 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a s the operation.
18bb0 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 ** requested is
18bc0 6f 6b 2e 20 20 57 68 65 6e 20 74 68 65 20 63 61 ok. When the ca
18bd0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b llback returns [
18be0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 SQLITE_DENY], th
18bf0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 e.** [sqlite3_pr
18c00 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 epare_v2()] or e
18c10 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 quivalent call t
18c20 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 hat triggered th
18c30 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 e.** authorizer
18c40 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 will fail with a
18c50 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 n error message
18c60 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a explaining that.
18c70 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e ** access is den
18c80 69 65 64 2e 20 20 49 66 20 74 68 65 20 61 75 74 ied. If the aut
18c90 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 69 73 20 horizer code is
18ca0 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a [SQLITE_READ].**
18cb0 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 and the callbac
18cc0 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 k returns [SQLIT
18cd0 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 E_IGNORE] then t
18ce0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 he.** [prepared
18cf0 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 statement] state
18d00 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 ment is construc
18d10 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 ted to substitut
18d20 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 e.** a NULL valu
18d30 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 e in place of th
18d40 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 e table column t
18d50 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a hat would have.*
18d60 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b * been read if [
18d70 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 SQLITE_OK] had b
18d80 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 een returned. T
18d90 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 he [SQLITE_IGNOR
18da0 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e E].** return can
18db0 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 be used to deny
18dc0 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 an untrusted us
18dd0 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 er access to ind
18de0 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d ividual.** colum
18df0 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a ns of a table..*
18e00 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 *.** The first p
18e10 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
18e20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
18e30 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 ack is a copy of
18e40 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 the third.** pa
18e50 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 rameter to the s
18e60 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
18e70 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 rizer() interfac
18e80 65 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 e. The second pa
18e90 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 rameter.** to th
18ea0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e e callback is an
18eb0 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 integer [SQLITE
18ec0 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 _COPY | action c
18ed0 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 ode] that specif
18ee0 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 ies.** the parti
18ef0 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 cular action to
18f00 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 54 be authorized. T
18f10 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 he third through
18f20 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 sixth parameter
18f30 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c s.** to the call
18f40 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 back are zero-te
18f50 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 rminated strings
18f60 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 that contain ad
18f70 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 ditional.** deta
18f80 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 ils about the ac
18f90 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f tion to be autho
18fa0 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 rized..**.** An
18fb0 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 authorizer is us
18fc0 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 ed when [sqlite3
18fd0 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 _prepare | prepa
18fe0 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 ring].** SQL sta
18ff0 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 tements from an
19000 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 untrusted source
19010 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 , to ensure that
19020 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
19030 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 nts.** do not tr
19040 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 y to access data
19050 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c they are not al
19060 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 lowed to see, or
19070 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f that they do no
19080 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 t.** try to exec
19090 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 ute malicious st
190a0 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 atements that da
190b0 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 mage the databas
190c0 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 e. For.** examp
190d0 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 le, an applicati
190e0 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 on may allow a u
190f0 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 ser to enter arb
19100 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 itrary.** SQL qu
19110 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 eries for evalua
19120 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 tion by a databa
19130 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 se. But the app
19140 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a lication does.**
19150 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 not want the us
19160 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f er to be able to
19170 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 make arbitrary
19180 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a changes to the.*
19190 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 * database. An
191a0 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 authorizer could
191b0 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 then be put in
191c0 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a place while the.
191d0 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 ** user-entered
191e0 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 SQL is being [sq
191f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 lite3_prepare |
19200 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a prepared] that.*
19210 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 * disallows ever
19220 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 ything except [S
19230 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 ELECT] statement
19240 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 s..**.** Applica
19250 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 tions that need
19260 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 to process SQL f
19270 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f rom untrusted so
19280 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 urces.** might a
19290 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 lso consider low
192a0 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c ering resource l
192b0 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c imits using [sql
192c0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a ite3_limit()].**
192d0 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 and limiting da
192e0 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e tabase size usin
192f0 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f g the [max_page_
19300 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a count] [PRAGMA].
19310 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 ** in addition t
19320 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f o using an autho
19330 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c rizer..**.** Onl
19340 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f y a single autho
19350 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 rizer can be in
19360 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 place on a datab
19370 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase connection.*
19380 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 * at a time. Ea
19390 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 ch call to sqlit
193a0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
193b0 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a r overrides the.
193c0 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c ** previous call
193d0 2e 20 20 44 69 73 61 62 6c 65 20 74 68 65 20 61 . Disable the a
193e0 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 uthorizer by ins
193f0 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 talling a NULL c
19400 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 allback..** The
19410 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 authorizer is di
19420 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c sabled by defaul
19430 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 t..**.** The aut
19440 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
19450 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 must not do any
19460 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 thing that will
19470 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 modify.** the da
19480 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
19490 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 n that invoked t
194a0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
194b0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 llback..** Note
194c0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 that [sqlite3_pr
194d0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 epare_v2()] and
194e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
194f0 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 both modify the
19500 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 ir.** database c
19510 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 onnections for t
19520 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d he meaning of "m
19530 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 odify" in this p
19540 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 aragraph..**.**
19550 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 When [sqlite3_pr
19560 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 epare_v2()] is u
19570 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 sed to prepare a
19580 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a statement, the.
19590 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 ** statement mig
195a0 68 74 20 62 65 20 72 65 70 72 65 70 61 72 65 64 ht be reprepared
195b0 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 during [sqlite3
195c0 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 _step()] due to
195d0 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 a .** schema cha
195e0 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 nge. Hence, the
195f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f application sho
19600 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 uld ensure that
19610 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 the.** correct a
19620 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
19630 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c ck remains in pl
19640 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b ace during the [
19650 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e sqlite3_step()].
19660 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 .**.** Note that
19670 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
19680 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
19690 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a ked only during.
196a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
196b0 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 are()] or its va
196c0 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 riants. Authori
196d0 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a zation is not.**
196e0 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e performed durin
196f0 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c g statement eval
19700 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 uation in [sqlit
19710 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a e3_step()]..**.*
19720 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
19730 0a 2a 2a 20 7b 48 31 32 35 30 31 7d 20 54 68 65 .** {H12501} The
19740 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
19750 74 68 6f 72 69 7a 65 72 28 44 2c 2e 2e 2e 29 5d thorizer(D,...)]
19760 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 interface regis
19770 74 65 72 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 ters a.**
19780 20 20 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 authorizer ca
19790 6c 6c 62 61 63 6b 20 77 69 74 68 20 64 61 74 61 llback with data
197a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
197b0 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 32 D..**.** {H12502
197c0 7d 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 } The authorizer
197d0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
197e0 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 oked as SQL stat
197f0 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 20 20 ements are.**
19800 20 20 20 20 20 20 20 62 65 69 6e 67 20 70 61 72 being par
19810 73 65 65 64 20 61 6e 64 20 63 6f 6d 70 69 6c 65 seed and compile
19820 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 33 d..**.** {H12503
19830 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 } If the authori
19840 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 zer callback ret
19850 75 72 6e 73 20 61 6e 79 20 76 61 6c 75 65 20 6f urns any value o
19860 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 ther than.**
19870 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 47 [SQLITE_IG
19880 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f NORE], [SQLITE_O
19890 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 K], or [SQLITE_D
198a0 45 4e 59 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 ENY], then.**
198b0 20 20 20 20 20 20 20 74 68 65 20 61 70 70 6c 69 the appli
198c0 63 61 74 69 6f 6e 20 69 6e 74 65 72 66 61 63 65 cation interface
198d0 20 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73 65 call that cause
198e0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 d.** th
198f0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
19900 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68 61 lback to run sha
19910 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 0a ll fail with an.
19920 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c ** [SQL
19930 49 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72 ITE_ERROR] error
19940 20 63 6f 64 65 20 61 6e 64 20 61 6e 20 61 70 70 code and an app
19950 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d ropriate error m
19960 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 essage..**.** {H
19970 31 32 35 30 34 7d 20 57 68 65 6e 20 74 68 65 20 12504} When the
19980 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
19990 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ack returns [SQL
199a0 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 20 6f 70 65 ITE_OK], the ope
199b0 72 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 ration.**
199c0 20 20 20 64 65 73 63 72 69 62 65 64 20 69 73 20 described is
199d0 70 72 6f 63 65 73 73 65 64 20 6e 6f 72 6d 61 6c processed normal
199e0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 ly..**.** {H1250
199f0 35 7d 20 57 68 65 6e 20 74 68 65 20 61 75 74 68 5} When the auth
19a00 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
19a10 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
19a20 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 20 20 DENY], the.**
19a30 20 20 20 20 20 20 20 61 70 70 6c 69 63 61 74 69 applicati
19a40 6f 6e 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c on interface cal
19a50 6c 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 l that caused th
19a60 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 e.** au
19a70 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
19a80 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c 6c 20 66 k to run shall f
19a90 61 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ail.**
19aa0 77 69 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f with an [SQLITE_
19ab0 45 52 52 4f 52 5d 20 65 72 72 6f 72 20 63 6f 64 ERROR] error cod
19ac0 65 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d e and an error m
19ad0 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 essage.**
19ae0 20 20 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 explaining th
19af0 61 74 20 61 63 63 65 73 73 20 69 73 20 64 65 6e at access is den
19b00 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 ied..**.** {H125
19b10 30 36 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 06} If the autho
19b20 72 69 7a 65 72 20 63 6f 64 65 20 28 74 68 65 20 rizer code (the
19b30 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 2nd parameter to
19b40 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 0a the authorizer.
19b50 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c ** call
19b60 62 61 63 6b 29 20 69 73 20 5b 53 51 4c 49 54 45 back) is [SQLITE
19b70 5f 52 45 41 44 5d 20 61 6e 64 20 74 68 65 20 61 _READ] and the a
19b80 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
19b90 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 ck returns.**
19ba0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 [SQLITE_I
19bb0 47 4e 4f 52 45 5d 2c 20 74 68 65 6e 20 74 68 65 GNORE], then the
19bc0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
19bd0 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 ent is construct
19be0 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 ed to.**
19bf0 20 20 69 6e 73 65 72 74 20 61 20 4e 55 4c 4c 20 insert a NULL
19c00 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f value in place o
19c10 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 f the table colu
19c20 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 mn that would ha
19c30 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 ve.** b
19c40 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c een read if [SQL
19c50 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e ITE_OK] had been
19c60 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
19c70 20 7b 48 31 32 35 30 37 7d 20 49 66 20 74 68 65 {H12507} If the
19c80 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 authorizer code
19c90 20 28 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 (the 2nd parame
19ca0 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f ter to the autho
19cb0 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 rizer.**
19cc0 20 20 63 61 6c 6c 62 61 63 6b 29 20 69 73 20 61 callback) is a
19cd0 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 nything other th
19ce0 61 6e 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d an [SQLITE_READ]
19cf0 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 , then.**
19d00 20 20 20 61 20 72 65 74 75 72 6e 20 6f 66 20 5b a return of [
19d10 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 68 SQLITE_IGNORE] h
19d20 61 73 20 74 68 65 20 73 61 6d 65 20 65 66 66 65 as the same effe
19d30 63 74 20 61 73 20 5b 53 51 4c 49 54 45 5f 44 45 ct as [SQLITE_DE
19d40 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 NY]..**.** {H125
19d50 31 30 7d 20 54 68 65 20 66 69 72 73 74 20 70 61 10} The first pa
19d60 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 rameter to the a
19d70 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
19d80 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a ck is a copy of.
19d90 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
19da0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
19db0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
19dc0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 set_authorizer()
19dd0 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a ] interface..**.
19de0 2a 2a 20 7b 48 31 32 35 31 31 7d 20 54 68 65 20 ** {H12511} The
19df0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
19e00 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
19e10 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a is an integer.*
19e20 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 * [SQLI
19e30 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e TE_COPY | action
19e40 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 code] that spec
19e50 69 66 69 65 73 20 74 68 65 20 70 61 72 74 69 63 ifies the partic
19e60 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 ular action.**
19e70 20 20 20 20 20 20 20 20 74 6f 20 62 65 20 61 75 to be au
19e80 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 thorized..**.**
19e90 7b 48 31 32 35 31 32 7d 20 54 68 65 20 74 68 69 {H12512} The thi
19ea0 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 rd through sixth
19eb0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 parameters to t
19ec0 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 0a he callback are.
19ed0 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f ** zero
19ee0 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 -terminated stri
19ef0 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e ngs that contain
19f00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 64 64 .** add
19f10 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20 itional details
19f20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e about the action
19f30 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 to be authorize
19f40 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 32 30 d..**.** {H12520
19f50 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b } Each call to [
19f60 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
19f70 6f 72 69 7a 65 72 28 29 5d 20 6f 76 65 72 72 69 orizer()] overri
19f80 64 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 des.**
19f90 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 69 any previously i
19fa0 6e 73 74 61 6c 6c 65 64 20 61 75 74 68 6f 72 69 nstalled authori
19fb0 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 zer..**.** {H125
19fc0 32 31 7d 20 41 20 4e 55 4c 4c 20 61 75 74 68 6f 21} A NULL autho
19fd0 72 69 7a 65 72 20 6d 65 61 6e 73 20 74 68 61 74 rizer means that
19fe0 20 6e 6f 20 61 75 74 68 6f 72 69 7a 61 74 69 6f no authorizatio
19ff0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 n.** ca
1a000 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
1a010 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 32 32 d..**.** {H12522
1a020 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 61 75 } The default au
1a030 74 68 6f 72 69 7a 65 72 20 69 73 20 4e 55 4c 4c thorizer is NULL
1a040 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
1a050 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 _set_authorizer(
1a060 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 . sqlite3*,. i
1a070 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 nt (*xAuth)(void
1a080 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 *,int,const char
1a090 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f *,const char*,co
1a0a0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 nst char*,const
1a0b0 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a char*),. void *
1a0c0 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a pUserData.);../*
1a0d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 .** CAPI3REF: Au
1a0e0 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 thorizer Return
1a0f0 43 6f 64 65 73 20 7b 48 31 32 35 39 30 7d 20 3c Codes {H12590} <
1a100 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 H12500>.**.** Th
1a110 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 e [sqlite3_set_a
1a120 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 uthorizer | auth
1a130 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
1a140 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a function] must.*
1a150 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 * return either
1a160 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f [SQLITE_OK] or o
1a170 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 ne of these two
1a180 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 constants in ord
1a190 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 er.** to signal
1a1a0 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f SQLite whether o
1a1b0 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e r not the action
1a1c0 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 is permitted.
1a1d0 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 See the.** [sqli
1a1e0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
1a1f0 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 er | authorizer
1a200 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 documentation] f
1a210 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a or additional.**
1a220 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f information..*/
1a230 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1a240 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 DENY 1 /* Ab
1a250 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 ort the SQL stat
1a260 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 ement with an er
1a270 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ror */.#define S
1a280 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 QLITE_IGNORE 2
1a290 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 /* Don't allow
1a2a0 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 access, but don'
1a2b0 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 t generate an er
1a2c0 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 ror */../*.** CA
1a2d0 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a PI3REF: Authoriz
1a2e0 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 20 er Action Codes
1a2f0 7b 48 31 32 35 35 30 7d 20 3c 48 31 32 35 30 30 {H12550} <H12500
1a300 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c >.**.** The [sql
1a310 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
1a320 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 zer()] interface
1a330 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c registers a cal
1a340 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a lback function.*
1a350 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 * that is invoke
1a360 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 d to authorize c
1a370 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 ertain SQL state
1a380 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 ment actions. T
1a390 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 he.** second par
1a3a0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 ameter to the ca
1a3b0 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 llback is an int
1a3c0 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 eger code that s
1a3d0 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 pecifies.** what
1a3e0 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 action is being
1a3f0 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 authorized. Th
1a400 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 ese are the inte
1a410 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 ger action codes
1a420 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 that.** the aut
1a430 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
1a440 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a may be passed..
1a450 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 **.** These acti
1a460 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 on code values s
1a470 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 ignify what kind
1a480 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 of operation is
1a490 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 to be.** author
1a4a0 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 ized. The 3rd a
1a4b0 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 nd 4th parameter
1a4c0 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 s to the authori
1a4d0 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 zation.** callba
1a4e0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c ck function will
1a4f0 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f be parameters o
1a500 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 r NULL depending
1a510 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 on which of the
1a520 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 se.** codes is u
1a530 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e sed as the secon
1a540 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 d parameter. Th
1a550 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 5th parameter
1a560 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 to the.** author
1a570 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 izer callback is
1a580 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
1a590 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e database ("main
1a5a0 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 ", "temp",.** et
1a5b0 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c c.) if applicabl
1a5c0 65 2e 20 20 54 68 65 20 36 74 68 20 70 61 72 61 e. The 6th para
1a5d0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 meter to the aut
1a5e0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
1a5f0 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 .** is the name
1a600 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 of the inner-mos
1a610 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 t trigger or vie
1a620 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e w that is respon
1a630 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 sible for.** the
1a640 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 access attempt
1a650 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 or NULL if this
1a660 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 access attempt i
1a670 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a s directly from.
1a680 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c ** top-level SQL
1a690 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 code..**.** INV
1a6a0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
1a6b0 48 31 32 35 35 31 7d 20 54 68 65 20 73 65 63 6f H12551} The seco
1a6c0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 nd parameter to
1a6d0 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b an.** [
1a6e0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
1a6f0 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 orizer | authori
1a700 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 73 68 zer callback] sh
1a710 61 6c 6c 20 62 65 20 61 6e 20 69 6e 74 65 67 65 all be an intege
1a720 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 r.** [S
1a730 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 75 74 QLITE_COPY | aut
1a740 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d 20 74 68 horizer code] th
1a750 61 74 20 73 70 65 63 69 66 69 65 73 20 77 68 61 at specifies wha
1a760 74 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 t action.**
1a770 20 20 20 20 20 69 73 20 62 65 69 6e 67 20 61 75 is being au
1a780 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 thorized..**.**
1a790 7b 48 31 32 35 35 32 7d 20 54 68 65 20 33 72 64 {H12552} The 3rd
1a7a0 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 and 4th paramet
1a7b0 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 ers to the.**
1a7c0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
1a7d0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c set_authorizer |
1a7e0 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63 authorization c
1a7f0 61 6c 6c 62 61 63 6b 5d 0a 2a 2a 20 20 20 20 20 allback].**
1a800 20 20 20 20 20 73 68 61 6c 6c 20 62 65 20 70 61 shall be pa
1a810 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c rameters or NULL
1a820 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 depending on wh
1a830 69 63 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ich.**
1a840 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 [SQLITE_COPY | a
1a850 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d 20 uthorizer code]
1a860 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 is used as the s
1a870 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e econd parameter.
1a880 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 33 7d 20 .**.** {H12553}
1a890 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 The 5th paramete
1a8a0 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 r to the.**
1a8b0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 [sqlite3_se
1a8c0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 t_authorizer | a
1a8d0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
1a8e0 63 6b 5d 20 73 68 61 6c 6c 20 62 65 20 74 68 65 ck] shall be the
1a8f0 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 name.**
1a900 20 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 of the databas
1a910 65 20 28 65 78 61 6d 70 6c 65 3a 20 22 6d 61 69 e (example: "mai
1a920 6e 22 2c 20 22 74 65 6d 70 22 2c 20 65 74 63 2e n", "temp", etc.
1a930 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e ) if applicable.
1a940 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 34 7d 20 .**.** {H12554}
1a950 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 The 6th paramete
1a960 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 r to the.**
1a970 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 [sqlite3_se
1a980 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 t_authorizer | a
1a990 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
1a9a0 63 6b 5d 20 73 68 61 6c 6c 20 62 65 20 74 68 65 ck] shall be the
1a9b0 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 name.**
1a9c0 20 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d of the inner-m
1a9d0 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 ost trigger or v
1a9e0 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 iew that is resp
1a9f0 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 20 onsible for.**
1aa00 20 20 20 20 20 20 20 20 74 68 65 20 61 63 63 65 the acce
1aa10 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 ss attempt or NU
1aa20 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 LL if this acces
1aa30 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 s attempt is dir
1aa40 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 20 20 ectly from.**
1aa50 20 20 20 20 20 20 20 74 6f 70 2d 6c 65 76 65 6c top-level
1aa60 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a SQL code..*/./*
1aa70 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1aa80 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1aa90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a ********** 3rd *
1aaa0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 *********** 4th
1aab0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 ***********/.#de
1aac0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
1aad0 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 TE_INDEX
1aae0 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 1 /* Index N
1aaf0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e ame Table N
1ab00 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
1ab10 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
1ab20 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 E_TABLE
1ab30 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 2 /* Table Na
1ab40 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
1ab50 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
1ab60 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
1ab70 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 _TEMP_INDEX
1ab80 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 3 /* Index Nam
1ab90 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d e Table Nam
1aba0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
1abb0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
1abc0 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 TEMP_TABLE 4
1abd0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
1abe0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
1abf0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1ac00 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 SQLITE_CREATE_T
1ac10 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 EMP_TRIGGER 5
1ac20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d /* Trigger Nam
1ac30 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 e Table Name
1ac40 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1ac50 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 SQLITE_CREATE_TE
1ac60 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 MP_VIEW 6
1ac70 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 /* View Name
1ac80 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
1ac90 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1aca0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 QLITE_CREATE_TRI
1acb0 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20 GGER 7
1acc0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 /* Trigger Name
1acd0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
1ace0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1acf0 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 LITE_CREATE_VIEW
1ad00 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 8 /
1ad10 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 * View Name
1ad20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
1ad30 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1ad40 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 ITE_DELETE
1ad50 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 9 /*
1ad60 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
1ad70 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
1ad80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1ad90 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 TE_DROP_INDEX
1ada0 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 10 /*
1adb0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 Index Name
1adc0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
1add0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1ade0 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 E_DROP_TABLE
1adf0 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 11 /* T
1ae00 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
1ae10 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
1ae20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1ae30 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 _DROP_TEMP_INDEX
1ae40 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 12 /* In
1ae50 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 dex Name Ta
1ae60 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
1ae70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1ae80 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 DROP_TEMP_TABLE
1ae90 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 13 /* Tab
1aea0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
1aeb0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
1aec0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
1aed0 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 ROP_TEMP_TRIGGER
1aee0 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 14 /* Trig
1aef0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c ger Name Tabl
1af00 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
1af10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
1af20 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 OP_TEMP_VIEW
1af30 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 15 /* View
1af40 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
1af50 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
1af60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
1af70 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 P_TRIGGER
1af80 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 16 /* Trigge
1af90 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 r Name Table
1afa0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
1afb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
1afc0 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 _VIEW
1afd0 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 17 /* View Na
1afe0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 me NULL
1aff0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
1b000 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 ine SQLITE_INSER
1b010 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 T
1b020 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 18 /* Table Na
1b030 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
1b040 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
1b050 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 ne SQLITE_PRAGMA
1b060 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 1
1b070 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 9 /* Pragma Na
1b080 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f me 1st arg o
1b090 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e r NULL */.#defin
1b0a0 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 e SQLITE_READ
1b0b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20
1b0c0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
1b0d0 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d Column Nam
1b0e0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 e */.#define
1b0f0 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 SQLITE_SELECT
1b100 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 21
1b110 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 /* NULL
1b120 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
1b130 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1b140 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 SQLITE_TRANSACTI
1b150 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20 ON 22
1b160 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 /* NULL
1b170 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
1b180 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1b190 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 QLITE_UPDATE
1b1a0 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 23
1b1b0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
1b1c0 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 Column Name
1b1d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1b1e0 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 LITE_ATTACH
1b1f0 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 24 /
1b200 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 * Filename
1b210 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
1b220 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1b230 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 ITE_DETACH
1b240 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 25 /*
1b250 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 Database Name
1b260 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
1b270 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1b280 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 TE_ALTER_TABLE
1b290 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 26 /*
1b2a0 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 Database Name
1b2b0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
1b2c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1b2d0 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 E_REINDEX
1b2e0 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 27 /* I
1b2f0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e ndex Name N
1b300 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
1b310 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1b320 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 _ANALYZE
1b330 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 28 /* Ta
1b340 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
1b350 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
1b360 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1b370 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 CREATE_VTABLE
1b380 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 29 /* Tab
1b390 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 le Name Mod
1b3a0 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a ule Name */.
1b3b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
1b3c0 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 ROP_VTABLE
1b3d0 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 30 /* Tabl
1b3e0 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 e Name Modu
1b3f0 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 le Name */.#
1b400 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 define SQLITE_FU
1b410 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 NCTION
1b420 20 20 20 33 31 20 20 20 2f 2a 20 46 75 6e 63 74 31 /* Funct
1b430 69 6f 6e 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 ion Name NULL
1b440 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
1b450 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 efine SQLITE_COP
1b460 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 Y
1b470 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 0 /* No lon
1b480 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a ger used */../*.
1b490 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 ** CAPI3REF: Tra
1b4a0 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 cing And Profili
1b4b0 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 ng Functions {H1
1b4c0 32 32 38 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2280} <S60400>.*
1b4d0 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
1b4e0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
1b4f0 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c nes register cal
1b500 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 lback functions
1b510 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 that can be used
1b520 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 for.** tracing
1b530 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 and profiling th
1b540 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 e execution of S
1b550 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a QL statements..*
1b560 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 *.** The callbac
1b570 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 k function regis
1b580 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 tered by sqlite3
1b590 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f _trace() is invo
1b5a0 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 ked at.** variou
1b5b0 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 s times when an
1b5c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 SQL statement is
1b5d0 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 being run by [s
1b5e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a qlite3_step()]..
1b5f0 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 ** The callback
1b600 72 65 74 75 72 6e 73 20 61 20 55 54 46 2d 38 20 returns a UTF-8
1b610 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 rendering of the
1b620 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
1b630 65 78 74 0a 2a 2a 20 61 73 20 74 68 65 20 73 74 ext.** as the st
1b640 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 atement first be
1b650 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 20 gins executing.
1b660 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 61 6c 6c Additional call
1b670 62 61 63 6b 73 20 6f 63 63 75 72 0a 2a 2a 20 61 backs occur.** a
1b680 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 s each triggered
1b690 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 subprogram is e
1b6a0 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c ntered. The cal
1b6b0 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 lbacks for trigg
1b6c0 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 ers.** contain a
1b6d0 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 UTF-8 SQL comme
1b6e0 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 nt that identifi
1b6f0 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 0a es the trigger..
1b700 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 **.** The callba
1b710 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 ck function regi
1b720 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 stered by sqlite
1b730 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 3_profile() is i
1b740 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 nvoked.** as eac
1b750 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 h SQL statement
1b760 66 69 6e 69 73 68 65 73 2e 20 20 54 68 65 20 70 finishes. The p
1b770 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 rofile callback
1b780 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 contains.** the
1b790 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 original stateme
1b7a0 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 nt text and an e
1b7b0 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d stimate of wall-
1b7c0 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 clock time.** of
1b7d0 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 how long that s
1b7e0 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f tatement took to
1b7f0 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 run..**.** INVA
1b800 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 RIANTS:.**.** {H
1b810 31 32 32 38 31 7d 20 54 68 65 20 63 61 6c 6c 62 12281} The callb
1b820 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 ack function reg
1b830 69 73 74 65 72 65 64 20 62 79 20 5b 73 71 6c 69 istered by [sqli
1b840 74 65 33 5f 74 72 61 63 65 28 29 5d 20 0a 2a 2a te3_trace()] .**
1b850 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 shall
1b860 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 be invoked.**
1b870 20 20 20 20 20 20 20 77 68 65 6e 65 76 65 72 20 whenever
1b880 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 an SQL statement
1b890 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 74 6f first begins to
1b8a0 20 65 78 65 63 75 74 65 20 61 6e 64 0a 2a 2a 20 execute and.**
1b8b0 20 20 20 20 20 20 20 20 20 77 68 65 6e 65 76 65 wheneve
1b8c0 72 20 61 20 74 72 69 67 67 65 72 20 73 75 62 70 r a trigger subp
1b8d0 72 6f 67 72 61 6d 20 66 69 72 73 74 20 62 65 67 rogram first beg
1b8e0 69 6e 73 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a ins to run..**.*
1b8f0 2a 20 7b 48 31 32 32 38 32 7d 20 45 61 63 68 20 * {H12282} Each
1b900 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
1b910 5f 74 72 61 63 65 28 29 5d 20 73 68 61 6c 6c 20 _trace()] shall
1b920 6f 76 65 72 72 69 64 65 20 74 68 65 20 70 72 65 override the pre
1b930 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 viously.**
1b940 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20 74 registered t
1b950 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a race callback..*
1b960 2a 0a 2a 2a 20 7b 48 31 32 32 38 33 7d 20 41 20 *.** {H12283} A
1b970 4e 55 4c 4c 20 74 72 61 63 65 20 63 61 6c 6c 62 NULL trace callb
1b980 61 63 6b 20 73 68 61 6c 6c 20 64 69 73 61 62 6c ack shall disabl
1b990 65 20 74 72 61 63 69 6e 67 2e 0a 2a 2a 0a 2a 2a e tracing..**.**
1b9a0 20 7b 48 31 32 32 38 34 7d 20 54 68 65 20 66 69 {H12284} The fi
1b9b0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
1b9c0 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 the trace callba
1b9d0 63 6b 20 73 68 61 6c 6c 20 62 65 20 61 20 63 6f ck shall be a co
1b9e0 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 py of.**
1b9f0 20 20 74 68 65 20 70 6f 69 6e 74 65 72 20 77 68 the pointer wh
1ba00 69 63 68 20 77 61 73 20 74 68 65 20 33 72 64 20 ich was the 3rd
1ba10 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c argument to [sql
1ba20 69 74 65 33 5f 74 72 61 63 65 28 29 5d 2e 0a 2a ite3_trace()]..*
1ba30 2a 0a 2a 2a 20 7b 48 31 32 32 38 35 7d 20 54 68 *.** {H12285} Th
1ba40 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
1ba50 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 t to the trace c
1ba60 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20 allback is a.**
1ba70 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 zero-te
1ba80 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 rminated UTF-8 s
1ba90 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 tring containing
1baa0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 74 65 the original te
1bab0 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f xt.** o
1bac0 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d f the SQL statem
1bad0 65 6e 74 20 61 73 20 69 74 20 77 61 73 20 70 61 ent as it was pa
1bae0 73 73 65 64 20 69 6e 74 6f 20 5b 73 71 6c 69 74 ssed into [sqlit
1baf0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
1bb00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 .** or
1bb10 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 2c 20 the equivalent,
1bb20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e or an SQL commen
1bb30 74 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 t indicating the
1bb40 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 20 20 beginning.**
1bb50 20 20 20 20 20 20 20 6f 66 20 61 20 74 72 69 67 of a trig
1bb60 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 0a ger subprogram..
1bb70 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 37 7d 20 54 **.** {H12287} T
1bb80 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 he callback func
1bb90 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 tion registered
1bba0 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 by [sqlite3_prof
1bbb0 69 6c 65 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 ile()] is invoke
1bbc0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 d.** as
1bbd0 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d each SQL statem
1bbe0 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a ent finishes..**
1bbf0 0a 2a 2a 20 7b 48 31 32 32 38 38 7d 20 54 68 65 .** {H12288} The
1bc00 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
1bc10 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 to the profile
1bc20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f callback is a co
1bc30 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 py of.**
1bc40 20 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 the 3rd parame
1bc50 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
1bc60 70 72 6f 66 69 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a profile()]..**.*
1bc70 2a 20 7b 48 31 32 32 38 39 7d 20 54 68 65 20 73 * {H12289} The s
1bc80 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
1bc90 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63 to the profile c
1bca0 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20 allback is a.**
1bcb0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 zero-te
1bcc0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 rminated UTF-8 s
1bcd0 74 72 69 6e 67 20 74 68 61 74 20 63 6f 6e 74 61 tring that conta
1bce0 69 6e 73 20 74 68 65 20 63 6f 6d 70 6c 65 74 65 ins the complete
1bcf0 20 74 65 78 74 20 6f 66 0a 2a 2a 20 20 20 20 20 text of.**
1bd00 20 20 20 20 20 74 68 65 20 53 51 4c 20 73 74 61 the SQL sta
1bd10 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77 61 73 tement as it was
1bd20 20 70 72 6f 63 65 73 73 65 64 20 62 79 20 5b 73 processed by [s
1bd30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1bd40 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 2()].**
1bd50 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 or the equivale
1bd60 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 39 nt..**.** {H1229
1bd70 30 7d 20 54 68 65 20 74 68 69 72 64 20 70 61 72 0} The third par
1bd80 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70 72 ameter to the pr
1bd90 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 ofile callback i
1bda0 73 20 61 6e 20 65 73 74 69 6d 61 74 65 0a 2a 2a s an estimate.**
1bdb0 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 of the
1bdc0 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73 number of nanos
1bdd0 65 63 6f 6e 64 73 20 6f 66 20 77 61 6c 6c 2d 63 econds of wall-c
1bde0 6c 6f 63 6b 20 74 69 6d 65 20 72 65 71 75 69 72 lock time requir
1bdf0 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 ed to.**
1be00 20 20 72 75 6e 20 74 68 65 20 53 51 4c 20 73 74 run the SQL st
1be10 61 74 65 6d 65 6e 74 20 66 72 6f 6d 20 73 74 61 atement from sta
1be20 72 74 20 74 6f 20 66 69 6e 69 73 68 2e 0a 2a 2f rt to finish..*/
1be30 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 .SQLITE_EXPERIME
1be40 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 NTAL void *sqlit
1be50 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 e3_trace(sqlite3
1be60 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 *, void(*xTrace)
1be70 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 (void*,const cha
1be80 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c r*), void*);.SQL
1be90 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c ITE_EXPERIMENTAL
1bea0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 void *sqlite3_p
1beb0 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c rofile(sqlite3*,
1bec0 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 . void(*xProfi
1bed0 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 le)(void*,const
1bee0 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 char*,sqlite3_ui
1bef0 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a nt64), void*);..
1bf00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1bf10 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 Query Progress C
1bf20 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 31 30 allbacks {H12910
1bf30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a } <S60400>.**.**
1bf40 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f This routine co
1bf50 6e 66 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62 nfigures a callb
1bf60 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 ack function - t
1bf70 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 63 he.** progress c
1bf80 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 20 69 allback - that i
1bf90 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 s invoked period
1bfa0 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f ically during lo
1bfb0 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61 ng.** running ca
1bfc0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
1bfd0 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 exec()], [sqlite
1bfe0 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 3_step()] and.**
1bff0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 [sqlite3_get_ta
1c000 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d ble()]. An exam
1c010 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 ple use for this
1c020 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 .** interface is
1c030 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 to keep a GUI u
1c040 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 pdated during a
1c050 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a large query..**.
1c060 2a 2a 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 ** If the progre
1c070 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 ss callback retu
1c080 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 rns non-zero, th
1c090 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a e operation is.*
1c0a0 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 * interrupted.
1c0b0 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e This feature can
1c0c0 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c be used to impl
1c0d0 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 ement a.** "Canc
1c0e0 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 el" button on a
1c0f0 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 GUI progress dia
1c100 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 log box..**.** T
1c110 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 he progress hand
1c120 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 ler must not do
1c130 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 anything that wi
1c140 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 ll modify.** the
1c150 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1c160 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 tion that invoke
1c170 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 d the progress h
1c180 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 andler..** Note
1c190 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 that [sqlite3_pr
1c1a0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 epare_v2()] and
1c1b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
1c1c0 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 both modify the
1c1d0 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 ir.** database c
1c1e0 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 onnections for t
1c1f0 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d he meaning of "m
1c200 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 odify" in this p
1c210 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 aragraph..**.**
1c220 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
1c230 2a 20 7b 48 31 32 39 31 31 7d 20 54 68 65 20 63 * {H12911} The c
1c240 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
1c250 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 registered by s
1c260 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f qlite3_progress_
1c270 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 20 20 20 handler().**
1c280 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 is invoked
1c290 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 periodically du
1c2a0 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e ring long runnin
1c2b0 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20 g calls to.**
1c2c0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
1c2d0 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b step()]..**.** {
1c2e0 48 31 32 39 31 32 7d 20 54 68 65 20 70 72 6f 67 H12912} The prog
1c2f0 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 ress callback is
1c300 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f invoked once fo
1c310 72 20 65 76 65 72 79 20 4e 20 76 69 72 74 75 61 r every N virtua
1c320 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 61 l.** ma
1c330 63 68 69 6e 65 20 6f 70 63 6f 64 65 73 2c 20 77 chine opcodes, w
1c340 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 here N is the se
1c350 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
1c360 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
1c370 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 [sqlite3_progre
1c380 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 20 63 61 ss_handler()] ca
1c390 6c 6c 20 74 68 61 74 20 72 65 67 69 73 74 65 72 ll that register
1c3a0 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 ed.** t
1c3b0 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66 he callback. If
1c3c0 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 N is less than
1c3d0 31 2c 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 1, sqlite3_progr
1c3e0 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a ess_handler().**
1c3f0 20 20 20 20 20 20 20 20 20 20 61 63 74 73 20 61 acts a
1c400 73 20 69 66 20 61 20 4e 55 4c 4c 20 70 72 6f 67 s if a NULL prog
1c410 72 65 73 73 20 68 61 6e 64 6c 65 72 20 68 61 64 ress handler had
1c420 20 62 65 65 6e 20 73 70 65 63 69 66 69 65 64 2e been specified.
1c430 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 33 7d 20 .**.** {H12913}
1c440 54 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c The progress cal
1c450 6c 62 61 63 6b 20 69 74 73 65 6c 66 20 69 73 20 lback itself is
1c460 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 identified by th
1c470 65 20 74 68 69 72 64 0a 2a 2a 20 20 20 20 20 20 e third.**
1c480 20 20 20 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 argument to
1c490 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 sqlite3_progress
1c4a0 5f 68 61 6e 64 6c 65 72 28 29 2e 0a 2a 2a 0a 2a _handler()..**.*
1c4b0 2a 20 7b 48 31 32 39 31 34 7d 20 54 68 65 20 66 * {H12914} The f
1c4c0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 ourth argument t
1c4d0 6f 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 o sqlite3_progre
1c4e0 73 73 5f 68 61 6e 64 6c 65 72 28 29 20 69 73 20 ss_handler() is
1c4f0 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 6f a.** vo
1c500 69 64 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 id pointer passe
1c510 64 20 74 6f 20 74 68 65 20 70 72 6f 67 72 65 73 d to the progres
1c520 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 s callback.**
1c530 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 function
1c540 65 61 63 68 20 74 69 6d 65 20 69 74 20 69 73 20 each time it is
1c550 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b invoked..**.** {
1c560 48 31 32 39 31 35 7d 20 49 66 20 61 20 63 61 6c H12915} If a cal
1c570 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 l to [sqlite3_st
1c580 65 70 28 29 5d 20 72 65 73 75 6c 74 73 20 69 6e ep()] results in
1c590 20 66 65 77 65 72 20 74 68 61 6e 20 4e 20 6f 70 fewer than N op
1c5a0 63 6f 64 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 codes.**
1c5b0 20 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 being executed
1c5c0 2c 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 , then the progr
1c5d0 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 ess callback is
1c5e0 6e 65 76 65 72 20 69 6e 76 6f 6b 65 64 2e 0a 2a never invoked..*
1c5f0 2a 0a 2a 2a 20 7b 48 31 32 39 31 36 7d 20 45 76 *.** {H12916} Ev
1c600 65 72 79 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ery call to [sql
1c610 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 ite3_progress_ha
1c620 6e 64 6c 65 72 28 29 5d 0a 2a 2a 20 20 20 20 20 ndler()].**
1c630 20 20 20 20 20 6f 76 65 72 77 72 69 74 65 73 20 overwrites
1c640 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 72 any previously r
1c650 65 67 69 73 74 65 72 65 64 20 70 72 6f 67 72 65 egistered progre
1c660 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a ss handler..**.*
1c670 2a 20 7b 48 31 32 39 31 37 7d 20 49 66 20 74 68 * {H12917} If th
1c680 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c e progress handl
1c690 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e er callback is N
1c6a0 55 4c 4c 20 74 68 65 6e 20 6e 6f 20 70 72 6f 67 ULL then no prog
1c6b0 72 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 ress.**
1c6c0 20 68 61 6e 64 6c 65 72 20 69 73 20 69 6e 76 6f handler is invo
1c6d0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 ked..**.** {H129
1c6e0 31 38 7d 20 49 66 20 74 68 65 20 70 72 6f 67 72 18} If the progr
1c6f0 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 ess callback ret
1c700 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 6f 74 urns a result ot
1c710 68 65 72 20 74 68 61 6e 20 30 2c 20 74 68 65 6e her than 0, then
1c720 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
1c730 20 62 65 68 61 76 69 6f 72 20 69 73 20 61 20 69 behavior is a i
1c740 66 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 f [sqlite3_inter
1c750 72 75 70 74 28 29 5d 20 68 61 64 20 62 65 65 6e rupt()] had been
1c760 20 63 61 6c 6c 65 64 2e 0a 2a 2a 20 20 20 20 20 called..**
1c770 20 20 20 20 20 3c 53 33 30 35 30 30 3e 0a 2a 2f <S30500>.*/
1c780 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 .void sqlite3_pr
1c790 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 ogress_handler(s
1c7a0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e qlite3*, int, in
1c7b0 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 t(*)(void*), voi
1c7c0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d*);../*.** CAPI
1c7d0 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 3REF: Opening A
1c7e0 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e New Database Con
1c7f0 6e 65 63 74 69 6f 6e 20 7b 48 31 32 37 30 30 7d nection {H12700}
1c800 20 3c 53 34 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S40200>.**.**
1c810 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f These routines o
1c820 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 pen an SQLite da
1c830 74 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73 tabase file whos
1c840 65 20 6e 61 6d 65 20 69 73 20 67 69 76 65 6e 20 e name is given
1c850 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 by the.** filena
1c860 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 65 me argument. The
1c870 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 filename argume
1c880 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 nt is interprete
1c890 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a d as UTF-8 for.*
1c8a0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 * sqlite3_open()
1c8b0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 and sqlite3_ope
1c8c0 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 n_v2() and as UT
1c8d0 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 F-16 in the nati
1c8e0 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 ve byte.** order
1c8f0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 for sqlite3_ope
1c900 6e 31 36 28 29 2e 20 41 20 5b 64 61 74 61 62 61 n16(). A [databa
1c910 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 se connection] h
1c920 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 andle is usually
1c930 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 .** returned in
1c940 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 *ppDb, even if a
1c950 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 n error occurs.
1c960 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 The only except
1c970 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 ion is that.** i
1c980 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 f SQLite is unab
1c990 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d le to allocate m
1c9a0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 emory to hold th
1c9b0 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 e [sqlite3] obje
1c9c0 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 ct,.** a NULL wi
1c9d0 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e ll be written in
1c9e0 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 to *ppDb instead
1c9f0 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f of a pointer to
1ca00 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a the [sqlite3].*
1ca10 2a 20 6f 62 6a 65 63 74 2e 20 49 66 20 74 68 65 * object. If the
1ca20 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
1ca30 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 ned (and/or crea
1ca40 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c ted) successfull
1ca50 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 y, then.** [SQLI
1ca60 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e TE_OK] is return
1ca70 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 ed. Otherwise a
1ca80 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 n [error code] i
1ca90 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 s returned. The
1caa0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 .** [sqlite3_err
1cab0 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 msg()] or [sqlit
1cac0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 e3_errmsg16()] r
1cad0 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 outines can be u
1cae0 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a sed to obtain.**
1caf0 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 an English lang
1cb00 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e uage description
1cb10 20 6f 66 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a of the error..*
1cb20 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 *.** The default
1cb30 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 encoding for th
1cb40 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 e database will
1cb50 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 be UTF-8 if.** s
1cb60 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 qlite3_open() or
1cb70 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
1cb80 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 () is called and
1cb90 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 .** UTF-16 in th
1cba0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 e native byte or
1cbb0 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f der if sqlite3_o
1cbc0 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e pen16() is used.
1cbd0 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f .**.** Whether o
1cbe0 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f r not an error o
1cbf0 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 ccurs when it is
1cc00 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 opened, resourc
1cc10 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 es.** associated
1cc20 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 with the [datab
1cc30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
1cc40 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 handle should be
1cc50 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 released by.**
1cc60 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 passing it to [s
1cc70 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 qlite3_close()]
1cc80 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f when it is no lo
1cc90 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a nger required..*
1cca0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
1ccb0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 _open_v2() inter
1ccc0 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 face works like
1ccd0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a sqlite3_open().*
1cce0 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 * except that it
1ccf0 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 accepts two add
1cd00 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 itional paramete
1cd10 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 rs for additiona
1cd20 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 l control.** ove
1cd30 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 r the new databa
1cd40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 se connection.
1cd50 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 The flags parame
1cd60 74 65 72 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 ter can take one
1cd70 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f of.** the follo
1cd80 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 wing three value
1cd90 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f s, optionally co
1cda0 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 mbined with the
1cdb0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e .** [SQLITE_OPEN
1cdc0 5f 4e 4f 4d 55 54 45 58 5d 20 6f 72 20 5b 53 51 _NOMUTEX] or [SQ
1cdd0 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 LITE_OPEN_FULLMU
1cde0 54 45 58 5d 20 66 6c 61 67 73 3a 0a 2a 2a 0a 2a TEX] flags:.**.*
1cdf0 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 5b 53 * <dl>.** <dt>[S
1ce00 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
1ce10 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 NLY]</dt>.** <dd
1ce20 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 >The database is
1ce30 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d opened in read-
1ce40 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 only mode. If t
1ce50 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 he database does
1ce60 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 not.** already
1ce70 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 exist, an error
1ce80 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 is returned.</dd
1ce90 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c >.**.** <dt>[SQL
1cea0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 ITE_OPEN_READWRI
1ceb0 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TE]</dt>.** <dd>
1cec0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 The database is
1ced0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 opened for readi
1cee0 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 ng and writing i
1cef0 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 f possible, or r
1cf00 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 eading.** only i
1cf10 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 f the file is wr
1cf20 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 ite protected by
1cf30 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 the operating s
1cf40 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 ystem. In eithe
1cf50 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 r.** case the da
1cf60 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 tabase must alre
1cf70 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 ady exist, other
1cf80 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 wise an error is
1cf90 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a returned.</dd>.
1cfa0 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 **.** <dt>[SQLIT
1cfb0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 E_OPEN_READWRITE
1cfc0 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e ] | [SQLITE_OPEN
1cfd0 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a _CREATE]</dt>.**
1cfe0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 <dd>The databas
1cff0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 e is opened for
1d000 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 reading and writ
1d010 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 ing, and is crea
1d020 74 65 73 20 69 74 20 69 66 0a 2a 2a 20 69 74 20 tes it if.** it
1d030 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 does not already
1d040 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 exist. This is
1d050 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 the behavior tha
1d060 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 t is always used
1d070 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f for.** sqlite3_
1d080 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 open() and sqlit
1d090 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 e3_open16().</dd
1d0a0 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a >.** </dl>.**.**
1d0b0 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 If the 3rd para
1d0c0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
1d0d0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f _open_v2() is no
1d0e0 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 t one of the.**
1d0f0 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f combinations sho
1d100 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20 wn above or one
1d110 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e 61 74 69 of the combinati
1d120 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 ons shown above
1d130 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68 combined.** with
1d140 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 the [SQLITE_OPE
1d150 4e 5f 4e 4f 4d 55 54 45 58 5d 20 6f 72 20 5b 53 N_NOMUTEX] or [S
1d160 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d QLITE_OPEN_FULLM
1d170 55 54 45 58 5d 20 66 6c 61 67 73 2c 0a 2a 2a 20 UTEX] flags,.**
1d180 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f then the behavio
1d190 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a r is undefined..
1d1a0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53 51 **.** If the [SQ
1d1b0 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 LITE_OPEN_NOMUTE
1d1c0 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 X] flag is set,
1d1d0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 then the databas
1d1e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
1d1f0 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c opens in the mul
1d200 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 ti-thread [threa
1d210 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f ding mode] as lo
1d220 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 ng as the single
1d230 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 -thread.** mode
1d240 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 has not been set
1d250 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 at compile-time
1d260 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 or start-time.
1d270 20 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 If the.** [SQLI
1d280 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 TE_OPEN_FULLMUTE
1d290 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 X] flag is set t
1d2a0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
1d2b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e connection open
1d2c0 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 s.** in the seri
1d2d0 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e alized [threadin
1d2e0 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 g mode] unless s
1d2f0 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 ingle-thread was
1d300 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 .** previously s
1d310 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 elected at compi
1d320 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 le-time or start
1d330 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 -time..**.** If
1d340 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 the filename is
1d350 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e ":memory:", then
1d360 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 a private, temp
1d370 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 orary in-memory
1d380 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 database.** is c
1d390 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 reated for the c
1d3a0 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69 73 onnection. This
1d3b0 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 in-memory datab
1d3c0 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 ase will vanish
1d3d0 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 when.** the data
1d3e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
1d3f0 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 is closed. Futu
1d400 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 re versions of S
1d410 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d QLite might.** m
1d420 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 ake use of addit
1d430 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 ional special fi
1d440 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 lenames that beg
1d450 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 in with the ":"
1d460 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 character..** It
1d470 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
1d480 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 that when a data
1d490 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 base filename ac
1d4a0 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 tually does begi
1d4b0 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 n with.** a ":"
1d4c0 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 character you sh
1d4d0 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 ould prefix the
1d4e0 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 filename with a
1d4f0 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 pathname such as
1d500 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 .** "./" to avoi
1d510 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a d ambiguity..**.
1d520 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 ** If the filena
1d530 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 me is an empty s
1d540 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 tring, then a pr
1d550 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 ivate, temporary
1d560 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 .** on-disk data
1d570 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 base will be cre
1d580 61 74 65 64 2e 20 20 54 68 69 73 20 70 72 69 76 ated. This priv
1d590 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c ate database wil
1d5a0 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 l be.** automati
1d5b0 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 cally deleted as
1d5c0 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 soon as the dat
1d5d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1d5e0 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a is closed..**.*
1d5f0 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 * The fourth par
1d600 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
1d610 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 3_open_v2() is t
1d620 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a he name of the.*
1d630 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 * [sqlite3_vfs]
1d640 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 object that defi
1d650 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e nes the operatin
1d660 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 g system interfa
1d670 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e ce that.** the n
1d680 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ew database conn
1d690 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 ection should us
1d6a0 65 2e 20 20 49 66 20 74 68 65 20 66 6f 75 72 74 e. If the fourt
1d6b0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a h parameter is.*
1d6c0 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 * a NULL pointer
1d6d0 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c then the defaul
1d6e0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 t [sqlite3_vfs]
1d6f0 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a object is used..
1d700 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f **.** <b>Note to
1d710 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c Windows users:<
1d720 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e /b> The encodin
1d730 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 g used for the f
1d740 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 ilename argument
1d750 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f .** of sqlite3_o
1d760 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 pen() and sqlite
1d770 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 3_open_v2() must
1d780 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 be UTF-8, not w
1d790 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 hatever.** codep
1d7a0 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 age is currently
1d7b0 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e defined. Filen
1d7c0 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 ames containing
1d7d0 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a international.**
1d7e0 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 characters must
1d7f0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f be converted to
1d800 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 UTF-8 prior to
1d810 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 passing them int
1d820 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 o.** sqlite3_ope
1d830 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f n() or sqlite3_o
1d840 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 pen_v2()..**.**
1d850 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
1d860 2a 20 7b 48 31 32 37 30 31 7d 20 54 68 65 20 5b * {H12701} The [
1d870 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
1d880 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
1d890 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20 ()], and.**
1d8a0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 [sqlite3_op
1d8b0 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 en_v2()] interfa
1d8c0 63 65 73 20 63 72 65 61 74 65 20 61 20 6e 65 77 ces create a new
1d8d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 .** [da
1d8e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1d8f0 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 n] associated wi
1d900 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 th.** t
1d910 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
1d920 20 67 69 76 65 6e 20 69 6e 20 74 68 65 69 72 20 given in their
1d930 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e first parameter.
1d940 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 32 7d 20 .**.** {H12702}
1d950 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 The filename arg
1d960 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 ument is interpr
1d970 65 74 65 64 20 61 73 20 55 54 46 2d 38 0a 2a 2a eted as UTF-8.**
1d980 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 5b 73 for [s
1d990 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 qlite3_open()] a
1d9a0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e nd [sqlite3_open
1d9b0 5f 76 32 28 29 5d 20 61 6e 64 20 61 73 20 55 54 _v2()] and as UT
1d9c0 46 2d 31 36 0a 2a 2a 20 20 20 20 20 20 20 20 20 F-16.**
1d9d0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 in the native b
1d9e0 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 5b 73 yte order for [s
1d9f0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
1da00 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 33 7d ..**.** {H12703}
1da10 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e A successful in
1da20 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c vocation of [sql
1da30 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 ite3_open()], [s
1da40 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
1da50 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 ,.** or
1da60 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
1da70 32 28 29 5d 20 77 72 69 74 65 73 20 61 20 70 6f 2()] writes a po
1da80 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a inter to a new.*
1da90 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 * [data
1daa0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
1dab0 20 69 6e 74 6f 20 2a 70 70 44 62 2e 0a 2a 2a 0a into *ppDb..**.
1dac0 2a 2a 20 7b 48 31 32 37 30 34 7d 20 54 68 65 20 ** {H12704} The
1dad0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
1dae0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 , [sqlite3_open1
1daf0 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 6()], and.**
1db00 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f [sqlite3_o
1db10 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 pen_v2()] interf
1db20 61 63 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c aces return [SQL
1db30 49 54 45 5f 4f 4b 5d 20 75 70 6f 6e 20 73 75 63 ITE_OK] upon suc
1db40 63 65 73 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20 cess,.**
1db50 20 20 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 or an appropri
1db60 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d ate [error code]
1db70 20 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a on failure..**.
1db80 2a 2a 20 7b 48 31 32 37 30 36 7d 20 54 68 65 20 ** {H12706} The
1db90 64 65 66 61 75 6c 74 20 74 65 78 74 20 65 6e 63 default text enc
1dba0 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e 65 77 20 oding for a new
1dbb0 64 61 74 61 62 61 73 65 20 63 72 65 61 74 65 64 database created
1dbc0 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 using.**
1dbd0 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e [sqlite3_open
1dbe0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
1dbf0 6f 70 65 6e 5f 76 32 28 29 5d 20 77 69 6c 6c 20 open_v2()] will
1dc00 62 65 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 be UTF-8..**.**
1dc10 7b 48 31 32 37 30 37 7d 20 54 68 65 20 64 65 66 {H12707} The def
1dc20 61 75 6c 74 20 74 65 78 74 20 65 6e 63 6f 64 69 ault text encodi
1dc30 6e 67 20 66 6f 72 20 61 20 6e 65 77 20 64 61 74 ng for a new dat
1dc40 61 62 61 73 65 20 63 72 65 61 74 65 64 20 75 73 abase created us
1dc50 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ing.**
1dc60 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 [sqlite3_open16(
1dc70 29 5d 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 )] will be UTF-1
1dc80 36 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 39 6..**.** {H12709
1dc90 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f } The [sqlite3_o
1dca0 70 65 6e 28 46 2c 44 29 5d 20 69 6e 74 65 72 66 pen(F,D)] interf
1dcb0 61 63 65 20 69 73 20 65 71 75 69 76 61 6c 65 6e ace is equivalen
1dcc0 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 t to.**
1dcd0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
1dce0 32 28 46 2c 44 2c 47 2c 30 29 5d 20 77 68 65 72 2(F,D,G,0)] wher
1dcf0 65 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 e the G paramete
1dd00 72 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 r is.**
1dd10 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 [SQLITE_OPEN_RE
1dd20 41 44 57 52 49 54 45 5d 7c 5b 53 51 4c 49 54 45 ADWRITE]|[SQLITE
1dd30 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 0a 2a _OPEN_CREATE]..*
1dd40 2a 0a 2a 2a 20 7b 48 31 32 37 31 31 7d 20 49 66 *.** {H12711} If
1dd50 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 the G parameter
1dd60 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 to [sqlite3_ope
1dd70 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 n_v2(F,D,G,V)] c
1dd80 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 ontains the.**
1dd90 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 bit valu
1dda0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 e [SQLITE_OPEN_R
1ddb0 45 41 44 4f 4e 4c 59 5d 20 74 68 65 6e 20 74 68 EADONLY] then th
1ddc0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 e database is op
1ddd0 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 ened.**
1dde0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c for reading onl
1ddf0 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 32 y..**.** {H12712
1de00 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d } If the G param
1de10 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 eter to [sqlite3
1de20 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 _open_v2(F,D,G,V
1de30 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a )] contains the.
1de40 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20 ** bit
1de50 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 value [SQLITE_OP
1de60 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 74 68 EN_READWRITE] th
1de70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
1de80 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20 is opened.**
1de90 20 20 20 20 20 20 72 65 61 64 69 6e 67 20 61 6e reading an
1dea0 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 d writing if pos
1deb0 73 69 62 6c 65 2c 20 6f 72 20 66 6f 72 20 72 65 sible, or for re
1dec0 61 64 69 6e 67 20 6f 6e 6c 79 20 69 66 20 74 68 ading only if th
1ded0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 e.** fi
1dee0 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 le is write prot
1def0 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 ected by the ope
1df00 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 0a 2a rating system..*
1df10 2a 0a 2a 2a 20 7b 48 31 32 37 31 33 7d 20 49 66 *.** {H12713} If
1df20 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 the G parameter
1df30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 to [sqlite3_ope
1df40 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 6f n_v2(F,D,G,V)] o
1df50 6d 69 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 mits the.**
1df60 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b bit value [
1df70 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 SQLITE_OPEN_CREA
1df80 54 45 5d 20 61 6e 64 20 74 68 65 20 64 61 74 61 TE] and the data
1df90 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a base does not.**
1dfa0 20 20 20 20 20 20 20 20 20 20 70 72 65 76 69 6f previo
1dfb0 75 73 6c 79 20 65 78 69 73 74 2c 20 61 6e 20 65 usly exist, an e
1dfc0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 rror is returned
1dfd0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 34 7d ..**.** {H12714}
1dfe0 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 If the G parame
1dff0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
1e000 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 open_v2(F,D,G,V)
1e010 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a ] contains the.*
1e020 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20 76 * bit v
1e030 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 alue [SQLITE_OPE
1e040 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64 20 74 68 N_CREATE] and th
1e050 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 e database does
1e060 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 not.**
1e070 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73 74 previously exist
1e080 2c 20 74 68 65 6e 20 61 6e 20 61 74 74 65 6d 70 , then an attemp
1e090 74 20 69 73 20 6d 61 64 65 20 74 6f 20 63 72 65 t is made to cre
1e0a0 61 74 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 ate and.**
1e0b0 20 20 20 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 initialize t
1e0c0 68 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 0a he database..**.
1e0d0 2a 2a 20 7b 48 31 32 37 31 37 7d 20 49 66 20 74 ** {H12717} If t
1e0e0 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 he filename argu
1e0f0 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 ment to [sqlite3
1e100 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 _open()], [sqlit
1e110 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a e3_open16()],.**
1e120 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 or [sq
1e130 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d lite3_open_v2()]
1e140 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 is ":memory:",
1e150 74 68 65 6e 20 61 6e 20 70 72 69 76 61 74 65 2c then an private,
1e160 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 70 68 .** eph
1e170 65 6d 65 72 61 6c 2c 20 69 6e 2d 6d 65 6d 6f 72 emeral, in-memor
1e180 79 20 64 61 74 61 62 61 73 65 20 69 73 20 63 72 y database is cr
1e190 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f eated for the co
1e1a0 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 20 20 20 20 nnection..**
1e1b0 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53 <todo>Is S
1e1c0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
1e1d0 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 E|SQLITE_OPEN_RE
1e1e0 41 44 57 52 49 54 45 20 72 65 71 75 69 72 65 64 ADWRITE required
1e1f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 .** in
1e200 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
1e210 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 )?</todo>.**.**
1e220 7b 48 31 32 37 31 39 7d 20 49 66 20 74 68 65 20 {H12719} If the
1e230 66 69 6c 65 6e 61 6d 65 20 69 73 20 4e 55 4c 4c filename is NULL
1e240 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 or an empty str
1e250 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 ing, then a priv
1e260 61 74 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 ate,.**
1e270 20 65 70 68 65 6d 65 72 61 6c 20 6f 6e 2d 64 69 ephemeral on-di
1e280 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c sk database will
1e290 20 62 65 20 63 72 65 61 74 65 64 2e 0a 2a 2a 20 be created..**
1e2a0 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49 <todo>I
1e2b0 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 s SQLITE_OPEN_CR
1e2c0 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e EATE|SQLITE_OPEN
1e2d0 5f 52 45 41 44 57 52 49 54 45 20 72 65 71 75 69 _READWRITE requi
1e2e0 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 red.**
1e2f0 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f in sqlite3_open_
1e300 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a v2()?</todo>.**.
1e310 2a 2a 20 7b 48 31 32 37 32 31 7d 20 54 68 65 20 ** {H12721} The
1e320 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
1e330 74 69 6f 6e 5d 20 63 72 65 61 74 65 64 20 62 79 tion] created by
1e340 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
1e350 32 28 46 2c 44 2c 47 2c 56 29 5d 0a 2a 2a 20 20 2(F,D,G,V)].**
1e360 20 20 20 20 20 20 20 20 77 69 6c 6c 20 75 73 65 will use
1e370 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 the [sqlite3_vf
1e380 73 5d 20 6f 62 6a 65 63 74 20 69 64 65 6e 74 69 s] object identi
1e390 66 69 65 64 20 62 79 20 74 68 65 20 56 20 70 61 fied by the V pa
1e3a0 72 61 6d 65 74 65 72 2c 0a 2a 2a 20 20 20 20 20 rameter,.**
1e3b0 20 20 20 20 20 6f 72 20 74 68 65 20 64 65 66 61 or the defa
1e3c0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 ult [sqlite3_vfs
1e3d0 5d 20 6f 62 6a 65 63 74 20 69 66 20 56 20 69 73 ] object if V is
1e3e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
1e3f0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 32 33 7d 20 .**.** {H12723}
1e400 54 77 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f Two [database co
1e410 6e 6e 65 63 74 69 6f 6e 73 5d 20 77 69 6c 6c 20 nnections] will
1e420 73 68 61 72 65 20 61 20 63 6f 6d 6d 6f 6e 20 63 share a common c
1e430 61 63 68 65 20 69 66 20 62 6f 74 68 20 77 65 72 ache if both wer
1e440 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 70 e.** op
1e450 65 6e 65 64 20 77 69 74 68 20 74 68 65 20 73 61 ened with the sa
1e460 6d 65 20 56 46 53 20 77 68 69 6c 65 20 5b 73 68 me VFS while [sh
1e470 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d ared cache mode]
1e480 20 77 61 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 was enabled and
1e490 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 .** if
1e4a0 62 6f 74 68 20 66 69 6c 65 6e 61 6d 65 73 20 63 both filenames c
1e4b0 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 75 73 69 ompare equal usi
1e4c0 6e 67 20 6d 65 6d 63 6d 70 28 29 20 61 66 74 65 ng memcmp() afte
1e4d0 72 20 68 61 76 69 6e 67 20 62 65 65 6e 0a 2a 2a r having been.**
1e4e0 20 20 20 20 20 20 20 20 20 20 70 72 6f 63 65 73 proces
1e4f0 73 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 sed by the [sqli
1e500 74 65 33 5f 76 66 73 20 7c 20 78 46 75 6c 6c 50 te3_vfs | xFullP
1e510 61 74 68 6e 61 6d 65 5d 20 6d 65 74 68 6f 64 20 athname] method
1e520 6f 66 20 74 68 65 20 56 46 53 2e 0a 2a 2f 0a 69 of the VFS..*/.i
1e530 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 nt sqlite3_open(
1e540 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 . const char *f
1e550 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 ilename, /* Da
1e560 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 tabase filename
1e570 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c (UTF-8) */. sql
1e580 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 ite3 **ppDb
1e590 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c /* OUT: SQL
1e5a0 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f ite db handle */
1e5b0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .);.int sqlite3_
1e5c0 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 open16(. const
1e5d0 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 void *filename,
1e5e0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 /* Database fi
1e5f0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 lename (UTF-16)
1e600 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 */. sqlite3 **p
1e610 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 pDb /*
1e620 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 OUT: SQLite db h
1e630 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 andle */.);.int
1e640 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
1e650 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 . const char *f
1e660 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 ilename, /* Da
1e670 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 tabase filename
1e680 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c (UTF-8) */. sql
1e690 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 ite3 **ppDb,
1e6a0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c /* OUT: SQL
1e6b0 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f ite db handle */
1e6c0 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 . int flags,
1e6d0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c /* Fl
1e6e0 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 ags */. const c
1e6f0 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 har *zVfs
1e700 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 /* Name of VFS
1e710 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f module to use */
1e720 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
1e730 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 REF: Error Codes
1e740 20 41 6e 64 20 4d 65 73 73 61 67 65 73 20 7b 48 And Messages {H
1e750 31 32 38 30 30 7d 20 3c 53 36 30 32 30 30 3e 0a 12800} <S60200>.
1e760 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
1e770 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 3_errcode() inte
1e780 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 rface returns th
1e790 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c e numeric [resul
1e7a0 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 t code] or.** [e
1e7b0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
1e7c0 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 ode] for the mos
1e7d0 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 t recent failed
1e7e0 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 sqlite3_* API ca
1e7f0 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 ll.** associated
1e800 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 with a [databas
1e810 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 e connection]. I
1e820 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 f a prior API ca
1e830 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 ll failed.** but
1e840 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
1e850 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 API call succee
1e860 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 ded, the return
1e870 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 value from.** sq
1e880 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 lite3_errcode()
1e890 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 54 is undefined. T
1e8a0 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e he sqlite3_exten
1e8b0 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a ded_errcode().**
1e8c0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 interface is th
1e8d0 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 e same except th
1e8e0 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 at it always ret
1e8f0 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 urns the .** [ex
1e900 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
1e910 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 de] even when ex
1e920 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
1e930 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 des are.** disab
1e940 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 led..**.** The s
1e950 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 qlite3_errmsg()
1e960 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d and sqlite3_errm
1e970 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e sg16() return En
1e980 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a glish-language.*
1e990 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 * text that desc
1e9a0 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c ribes the error,
1e9b0 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 as either UTF-8
1e9c0 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 or UTF-16 respe
1e9d0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f ctively..** Memo
1e9e0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 ry to hold the e
1e9f0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 rror message str
1ea00 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 ing is managed i
1ea10 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 nternally..** Th
1ea20 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f e application do
1ea30 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 es not need to w
1ea40 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 orry about freei
1ea50 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a ng the result..*
1ea60 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 * However, the e
1ea70 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 rror string migh
1ea80 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e t be overwritten
1ea90 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 or deallocated
1eaa0 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 by.** subsequent
1eab0 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 calls to other
1eac0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
1ead0 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a functions..**.*
1eae0 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 * When the seria
1eaf0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 lized [threading
1eb00 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 mode] is in use
1eb10 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 , it might be th
1eb20 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 e.** case that a
1eb30 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 second error oc
1eb40 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 curs on a separa
1eb50 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 te thread in bet
1eb60 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 ween.** the time
1eb70 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 of the first er
1eb80 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c ror and the call
1eb90 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 to these interf
1eba0 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 aces..** When th
1ebb0 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 at happens, the
1ebc0 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c second error wil
1ebd0 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 l be reported si
1ebe0 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 nce these.** int
1ebf0 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 erfaces always r
1ec00 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 eport the most r
1ec10 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 ecent result. T
1ec20 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c o avoid.** this,
1ec30 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e each thread can
1ec40 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 obtain exclusiv
1ec50 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 e use of the [da
1ec60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1ec70 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b n] D.** by invok
1ec80 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 ing [sqlite3_mut
1ec90 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 ex_enter]([sqlit
1eca0 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 e3_db_mutex](D))
1ecb0 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e before beginnin
1ecc0 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e g.** to use D an
1ecd0 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 d invoking [sqli
1ece0 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d te3_mutex_leave]
1ecf0 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 ([sqlite3_db_mut
1ed00 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a ex](D)) after.**
1ed10 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 all calls to th
1ed20 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 e interfaces lis
1ed30 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d ted here are com
1ed40 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 pleted..**.** If
1ed50 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 an interface fa
1ed60 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f ils with SQLITE_
1ed70 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 MISUSE, that mea
1ed80 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 ns the interface
1ed90 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 .** was invoked
1eda0 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 incorrectly by t
1edb0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 he application.
1edc0 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 In that case, t
1edd0 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 he.** error code
1ede0 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 and message may
1edf0 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 or may not be s
1ee00 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 et..**.** INVARI
1ee10 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 ANTS:.**.** {H12
1ee20 38 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 801} The [sqlite
1ee30 33 5f 65 72 72 63 6f 64 65 28 44 29 5d 20 69 6e 3_errcode(D)] in
1ee40 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
1ee50 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 20 the numeric.**
1ee60 20 20 20 20 20 20 20 20 5b 72 65 73 75 6c 74 20 [result
1ee70 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 code] or [extend
1ee80 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 ed result code]
1ee90 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 for the most rec
1eea0 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 ently.**
1eeb0 20 20 66 61 69 6c 65 64 20 69 6e 74 65 72 66 61 failed interfa
1eec0 63 65 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 ce call associat
1eed0 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 ed with the [dat
1eee0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1eef0 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 ] D..**.** {H128
1ef00 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 02} The [sqlite3
1ef10 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 _extended_errcod
1ef20 65 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 e(D)] interface
1ef30 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 returns the nume
1ef40 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ric.**
1ef50 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
1ef60 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d code] for the m
1ef70 6f 73 74 20 72 65 63 65 6e 74 6c 79 0a 2a 2a 20 ost recently.**
1ef80 20 20 20 20 20 20 20 20 20 66 61 69 6c 65 64 20 failed
1ef90 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 61 interface call a
1efa0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
1efb0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
1efc0 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a nection] D..**.*
1efd0 2a 20 7b 48 31 32 38 30 33 7d 20 54 68 65 20 5b * {H12803} The [
1efe0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 44 sqlite3_errmsg(D
1eff0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
1f000 65 72 72 6d 73 67 31 36 28 44 29 5d 0a 2a 2a 20 errmsg16(D)].**
1f010 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 interfa
1f020 63 65 73 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 ces return Engli
1f030 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 sh-language text
1f040 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 0a that describes.
1f050 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
1f060 65 72 72 6f 72 20 69 6e 20 74 68 65 20 6d 6f 73 error in the mos
1f070 74 6c 79 20 72 65 63 65 6e 74 6c 79 20 66 61 69 tly recently fai
1f080 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20 63 61 led interface ca
1f090 6c 6c 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ll,.**
1f0a0 65 6e 63 6f 64 65 64 20 61 73 20 65 69 74 68 65 encoded as eithe
1f0b0 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 r UTF-8 or UTF-1
1f0c0 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 6 respectively..
1f0d0 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 37 7d 20 54 **.** {H12807} T
1f0e0 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 he strings retur
1f0f0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ned by [sqlite3_
1f100 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20 5b 73 errmsg()] and [s
1f110 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 qlite3_errmsg16(
1f120 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 )].** a
1f130 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 re valid until t
1f140 68 65 20 6e 65 78 74 20 53 51 4c 69 74 65 20 69 he next SQLite i
1f150 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 2e 0a 2a nterface call..*
1f160 2a 0a 2a 2a 20 7b 48 31 32 38 30 38 7d 20 43 61 *.** {H12808} Ca
1f170 6c 6c 73 20 74 6f 20 41 50 49 20 72 6f 75 74 69 lls to API routi
1f180 6e 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 nes that do not
1f190 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 20 return an error
1f1a0 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 code.**
1f1b0 20 28 65 78 61 6d 70 6c 65 3a 20 5b 73 71 6c 69 (example: [sqli
1f1c0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 te3_data_count()
1f1d0 5d 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20 20 20 20 ]) do not.**
1f1e0 20 20 20 20 20 20 63 68 61 6e 67 65 20 74 68 65 change the
1f1f0 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 72 20 6d error code or m
1f200 65 73 73 61 67 65 20 72 65 74 75 72 6e 65 64 20 essage returned
1f210 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b by.** [
1f220 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
1f230 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 )], [sqlite3_ext
1f240 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d ended_errcode()]
1f250 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 ,.** [s
1f260 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d qlite3_errmsg()]
1f270 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 , or [sqlite3_er
1f280 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a rmsg16()]..**.**
1f290 20 7b 48 31 32 38 30 39 7d 20 49 6e 74 65 72 66 {H12809} Interf
1f2a0 61 63 65 73 20 74 68 61 74 20 61 72 65 20 6e 6f aces that are no
1f2b0 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 t associated wit
1f2c0 68 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 h a specific.**
1f2d0 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 [databa
1f2e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 se connection] (
1f2f0 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20 20 20 20 examples:.**
1f300 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d [sqlite3_m
1f310 70 72 69 6e 74 66 28 29 5d 20 6f 72 20 5b 73 71 printf()] or [sq
1f320 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 lite3_enable_sha
1f330 72 65 64 5f 63 61 63 68 65 28 29 5d 0a 2a 2a 20 red_cache()].**
1f340 20 20 20 20 20 20 20 20 20 64 6f 20 6e 6f 74 20 do not
1f350 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 change the value
1f360 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a s returned by.**
1f370 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
1f380 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b e3_errcode()], [
1f390 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
1f3a0 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 _errcode()],.**
1f3b0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
1f3c0 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20 3_errmsg()], or
1f3d0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 [sqlite3_errmsg1
1f3e0 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 6()]..*/.int sql
1f3f0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c ite3_errcode(sql
1f400 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 ite3 *db);.int s
1f410 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f qlite3_extended_
1f420 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 errcode(sqlite3
1f430 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 *db);.const char
1f440 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 *sqlite3_errmsg
1f450 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 (sqlite3*);.cons
1f460 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
1f470 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 errmsg16(sqlite3
1f480 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
1f490 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 REF: SQL Stateme
1f4a0 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 30 30 nt Object {H1300
1f4b0 30 7d 20 3c 48 31 33 30 31 30 3e 0a 2a 2a 20 4b 0} <H13010>.** K
1f4c0 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 EYWORDS: {prepar
1f4d0 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 ed statement} {p
1f4e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
1f4f0 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 ts}.**.** An ins
1f500 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 tance of this ob
1f510 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 ject represents
1f520 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 a single SQL sta
1f530 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 tement..** This
1f540 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 object is variou
1f550 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 sly known as a "
1f560 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1f570 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d nt" or a.** "com
1f580 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d piled SQL statem
1f590 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 ent" or simply a
1f5a0 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e s a "statement".
1f5b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 .**.** The life
1f5c0 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f of a statement o
1f5d0 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 bject goes somet
1f5e0 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a hing like this:.
1f5f0 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c **.** <ol>.** <l
1f600 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 i> Create the ob
1f610 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 ject using [sqli
1f620 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
1f630 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a ] or a related.*
1f640 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e * function.
1f650 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 .** <li> Bind va
1f660 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 lues to [host pa
1f670 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 rameters] using
1f680 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 the sqlite3_bind
1f690 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 _*().** int
1f6a0 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e erfaces..** <li>
1f6b0 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 Run the SQL by
1f6c0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 calling [sqlite3
1f6d0 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 _step()] one or
1f6e0 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c more times..** <
1f6f0 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 li> Reset the st
1f700 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 atement using [s
1f710 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
1f720 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 then go back.**
1f730 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 to step 2.
1f740 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 Do this zero or
1f750 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 more times..**
1f760 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 <li> Destroy the
1f770 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 object using [s
1f780 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
1f790 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a )]..** </ol>.**.
1f7a0 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 ** Refer to docu
1f7b0 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 mentation on ind
1f7c0 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 ividual methods
1f7d0 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 above for additi
1f7e0 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 onal.** informat
1f7f0 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ion..*/.typedef
1f800 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 struct sqlite3_s
1f810 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 tmt sqlite3_stmt
1f820 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1f830 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 F: Run-time Limi
1f840 74 73 20 7b 48 31 32 37 36 30 7d 20 3c 53 32 30 ts {H12760} <S20
1f850 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 600>.**.** This
1f860 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 interface allows
1f870 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 the size of var
1f880 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 ious constructs
1f890 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a to be limited.**
1f8a0 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e on a connection
1f8b0 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 by connection b
1f8c0 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 asis. The first
1f8d0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
1f8e0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 e.** [database c
1f8f0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 onnection] whose
1f900 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 limit is to be
1f910 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 set or queried.
1f920 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 The.** second p
1f930 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 arameter is one
1f940 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 of the [limit ca
1f950 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 tegories] that d
1f960 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 efine a.** class
1f970 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 of constructs t
1f980 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 o be size limite
1f990 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 d. The third pa
1f9a0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a rameter is the.*
1f9b0 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 * new limit for
1f9c0 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 20 that construct.
1f9d0 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 The function re
1f9e0 74 75 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c 69 turns the old li
1f9f0 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 mit..**.** If th
1fa00 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 e new limit is a
1fa10 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 negative number
1fa20 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 , the limit is u
1fa30 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 46 6f 72 nchanged..** For
1fa40 20 74 68 65 20 6c 69 6d 69 74 20 63 61 74 65 67 the limit categ
1fa50 6f 72 79 20 6f 66 20 53 51 4c 49 54 45 5f 4c 49 ory of SQLITE_LI
1fa60 4d 49 54 5f 58 59 5a 20 74 68 65 72 65 20 69 73 MIT_XYZ there is
1fa70 20 61 20 68 61 72 64 20 75 70 70 65 72 0a 2a 2a a hard upper.**
1fa80 20 62 6f 75 6e 64 20 73 65 74 20 62 79 20 61 20 bound set by a
1fa90 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43 20 70 compile-time C p
1faa0 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 reprocessor macr
1fab0 6f 20 6e 61 6d 65 64 20 53 51 4c 49 54 45 5f 4d o named SQLITE_M
1fac0 41 58 5f 58 59 5a 2e 0a 2a 2a 20 28 54 68 65 20 AX_XYZ..** (The
1fad0 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 "_LIMIT_" in the
1fae0 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 name is changed
1faf0 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a 2a to "_MAX_".).**
1fb00 20 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 Attempts to inc
1fb10 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 rease a limit ab
1fb20 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70 ove its hard upp
1fb30 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 er bound are.**
1fb40 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 silently truncat
1fb50 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 ed to the hard u
1fb60 70 70 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a pper limit..**.*
1fb70 2a 20 52 75 6e 20 74 69 6d 65 20 6c 69 6d 69 74 * Run time limit
1fb80 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 s are intended f
1fb90 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 or use in applic
1fba0 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 ations that mana
1fbb0 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 ge.** both their
1fbc0 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 own internal da
1fbd0 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 tabase and also
1fbe0 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 databases that a
1fbf0 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a re controlled.**
1fc00 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 by untrusted ex
1fc10 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 ternal sources.
1fc20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c An example appl
1fc30 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 ication might be
1fc40 20 61 0a 2a 2a 20 77 65 62 62 72 6f 77 73 65 72 a.** webbrowser
1fc50 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 that has its ow
1fc60 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 n databases for
1fc70 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 storing history
1fc80 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 and.** separate
1fc90 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f databases contro
1fca0 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 lled by JavaScri
1fcb0 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 pt applications
1fcc0 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 downloaded.** of
1fcd0 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 f the Internet.
1fce0 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 The internal da
1fcf0 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 tabases can be g
1fd00 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 iven the.** larg
1fd10 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 e, default limit
1fd20 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 s. Databases ma
1fd30 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 naged by externa
1fd40 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a l sources can.**
1fd50 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 be given much s
1fd60 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 maller limits de
1fd70 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e signed to preven
1fd80 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 t a denial of se
1fd90 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e rvice.** attack.
1fda0 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 Developers mig
1fdb0 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 ht also want to
1fdc0 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 use the [sqlite3
1fdd0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 _set_authorizer(
1fde0 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 )].** interface
1fdf0 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 to further contr
1fe00 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c ol untrusted SQL
1fe10 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 . The size of t
1fe20 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 he database.** c
1fe30 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 reated by an unt
1fe40 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61 rusted script ca
1fe50 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 n be contained u
1fe60 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 sing the.** [max
1fe70 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 _page_count] [PR
1fe80 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 AGMA]..**.** New
1fe90 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 run-time limit
1fea0 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 categories may b
1feb0 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
1fec0 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a e releases..**.*
1fed0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
1fee0 0a 2a 2a 20 7b 48 31 32 37 36 32 7d 20 41 20 73 .** {H12762} A s
1fef0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 uccessful call t
1ff00 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 o [sqlite3_limit
1ff10 28 44 2c 43 2c 56 29 5d 20 77 68 65 72 65 20 56 (D,C,V)] where V
1ff20 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 is.**
1ff30 70 6f 73 69 74 69 76 65 20 63 68 61 6e 67 65 73 positive changes
1ff40 20 74 68 65 20 6c 69 6d 69 74 20 6f 6e 20 74 68 the limit on th
1ff50 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72 e size of constr
1ff60 75 63 74 20 43 20 69 6e 20 74 68 65 0a 2a 2a 20 uct C in the.**
1ff70 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 [databa
1ff80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
1ff90 20 74 6f 20 74 68 65 20 6c 65 73 73 65 72 20 6f to the lesser o
1ffa0 66 20 56 20 61 6e 64 20 74 68 65 20 68 61 72 64 f V and the hard
1ffb0 20 75 70 70 65 72 0a 2a 2a 20 20 20 20 20 20 20 upper.**
1ffc0 20 20 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 bound on the
1ffd0 73 69 7a 65 20 6f 66 20 43 20 74 68 61 74 20 69 size of C that i
1ffe0 73 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 s set at compile
1fff0 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 -time..**.** {H1
20000 32 37 36 36 7d 20 41 20 73 75 63 63 65 73 73 66 2766} A successf
20010 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 ul call to [sqli
20020 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 te3_limit(D,C,V)
20030 5d 20 77 68 65 72 65 20 56 20 69 73 20 6e 65 67 ] where V is neg
20040 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 ative.**
20050 20 20 6c 65 61 76 65 73 20 74 68 65 20 73 74 61 leaves the sta
20060 74 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 te of the [datab
20070 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
20080 44 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a D unchanged..**.
20090 2a 2a 20 7b 48 31 32 37 36 39 7d 20 41 20 73 75 ** {H12769} A su
200a0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f ccessful call to
200b0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 [sqlite3_limit(
200c0 44 2c 43 2c 56 29 5d 20 72 65 74 75 72 6e 73 20 D,C,V)] returns
200d0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
200e0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d value of the lim
200f0 69 74 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f it on the size o
20100 66 20 63 6f 6e 73 74 72 75 63 74 20 43 20 69 6e f construct C in
20110 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
20120 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
20130 63 74 69 6f 6e 5d 20 44 20 61 73 20 69 74 20 77 ction] D as it w
20140 61 73 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 as prior to the
20150 63 61 6c 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c call..*/.int sql
20160 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 ite3_limit(sqlit
20170 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 e3*, int id, int
20180 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a newVal);../*.**
20190 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 CAPI3REF: Run-T
201a0 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f ime Limit Catego
201b0 72 69 65 73 20 7b 48 31 32 37 39 30 7d 20 3c 48 ries {H12790} <H
201c0 31 32 37 36 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 12760>.** KEYWOR
201d0 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 DS: {limit categ
201e0 6f 72 79 7d 20 7b 6c 69 6d 69 74 20 63 61 74 65 ory} {limit cate
201f0 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 gories}.**.** Th
20200 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 ese constants de
20210 66 69 6e 65 20 76 61 72 69 6f 75 73 20 61 73 70 fine various asp
20220 65 63 74 73 20 6f 66 20 61 20 5b 64 61 74 61 62 ects of a [datab
20230 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a ase connection].
20240 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c ** that can be l
20250 69 6d 69 74 65 64 20 69 6e 20 73 69 7a 65 20 62 imited in size b
20260 79 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 y calls to [sqli
20270 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a te3_limit()]..**
20280 20 54 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 The meanings of
20290 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d the various lim
202a0 69 74 73 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f its are as follo
202b0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a ws:.**.** <dl>.*
202c0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d * <dt>SQLITE_LIM
202d0 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a IT_LENGTH</dt>.*
202e0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
202f0 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 m size of any st
20300 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 ring or BLOB or
20310 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a table row.<dd>.*
20320 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
20330 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 LIMIT_SQL_LENGTH
20340 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
20350 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 maximum length
20360 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d of an SQL statem
20370 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ent.</dd>.**.**
20380 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
20390 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 _COLUMN</dt>.**
203a0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
203b0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e number of column
203c0 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 s in a table def
203d0 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 inition or in th
203e0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 e.** result set
203f0 6f 66 20 61 20 53 45 4c 45 43 54 20 6f 72 20 74 of a SELECT or t
20400 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
20410 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 r of columns in
20420 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 an index.** or i
20430 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 n an ORDER BY or
20440 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 GROUP BY clause
20450 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
20460 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 >SQLITE_LIMIT_EX
20470 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a PR_DEPTH</dt>.**
20480 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
20490 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 depth of the pa
204a0 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 rse tree on any
204b0 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e expression.</dd>
204c0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
204d0 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 E_LIMIT_COMPOUND
204e0 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 _SELECT</dt>.**
204f0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
20500 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 number of terms
20510 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 in a compound SE
20520 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c LECT statement.<
20530 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
20540 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 QLITE_LIMIT_VDBE
20550 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e _OP</dt>.** <dd>
20560 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
20570 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f er of instructio
20580 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 ns in a virtual
20590 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a machine program.
205a0 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 ** used to imple
205b0 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 ment an SQL stat
205c0 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a ement.</dd>.**.*
205d0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d * <dt>SQLITE_LIM
205e0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c IT_FUNCTION_ARG<
205f0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
20600 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
20610 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 f arguments on a
20620 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a function.</dd>.
20630 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
20640 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c _LIMIT_ATTACHED<
20650 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
20660 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
20670 66 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 f attached datab
20680 61 73 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ases.</dd>.**.**
20690 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 <dt>SQLITE_LIMI
206a0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c T_LIKE_PATTERN_L
206b0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ENGTH</dt>.** <d
206c0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 d>The maximum le
206d0 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 ngth of the patt
206e0 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ern argument to
206f0 74 68 65 20 4c 49 4b 45 20 6f 72 0a 2a 2a 20 47 the LIKE or.** G
20700 4c 4f 42 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f LOB operators.</
20710 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
20720 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 LITE_LIMIT_VARIA
20730 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a BLE_NUMBER</dt>.
20740 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
20750 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 72 um number of var
20760 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c iables in an SQL
20770 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 statement that
20780 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e can.** be bound.
20790 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a </dd>.** </dl>.*
207a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
207b0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 _LIMIT_LENGTH
207c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
207d0 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 0.#define SQLIT
207e0 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 E_LIMIT_SQL_LENG
207f0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TH
20800 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 1.#define SQLI
20810 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 TE_LIMIT_COLUMN
20820 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
20830 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 2.#define SQL
20840 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 ITE_LIMIT_EXPR_D
20850 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 EPTH
20860 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 3.#define SQ
20870 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f LITE_LIMIT_COMPO
20880 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 UND_SELECT
20890 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 4.#define S
208a0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 QLITE_LIMIT_VDBE
208b0 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 _OP
208c0 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 5.#define
208d0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e SQLITE_LIMIT_FUN
208e0 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 CTION_ARG
208f0 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 6.#define
20900 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 SQLITE_LIMIT_AT
20910 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 TACHED
20920 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 7.#defin
20930 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c e SQLITE_LIMIT_L
20940 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 IKE_PATTERN_LENG
20950 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 TH 8.#defi
20960 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
20970 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 VARIABLE_NUMBER
20980 20 20 20 20 20 20 20 20 20 20 39 0a 0a 2f 2a 0a 9../*.
20990 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d ** CAPI3REF: Com
209a0 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 piling An SQL St
209b0 61 74 65 6d 65 6e 74 20 7b 48 31 33 30 31 30 7d atement {H13010}
209c0 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 20 4b 45 59 <S10000>.** KEY
209d0 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 WORDS: {SQL stat
209e0 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a ement compiler}.
209f0 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 **.** To execute
20a00 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 an SQL query, i
20a10 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 t must first be
20a20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 compiled into a
20a30 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f byte-code.** pro
20a40 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f gram using one o
20a50 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
20a60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 ..**.** The firs
20a70 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 t argument, "db"
20a80 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 , is a [database
20a90 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 connection] obt
20aa0 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 ained from a.**
20ab0 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 5b 73 prior call to [s
20ac0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 qlite3_open()],
20ad0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
20ae0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
20af0 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a open16()]..**.**
20b00 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 The second argu
20b10 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 ment, "zSql", is
20b20 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 the statement t
20b30 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 o be compiled, e
20b40 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 ncoded.** as eit
20b50 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 her UTF-8 or UTF
20b60 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 -16. The sqlite
20b70 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 3_prepare() and
20b80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
20b90 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 v2().** interfac
20ba0 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e es use UTF-8, an
20bb0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 d sqlite3_prepar
20bc0 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 e16() and sqlite
20bd0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
20be0 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a .** use UTF-16..
20bf0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42 79 **.** If the nBy
20c00 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c te argument is l
20c10 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 ess than zero, t
20c20 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 hen zSql is read
20c30 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 up to the.** fi
20c40 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 rst zero termina
20c50 74 6f 72 2e 20 49 66 20 6e 42 79 74 65 20 69 73 tor. If nByte is
20c60 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 non-negative, t
20c70 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 hen it is the ma
20c80 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 ximum.** number
20c90 6f 66 20 20 62 79 74 65 73 20 72 65 61 64 20 66 of bytes read f
20ca0 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20 rom zSql. When
20cb0 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 nByte is non-neg
20cc0 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 ative, the.** zS
20cd0 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 ql string ends a
20ce0 74 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72 t either the fir
20cf0 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 st '\000' or '\u
20d00 30 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20 0000' character
20d10 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d or.** the nByte-
20d20 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 th byte, whichev
20d30 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 er comes first.
20d40 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e If the caller kn
20d50 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 ows.** that the
20d60 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 supplied string
20d70 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 is nul-terminate
20d80 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 d, then there is
20d90 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 a small.** perf
20da0 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 ormance advantag
20db0 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 e to be gained b
20dc0 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 y passing an nBy
20dd0 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 te parameter tha
20de0 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f t.** is equal to
20df0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
20e00 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 ytes in the inpu
20e10 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c t string <i>incl
20e20 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 uding</i>.** the
20e30 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 nul-terminator
20e40 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 2a 70 7a bytes..**.** *pz
20e50 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 Tail is made to
20e60 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 point to the fir
20e70 73 74 20 62 79 74 65 20 70 61 73 74 20 74 68 65 st byte past the
20e80 20 65 6e 64 20 6f 66 20 74 68 65 0a 2a 2a 20 66 end of the.** f
20e90 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 irst SQL stateme
20ea0 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 nt in zSql. The
20eb0 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 se routines only
20ec0 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 compile the fir
20ed0 73 74 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 st.** statement
20ee0 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 in zSql, so *pzT
20ef0 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e ail is left poin
20f00 74 69 6e 67 20 74 6f 20 77 68 61 74 20 72 65 6d ting to what rem
20f10 61 69 6e 73 0a 2a 2a 20 75 6e 63 6f 6d 70 69 6c ains.** uncompil
20f20 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d ed..**.** *ppStm
20f30 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 t is left pointi
20f40 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 ng to a compiled
20f50 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
20f60 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 ment] that can b
20f70 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 e.** executed us
20f80 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 ing [sqlite3_ste
20f90 70 28 29 5d 2e 20 20 49 66 20 74 68 65 72 65 20 p()]. If there
20fa0 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 is an error, *pp
20fb0 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 Stmt is set.** t
20fc0 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 o NULL. If the
20fd0 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 input text conta
20fe0 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 ins no SQL (if t
20ff0 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 he input is an e
21000 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f mpty.** string o
21010 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 r a comment) the
21020 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 n *ppStmt is set
21030 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b 41 31 to NULL..** {A1
21040 33 30 31 38 7d 20 54 68 65 20 63 61 6c 6c 69 6e 3018} The callin
21050 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 g procedure is r
21060 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 esponsible for d
21070 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 eleting the comp
21080 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 iled.** SQL stat
21090 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c ement using [sql
210a0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
210b0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 after it has fi
210c0 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a nished with it..
210d0 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 **.** On success
210e0 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 , [SQLITE_OK] is
210f0 20 72 65 74 75 72 6e 65 64 2c 20 6f 74 68 65 72 returned, other
21100 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 wise an [error c
21110 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 ode] is returned
21120 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
21130 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
21140 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 and sqlite3_pre
21150 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 pare16_v2() inte
21160 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 rfaces are.** re
21170 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c commended for al
21180 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 l new programs.
21190 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e The two older in
211a0 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 terfaces are ret
211b0 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 ained.** for bac
211c0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 kwards compatibi
211d0 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 lity, but their
211e0 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 use is discourag
211f0 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76 ed..** In the "v
21200 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 2" interfaces, t
21210 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 he prepared stat
21220 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 ement.** that is
21230 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b returned (the [
21240 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 sqlite3_stmt] ob
21250 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 ject) contains a
21260 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 copy of the.**
21270 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 original SQL tex
21280 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 t. This causes t
21290 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 he [sqlite3_step
212a0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f ()] interface to
212b0 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 64 69 66 .** behave a dif
212c0 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20 ferently in two
212d0 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e ways:.**.** <ol>
212e0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 .** <li>.** If t
212f0 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 he database sche
21300 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 ma changes, inst
21310 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 ead of returning
21320 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d [SQLITE_SCHEMA]
21330 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 as it.** always
21340 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 used to do, [sq
21350 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 lite3_step()] wi
21360 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ll automatically
21370 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 recompile the S
21380 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 QL.** statement
21390 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 and try to run i
213a0 74 20 61 67 61 69 6e 2e 20 20 49 66 20 74 68 65 t again. If the
213b0 20 73 63 68 65 6d 61 20 68 61 73 20 63 68 61 6e schema has chan
213c0 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20 ged in.** a way
213d0 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 20 73 that makes the s
213e0 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 tatement no long
213f0 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 er valid, [sqlit
21400 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 e3_step()] will
21410 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 still.** return
21420 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e [SQLITE_SCHEMA].
21430 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 But unlike the
21440 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 legacy behavior
21450 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 , [SQLITE_SCHEMA
21460 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 ] is.** now a fa
21470 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c tal error. Call
21480 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 ing [sqlite3_pre
21490 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e pare_v2()] again
214a0 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 will not make t
214b0 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 he.** error go a
214c0 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 way. Note: use
214d0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 [sqlite3_errmsg(
214e0 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 )] to find the t
214f0 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 ext.** of the pa
21500 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74 rsing error that
21510 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b results in an [
21520 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 SQLITE_SCHEMA] r
21530 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a eturn..** </li>.
21540 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 **.** <li>.** Wh
21550 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 en an error occu
21560 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 rs, [sqlite3_ste
21570 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e p()] will return
21580 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 one of the deta
21590 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 iled.** [error c
215a0 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 odes] or [extend
215b0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e ed error codes].
215c0 20 20 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 The legacy beh
215d0 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a avior was that.*
215e0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 * [sqlite3_step(
215f0 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 )] would only re
21600 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b turn a generic [
21610 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 SQLITE_ERROR] re
21620 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 sult code.** and
21630 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20 you would have
21640 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 to make a second
21650 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
21660 33 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 6f 72 3_reset()] in or
21670 64 65 72 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 der.** to find t
21680 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 he underlying ca
21690 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c use of the probl
216a0 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 em. With the "v2
216b0 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 " prepare.** int
216c0 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 erfaces, the und
216d0 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 erlying reason f
216e0 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 or the error is
216f0 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 returned immedia
21700 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a tely..** </li>.*
21710 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e * </ol>.**.** IN
21720 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
21730 7b 48 31 33 30 31 31 7d 20 54 68 65 20 5b 73 71 {H13011} The [sq
21740 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 64 62 lite3_prepare(db
21750 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a ,zSql,...)] and.
21760 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
21770 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
21780 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e db,zSql,...)] in
21790 74 65 72 66 61 63 65 73 20 69 6e 74 65 72 70 72 terfaces interpr
217a0 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 et the.**
217b0 20 20 20 74 65 78 74 20 69 6e 20 74 68 65 69 72 text in their
217c0 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 72 20 zSql parameter
217d0 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 as UTF-8..**.**
217e0 7b 48 31 33 30 31 32 7d 20 54 68 65 20 5b 73 71 {H13012} The [sq
217f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
21800 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e db,zSql,...)] an
21810 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 d.** [s
21820 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
21830 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 _v2(db,zSql,...)
21840 5d 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e 74 ] interfaces int
21850 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 20 20 erpret the.**
21860 20 20 20 20 20 20 20 74 65 78 74 20 69 6e 20 74 text in t
21870 68 65 69 72 20 7a 53 71 6c 20 70 61 72 61 6d 65 heir zSql parame
21880 74 65 72 20 61 73 20 55 54 46 2d 31 36 20 69 6e ter as UTF-16 in
21890 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 the native byte
218a0 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 order..**.** {H
218b0 31 33 30 31 33 7d 20 49 66 20 74 68 65 20 6e 42 13013} If the nB
218c0 79 74 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 yte argument to
218d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
218e0 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 _v2(db,zSql,nByt
218f0 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 e,...)].**
21900 20 20 20 20 61 6e 64 20 69 74 73 20 76 61 72 69 and its vari
21910 61 6e 74 73 20 69 73 20 6c 65 73 73 20 74 68 61 ants is less tha
21920 6e 20 7a 65 72 6f 2c 20 74 68 65 20 53 51 4c 20 n zero, the SQL
21930 74 65 78 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 text is.**
21940 20 20 20 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 read from zS
21950 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f ql is read up to
21960 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 the first zero
21970 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a terminator..**.*
21980 2a 20 7b 48 31 33 30 31 34 7d 20 49 66 20 74 68 * {H13014} If th
21990 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 e nByte argument
219a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 to [sqlite3_pre
219b0 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c pare_v2(db,zSql,
219c0 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 nByte,...)].**
219d0 20 20 20 20 20 20 20 20 61 6e 64 20 69 74 73 20 and its
219e0 76 61 72 69 61 6e 74 73 20 69 73 20 6e 6f 6e 2d variants is non-
219f0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 negative, then a
21a00 74 20 6d 6f 73 74 20 6e 42 79 74 65 73 20 62 79 t most nBytes by
21a10 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 tes of.**
21a20 20 20 20 53 51 4c 20 74 65 78 74 20 69 73 20 72 SQL text is r
21a30 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 0a 2a ead from zSql..*
21a40 2a 0a 2a 2a 20 7b 48 31 33 30 31 35 7d 20 49 6e *.** {H13015} In
21a50 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
21a60 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 50 e_v2(db,zSql,N,P
21a70 2c 70 7a 54 61 69 6c 29 5d 20 61 6e 64 20 69 74 ,pzTail)] and it
21a80 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a 20 20 20 s variants.**
21a90 20 20 20 20 20 20 20 69 66 20 74 68 65 20 7a 53 if the zS
21aa0 71 6c 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f ql input text co
21ab0 6e 74 61 69 6e 73 20 6d 6f 72 65 20 74 68 61 6e ntains more than
21ac0 20 6f 6e 65 20 53 51 4c 20 73 74 61 74 65 6d 65 one SQL stateme
21ad0 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 nt.** a
21ae0 6e 64 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 nd pzTail is not
21af0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 2a 70 7a 54 NULL, then *pzT
21b00 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 ail is made to p
21b10 6f 69 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20 oint to the.**
21b20 20 20 20 20 20 20 20 20 66 69 72 73 74 20 62 79 first by
21b30 74 65 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 te past the end
21b40 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c of the first SQL
21b50 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 statement in zS
21b60 71 6c 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ql..**
21b70 3c 74 6f 64 6f 3e 57 68 61 74 20 64 6f 65 73 20 <todo>What does
21b80 2a 70 7a 54 61 69 6c 20 70 6f 69 6e 74 20 74 6f *pzTail point to
21b90 20 69 66 20 74 68 65 72 65 20 69 73 20 6f 6e 65 if there is one
21ba0 20 73 74 61 74 65 6d 65 6e 74 3f 3c 2f 74 6f 64 statement?</tod
21bb0 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 36 o>.**.** {H13016
21bc0 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 } A successful c
21bd0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
21be0 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 prepare_v2(db,zS
21bf0 71 6c 2c 4e 2c 70 70 53 74 6d 74 2c 2e 2e 2e 29 ql,N,ppStmt,...)
21c00 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 ].** or
21c10 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 one of its vari
21c20 61 6e 74 73 20 77 72 69 74 65 73 20 69 6e 74 6f ants writes into
21c30 20 2a 70 70 53 74 6d 74 20 61 20 70 6f 69 6e 74 *ppStmt a point
21c40 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 er to a new.**
21c50 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 [prepare
21c60 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 d statement] or
21c70 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c a pointer to NUL
21c80 4c 20 69 66 20 7a 53 71 6c 20 63 6f 6e 74 61 69 L if zSql contai
21c90 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e ns.** n
21ca0 6f 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 othing other tha
21cb0 6e 20 77 68 69 74 65 73 70 61 63 65 20 6f 72 20 n whitespace or
21cc0 63 6f 6d 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 comments..**.**
21cd0 7b 48 31 33 30 31 39 7d 20 54 68 65 20 5b 73 71 {H13019} The [sq
21ce0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
21cf0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e ()] interface an
21d00 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 72 d its variants r
21d10 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 eturn.**
21d20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 [SQLITE_OK] or
21d30 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 an appropriate
21d40 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f [error code] upo
21d50 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a n failure..**.**
21d60 20 7b 48 31 33 30 32 31 7d 20 42 65 66 6f 72 65 {H13021} Before
21d70 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
21d80 65 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c e(db,zSql,nByte,
21d90 70 70 53 74 6d 74 2c 70 7a 54 61 69 6c 29 5d 20 ppStmt,pzTail)]
21da0 6f 72 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 or its.**
21db0 20 20 20 76 61 72 69 61 6e 74 73 20 72 65 74 75 variants retu
21dc0 72 6e 73 20 61 6e 20 65 72 72 6f 72 20 28 61 6e rns an error (an
21dd0 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 y value other th
21de0 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 29 2c an [SQLITE_OK]),
21df0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
21e00 79 20 66 69 72 73 74 20 73 65 74 20 2a 70 70 53 y first set *ppS
21e10 74 6d 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a tmt to NULL..*/.
21e20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 int sqlite3_prep
21e30 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a are(. sqlite3 *
21e40 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f db, /
21e50 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c * Database handl
21e60 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
21e70 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f r *zSql, /
21e80 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c * SQL statement,
21e90 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a UTF-8 encoded *
21ea0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 /. int nByte,
21eb0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d /* M
21ec0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
21ed0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 zSql in bytes.
21ee0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d */. sqlite3_stm
21ef0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 t **ppStmt, /*
21f00 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 OUT: Statement h
21f10 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
21f20 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 char **pzTail
21f30 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 /* OUT: Point
21f40 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 er to unused por
21f50 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a tion of zSql */.
21f60 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 );.int sqlite3_p
21f70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c repare_v2(. sql
21f80 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
21f90 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
21fa0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
21fb0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 st char *zSql,
21fc0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 /* SQL stat
21fd0 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 ement, UTF-8 enc
21fe0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 oded */. int nB
21ff0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 yte,
22000 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e /* Maximum len
22010 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 gth of zSql in b
22020 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 ytes. */. sqlit
22030 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 e3_stmt **ppStmt
22040 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 , /* OUT: State
22050 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 ment handle */.
22060 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a const char **pz
22070 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a Tail /* OUT:
22080 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 Pointer to unus
22090 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 ed portion of zS
220a0 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c ql */.);.int sql
220b0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a ite3_prepare16(.
220c0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
220d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
220e0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a abase handle */.
220f0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 const void *zS
22100 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c ql, /* SQL
22110 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d statement, UTF-
22120 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 16 encoded */.
22130 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 int nByte,
22140 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d /* Maxim
22150 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 um length of zSq
22160 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 l in bytes. */.
22170 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a sqlite3_stmt **
22180 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a ppStmt, /* OUT:
22190 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c Statement handl
221a0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 e */. const voi
221b0 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f d **pzTail /
221c0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 * OUT: Pointer t
221d0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e o unused portion
221e0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 of zSql */.);.i
221f0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nt sqlite3_prepa
22200 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 re16_v2(. sqlit
22210 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
22220 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 /* Database h
22230 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
22240 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 void *zSql,
22250 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d /* SQL statem
22260 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f ent, UTF-16 enco
22270 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 ded */. int nBy
22280 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 te,
22290 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 /* Maximum leng
222a0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 th of zSql in by
222b0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 tes. */. sqlite
222c0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 3_stmt **ppStmt,
222d0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d /* OUT: Statem
222e0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ent handle */.
222f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 const void **pzT
22300 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 ail /* OUT:
22310 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 Pointer to unuse
22320 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 d portion of zSq
22330 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 l */.);../*.** C
22340 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 API3REF: Retriev
22350 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 ing Statement SQ
22360 4c 20 7b 48 31 33 31 30 30 7d 20 3c 48 31 33 30 L {H13100} <H130
22370 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 00>.**.** This i
22380 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 nterface can be
22390 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 used to retrieve
223a0 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 a saved copy of
223b0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a the original.**
223c0 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 SQL text used t
223d0 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 o create a [prep
223e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
223f0 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e if that statemen
22400 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 t was.** compile
22410 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b d using either [
22420 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
22430 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 v2()] or [sqlite
22440 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
22450 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 ]..**.** INVARIA
22460 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 NTS:.**.** {H131
22470 30 31 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 01} If the [prep
22480 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
22490 70 61 73 73 65 64 20 61 73 20 74 68 65 20 61 72 passed as the ar
224a0 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 gument to.**
224b0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 [sqlite3_s
224c0 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c ql()] was compil
224d0 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 ed using either
224e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
224f0 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 _v2()] or.**
22500 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 [sqlite3_p
22510 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 repare16_v2()],
22520 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 then [sqlite3_sq
22530 6c 28 29 5d 20 72 65 74 75 72 6e 73 0a 2a 2a 20 l()] returns.**
22540 20 20 20 20 20 20 20 20 20 61 20 70 6f 69 6e 74 a point
22550 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 er to a zero-ter
22560 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 20 63 minated string c
22570 6f 6e 74 61 69 6e 69 6e 67 20 61 20 55 54 46 2d ontaining a UTF-
22580 38 20 72 65 6e 64 65 72 69 6e 67 0a 2a 2a 20 20 8 rendering.**
22590 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 6f of the o
225a0 72 69 67 69 6e 61 6c 20 53 51 4c 20 73 74 61 74 riginal SQL stat
225b0 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ement..**.** {H1
225c0 33 31 30 32 7d 20 49 66 20 74 68 65 20 5b 70 72 3102} If the [pr
225d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
225e0 5d 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 ] passed as the
225f0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 argument to.**
22600 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
22610 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 _sql()] was comp
22620 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 iled using eithe
22630 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
22640 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 re()] or.**
22650 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 [sqlite3_pr
22660 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 65 6e epare16()], then
22670 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d [sqlite3_sql()]
22680 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 returns a NULL
22690 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b pointer..**.** {
226a0 48 31 33 31 30 33 7d 20 54 68 65 20 73 74 72 69 H13103} The stri
226b0 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b ng returned by [
226c0 73 71 6c 69 74 65 33 5f 73 71 6c 28 53 29 5d 20 sqlite3_sql(S)]
226d0 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 is valid until t
226e0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b he.** [
226f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
22700 6e 74 5d 20 53 20 69 73 20 64 65 6c 65 74 65 64 nt] S is deleted
22710 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
22720 66 69 6e 61 6c 69 7a 65 28 53 29 5d 2e 0a 2a 2f finalize(S)]..*/
22730 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
22740 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 ite3_sql(sqlite3
22750 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a _stmt *pStmt);..
22760 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
22770 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 Dynamically Type
22780 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 20 7b d Value Object {
22790 48 31 35 30 30 30 7d 20 3c 53 32 30 32 30 30 3e H15000} <S20200>
227a0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 .** KEYWORDS: {p
227b0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
227c0 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 _value} {unprote
227d0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
227e0 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 ue}.**.** SQLite
227f0 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 uses the sqlite
22800 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 3_value object t
22810 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 o represent all
22820 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 values.** that c
22830 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 an be stored in
22840 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 a database table
22850 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 . SQLite uses dy
22860 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 namic typing.**
22870 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 for the values i
22880 74 20 73 74 6f 72 65 73 2e 20 56 61 6c 75 65 73 t stores. Values
22890 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 stored in sqlit
228a0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
228b0 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 .** can be integ
228c0 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f ers, floating po
228d0 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 int values, stri
228e0 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e ngs, BLOBs, or N
228f0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 ULL..**.** An sq
22900 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
22910 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 ct may be either
22920 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 "protected" or
22930 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a "unprotected"..*
22940 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 * Some interface
22950 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 s require a prot
22960 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
22970 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 lue. Other inte
22980 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 rfaces.** will a
22990 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70 ccept either a p
229a0 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 rotected or an u
229b0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
229c0 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 e3_value..** Eve
229d0 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 ry interface tha
229e0 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 t accepts sqlite
229f0 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 3_value argument
22a00 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 s specifies.** w
22a10 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 hether or not it
22a20 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 requires a prot
22a30 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
22a40 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 lue..**.** The t
22a50 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 erms "protected"
22a60 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 and "unprotecte
22a70 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 d" refer to whet
22a80 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 her or not.** a
22a90 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 mutex is held.
22aa0 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 A internal mutex
22ab0 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 is held for a p
22ac0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 rotected.** sqli
22ad0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
22ae0 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 but no mutex is
22af0 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 held for an unp
22b00 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 rotected.** sqli
22b10 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
22b20 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 . If SQLite is
22b30 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 compiled to be s
22b40 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a ingle-threaded.*
22b50 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f * (with [SQLITE_
22b60 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e THREADSAFE=0] an
22b70 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f d with [sqlite3_
22b80 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 threadsafe()] re
22b90 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 turning 0).** or
22ba0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 if SQLite is ru
22bb0 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 n in one of redu
22bc0 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 ced mutex modes
22bd0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 .** [SQLITE_CONF
22be0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d IG_SINGLETHREAD]
22bf0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 or [SQLITE_CONF
22c00 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a IG_MULTITHREAD].
22c10 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 ** then there is
22c20 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 no distinction
22c30 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 between protecte
22c40 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 d and unprotecte
22c50 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c d.** sqlite3_val
22c60 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 ue objects and t
22c70 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 hey can be used
22c80 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e interchangeably.
22c90 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f However,.** fo
22ca0 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 r maximum code p
22cb0 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 ortability it is
22cc0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 recommended tha
22cd0 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a t applications.*
22ce0 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 * still make the
22cf0 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 distinction bet
22d00 77 65 65 6e 20 62 65 74 77 65 65 6e 20 70 72 6f ween between pro
22d10 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f tected and unpro
22d20 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 tected.** sqlite
22d30 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 3_value objects
22d40 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 even when not st
22d50 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e rictly required.
22d60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
22d70 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
22d80 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64 that are passed
22d90 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 as parameters i
22da0 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 nto the.** imple
22db0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 mentation of [ap
22dc0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
22dd0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d d SQL functions]
22de0 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a are protected..
22df0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 ** The sqlite3_v
22e00 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 alue object retu
22e10 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 rned by.** [sqli
22e20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 te3_column_value
22e30 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 ()] is unprotect
22e40 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 ed..** Unprotect
22e50 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
22e60 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c objects may onl
22e70 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a y be used with.*
22e80 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c * [sqlite3_resul
22e90 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b t_value()] and [
22ea0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c sqlite3_bind_val
22eb0 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 ue()]..** The [s
22ec0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f qlite3_value_blo
22ed0 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 b | sqlite3_valu
22ee0 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 e_type()] family
22ef0 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 of.** interface
22f00 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 s require protec
22f10 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
22f20 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 e objects..*/.ty
22f30 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d pedef struct Mem
22f40 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a sqlite3_value;.
22f50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
22f60 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f SQL Function Co
22f70 6e 74 65 78 74 20 4f 62 6a 65 63 74 20 7b 48 31 ntext Object {H1
22f80 36 30 30 31 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 6001} <S20200>.*
22f90 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 *.** The context
22fa0 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c in which an SQL
22fb0 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 function execut
22fc0 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 es is stored in
22fd0 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f an.** sqlite3_co
22fe0 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 41 ntext object. A
22ff0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 pointer to an s
23000 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f qlite3_context o
23010 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 bject.** is alwa
23020 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 ys first paramet
23030 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 er to [applicati
23040 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 on-defined SQL f
23050 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 unctions]..** Th
23060 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
23070 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 fined SQL functi
23080 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f on implementatio
23090 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 n will pass this
230a0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f .** pointer thro
230b0 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 ugh into calls t
230c0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c o [sqlite3_resul
230d0 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f t_int | sqlite3_
230e0 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 result()],.** [s
230f0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
23100 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 _context()], [sq
23110 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 lite3_user_data(
23120 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
23130 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c context_db_handl
23140 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 e()], [sqlite3_g
23150 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a et_auxdata()],.*
23160 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 * and/or [sqlite
23170 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 3_set_auxdata()]
23180 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
23190 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 uct sqlite3_cont
231a0 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ext sqlite3_cont
231b0 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ext;../*.** CAPI
231c0 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 3REF: Binding Va
231d0 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 lues To Prepared
231e0 20 53 74 61 74 65 6d 65 6e 74 73 20 7b 48 31 33 Statements {H13
231f0 35 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 500} <S70300>.**
23200 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 KEYWORDS: {host
23210 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 parameter} {hos
23220 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 t parameters} {h
23230 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 ost parameter na
23240 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a me}.** KEYWORDS:
23250 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d {SQL parameter}
23260 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 {SQL parameters
23270 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e } {parameter bin
23280 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 ding}.**.** In t
23290 68 65 20 53 51 4c 20 73 74 72 69 6e 67 73 20 69 he SQL strings i
232a0 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 nput to [sqlite3
232b0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 _prepare_v2()] a
232c0 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c nd its variants,
232d0 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 .** literals may
232e0 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 be replaced by
232f0 61 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 6f a parameter in o
23300 6e 65 20 6f 66 20 74 68 65 73 65 20 66 6f 72 6d ne of these form
23310 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a s:.**.** <ul>.**
23320 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e <li> ?.** <li>
23330 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 ?NNN.** <li>
23340 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 :VVV.** <li> @V
23350 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 VV.** <li> $VVV
23360 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
23370 49 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 In the parameter
23380 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f forms shown abo
23390 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74 ve NNN is an int
233a0 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a eger literal,.**
233b0 20 61 6e 64 20 56 56 56 20 69 73 20 61 6e 20 61 and VVV is an a
233c0 6c 70 68 61 2d 6e 75 6d 65 72 69 63 20 70 61 72 lpha-numeric par
233d0 61 6d 65 74 65 72 20 6e 61 6d 65 2e 20 54 68 65 ameter name. The
233e0 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 values of these
233f0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 .** parameters (
23400 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 also called "hos
23410 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 t parameter name
23420 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d s" or "SQL param
23430 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 eters").** can b
23440 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 e set using the
23450 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 sqlite3_bind_*()
23460 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 routines define
23470 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 d here..**.** Th
23480 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
23490 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
234a0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 bind_*() routine
234b0 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 s is always.** a
234c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
234d0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f [sqlite3_stmt] o
234e0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 bject returned f
234f0 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f rom.** [sqlite3_
23500 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
23510 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a its variants..*
23520 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 *.** The second
23530 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 argument is the
23540 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c index of the SQL
23550 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 parameter to be
23560 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20 6c 65 66 set..** The lef
23570 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 tmost SQL parame
23580 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 ter has an index
23590 20 6f 66 20 31 2e 20 20 57 68 65 6e 20 74 68 65 of 1. When the
235a0 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 same named.** S
235b0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 QL parameter is
235c0 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f used more than o
235d0 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 nce, second and
235e0 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 subsequent.** oc
235f0 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 currences have t
23600 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 he same index as
23610 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 the first occur
23620 72 65 6e 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6e rence..** The in
23630 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 dex for named pa
23640 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 rameters can be
23650 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 looked up using
23660 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
23670 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 bind_parameter_i
23680 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 ndex()] API if d
23690 65 73 69 72 65 64 2e 20 20 54 68 65 20 69 6e 64 esired. The ind
236a0 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 ex.** for "?NNN"
236b0 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 parameters is t
236c0 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e he value of NNN.
236d0 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75 .** The NNN valu
236e0 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 e must be betwee
236f0 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c n 1 and the [sql
23700 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a ite3_limit()].**
23710 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 parameter [SQLI
23720 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c TE_LIMIT_VARIABL
23730 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 E_NUMBER] (defau
23740 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a lt value: 999)..
23750 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 **.** The third
23760 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 argument is the
23770 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f value to bind to
23780 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a the parameter..
23790 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 72 **.** In those r
237a0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 outines that hav
237b0 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d e a fourth argum
237c0 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 ent, its value i
237d0 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 s the.** number
237e0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 of bytes in the
237f0 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 parameter. To b
23800 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c e clear: the val
23810 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d ue is the.** num
23820 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c ber of <u>bytes<
23830 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 /u> in the value
23840 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 , not the number
23850 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a of characters..
23860 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 ** If the fourth
23870 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 parameter is ne
23880 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 gative, the leng
23890 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 th of the string
238a0 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 is.** the numbe
238b0 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f r of bytes up to
238c0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 the first zero
238d0 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a terminator..**.*
238e0 2a 20 54 68 65 20 66 69 66 74 68 20 61 72 67 75 * The fifth argu
238f0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f ment to sqlite3_
23900 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c bind_blob(), sql
23910 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 ite3_bind_text()
23920 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 , and.** sqlite3
23930 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 _bind_text16() i
23940 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 s a destructor u
23950 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f sed to dispose o
23960 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a f the BLOB or.**
23970 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 string after SQ
23980 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 Lite has finishe
23990 64 20 77 69 74 68 20 69 74 2e 20 49 66 20 74 68 d with it. If th
239a0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 e fifth argument
239b0 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 is.** the speci
239c0 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 al value [SQLITE
239d0 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 _STATIC], then S
239e0 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 QLite assumes th
239f0 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d at the.** inform
23a00 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 ation is in stat
23a10 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 ic, unmanaged sp
23a20 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 ace and does not
23a30 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 need to be free
23a40 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 66 d..** If the fif
23a50 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 th argument has
23a60 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 the value [SQLIT
23a70 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 E_TRANSIENT], th
23a80 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b en.** SQLite mak
23a90 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 es its own priva
23aa0 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 te copy of the d
23ab0 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c ata immediately,
23ac0 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 before.** the s
23ad0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 qlite3_bind_*()
23ae0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e routine returns.
23af0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
23b00 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 e3_bind_zeroblob
23b10 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 () routine binds
23b20 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 a BLOB of lengt
23b30 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 h N that.** is f
23b40 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 illed with zeroe
23b50 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f 62 20 75 s. A zeroblob u
23b60 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 ses a fixed amou
23b70 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 nt of memory.**
23b80 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 (just an integer
23b90 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a to hold its siz
23ba0 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 e) while it is b
23bb0 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a eing processed..
23bc0 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 ** Zeroblobs are
23bd0 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 intended to ser
23be0 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 ve as placeholde
23bf0 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f rs for BLOBs who
23c00 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 se.** content is
23c10 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 later written u
23c20 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 sing.** [sqlite3
23c30 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 _blob_open | inc
23c40 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f remental BLOB I/
23c50 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 O] routines..**
23c60 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 A negative value
23c70 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f for the zeroblo
23c80 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a b results in a z
23c90 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e ero-length BLOB.
23ca0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
23cb0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 e3_bind_*() rout
23cc0 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c ines must be cal
23cd0 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73 71 led after.** [sq
23ce0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
23cf0 28 29 5d 20 28 61 6e 64 20 69 74 73 20 76 61 72 ()] (and its var
23d00 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69 74 iants) or [sqlit
23d10 65 33 5f 72 65 73 65 74 28 29 5d 20 61 6e 64 0a e3_reset()] and.
23d20 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 ** before [sqlit
23d30 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 42 e3_step()]..** B
23d40 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 indings are not
23d50 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b cleared by the [
23d60 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
23d70 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62 routine..** Unb
23d80 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 ound parameters
23d90 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 are interpreted
23da0 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 as NULL..**.** T
23db0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 hese routines re
23dc0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d turn [SQLITE_OK]
23dd0 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 on success or a
23de0 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69 66 0a n error code if.
23df0 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 ** anything goes
23e00 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 54 45 wrong. [SQLITE
23e10 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 _RANGE] is retur
23e20 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d ned if the param
23e30 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 eter.** index is
23e40 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 out of range.
23e50 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 [SQLITE_NOMEM] i
23e60 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 s returned if ma
23e70 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a lloc() fails..**
23e80 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
23e90 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e might be return
23ea0 65 64 20 69 66 20 74 68 65 73 65 20 72 6f 75 74 ed if these rout
23eb0 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 ines are called
23ec0 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75 61 6c 20 on a.** virtual
23ed0 6d 61 63 68 69 6e 65 20 74 68 61 74 20 69 73 20 machine that is
23ee0 74 68 65 20 77 72 6f 6e 67 20 73 74 61 74 65 20 the wrong state
23ef0 6f 72 20 77 68 69 63 68 20 68 61 73 20 61 6c 72 or which has alr
23f00 65 61 64 79 20 62 65 65 6e 20 66 69 6e 61 6c 69 eady been finali
23f10 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63 74 69 6f zed..** Detectio
23f20 6e 20 6f 66 20 6d 69 73 75 73 65 20 69 73 20 75 n of misuse is u
23f30 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41 70 70 6c nreliable. Appl
23f40 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 ications should
23f50 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e not depend.** on
23f60 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 72 SQLITE_MISUSE r
23f70 65 74 75 72 6e 73 2e 20 20 53 51 4c 49 54 45 5f eturns. SQLITE_
23f80 4d 49 53 55 53 45 20 69 73 20 69 6e 74 65 6e 64 MISUSE is intend
23f90 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 61 ed to indicate a
23fa0 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65 72 72 6f .** a logic erro
23fb0 72 20 69 6e 20 74 68 65 20 61 70 70 6c 69 63 61 r in the applica
23fc0 74 69 6f 6e 2e 20 20 46 75 74 75 72 65 20 76 65 tion. Future ve
23fd0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
23fe0 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e 69 63 20 might.** panic
23ff0 72 61 74 68 65 72 20 74 68 61 6e 20 72 65 74 75 rather than retu
24000 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 rn SQLITE_MISUSE
24010 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
24020 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f : [sqlite3_bind_
24030 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 parameter_count(
24040 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
24050 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e bind_parameter_n
24060 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c ame()], and [sql
24070 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
24080 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a ter_index()]..**
24090 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
240a0 2a 2a 0a 2a 2a 20 7b 48 31 33 35 30 36 7d 20 54 **.** {H13506} T
240b0 68 65 20 5b 53 51 4c 20 73 74 61 74 65 6d 65 6e he [SQL statemen
240c0 74 20 63 6f 6d 70 69 6c 65 72 5d 20 72 65 63 6f t compiler] reco
240d0 67 6e 69 7a 65 73 20 74 6f 6b 65 6e 73 20 6f 66 gnizes tokens of
240e0 20 74 68 65 20 66 6f 72 6d 73 0a 2a 2a 20 20 20 the forms.**
240f0 20 20 20 20 20 20 20 22 3f 22 2c 20 22 3f 4e 4e "?", "?NN
24100 4e 22 2c 20 22 24 56 56 56 22 2c 20 22 3a 56 56 N", "$VVV", ":VV
24110 56 22 2c 20 61 6e 64 20 22 40 56 56 56 22 20 61 V", and "@VVV" a
24120 73 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 s SQL parameters
24130 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 ,.** wh
24140 65 72 65 20 4e 4e 4e 20 69 73 20 61 6e 79 20 73 ere NNN is any s
24150 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f equence of one o
24160 72 20 6d 6f 72 65 20 64 69 67 69 74 73 0a 2a 2a r more digits.**
24170 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 77 68 and wh
24180 65 72 65 20 56 56 56 20 69 73 20 61 6e 79 20 73 ere VVV is any s
24190 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f equence of one o
241a0 72 20 6d 6f 72 65 20 61 6c 70 68 61 6e 75 6d 65 r more alphanume
241b0 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ric.**
241c0 63 68 61 72 61 63 74 65 72 73 20 6f 72 20 22 3a characters or ":
241d0 3a 22 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 66 6f :" optionally fo
241e0 6c 6c 6f 77 65 64 20 62 79 20 61 20 73 74 72 69 llowed by a stri
241f0 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a ng containing.**
24200 20 20 20 20 20 20 20 20 20 20 6e 6f 20 73 70 61 no spa
24210 63 65 73 20 61 6e 64 20 63 6f 6e 74 61 69 6e 65 ces and containe
24220 64 20 77 69 74 68 69 6e 20 70 61 72 65 6e 74 68 d within parenth
24230 65 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 eses..**.** {H13
24240 35 30 39 7d 20 54 68 65 20 69 6e 69 74 69 61 6c 509} The initial
24250 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c value of an SQL
24260 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 parameter is NU
24270 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 LL..**.** {H1351
24280 32 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 2} The index of
24290 61 6e 20 22 3f 22 20 53 51 4c 20 70 61 72 61 6d an "?" SQL param
242a0 65 74 65 72 20 69 73 20 6f 6e 65 20 6c 61 72 67 eter is one larg
242b0 65 72 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20 20 er than the.**
242c0 20 20 20 20 20 20 20 20 6c 61 72 67 65 73 74 20 largest
242d0 69 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72 index of SQL par
242e0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 6c 65 ameter to the le
242f0 66 74 2c 20 6f 72 20 31 20 69 66 0a 2a 2a 20 20 ft, or 1 if.**
24300 20 20 20 20 20 20 20 20 74 68 65 20 22 3f 22 20 the "?"
24310 69 73 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 is the leftmost
24320 53 51 4c 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a SQL parameter..*
24330 2a 0a 2a 2a 20 7b 48 31 33 35 31 35 7d 20 54 68 *.** {H13515} Th
24340 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f e index of an "?
24350 4e 4e 4e 22 20 53 51 4c 20 70 61 72 61 6d 65 74 NNN" SQL paramet
24360 65 72 20 69 73 20 74 68 65 20 69 6e 74 65 67 65 er is the intege
24370 72 20 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 r NNN..**.** {H1
24380 33 35 31 38 7d 20 54 68 65 20 69 6e 64 65 78 20 3518} The index
24390 6f 66 20 61 6e 20 22 3a 56 56 56 22 2c 20 22 24 of an ":VVV", "$
243a0 56 56 56 22 2c 20 6f 72 20 22 40 56 56 56 22 20 VVV", or "@VVV"
243b0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 SQL parameter is
243c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
243d0 20 73 61 6d 65 20 61 73 20 74 68 65 20 69 6e 64 same as the ind
243e0 65 78 20 6f 66 20 6c 65 66 74 6d 6f 73 74 20 6f ex of leftmost o
243f0 63 63 75 72 72 65 6e 63 65 73 20 6f 66 20 74 68 ccurrences of th
24400 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 e same.**
24410 20 20 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 parameter, or
24420 20 6f 6e 65 20 6d 6f 72 65 20 74 68 61 6e 20 74 one more than t
24430 68 65 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 he largest index
24440 20 6f 76 65 72 20 61 6c 6c 0a 2a 2a 20 20 20 20 over all.**
24450 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 73 parameters
24460 20 74 6f 20 74 68 65 20 6c 65 66 74 20 69 66 20 to the left if
24470 74 68 69 73 20 69 73 20 74 68 65 20 66 69 72 73 this is the firs
24480 74 20 6f 63 63 75 72 72 65 6e 63 65 0a 2a 2a 20 t occurrence.**
24490 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 69 73 of this
244a0 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 31 parameter, or 1
244b0 20 69 66 20 74 68 69 73 20 69 73 20 74 68 65 20 if this is the
244c0 6c 65 66 74 6d 6f 73 74 20 70 61 72 61 6d 65 74 leftmost paramet
244d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 er..**.** {H1352
244e0 31 7d 20 54 68 65 20 5b 53 51 4c 20 73 74 61 74 1} The [SQL stat
244f0 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 ement compiler]
24500 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 5b 53 fails with an [S
24510 51 4c 49 54 45 5f 52 41 4e 47 45 5d 0a 2a 2a 20 QLITE_RANGE].**
24520 20 20 20 20 20 20 20 20 20 65 72 72 6f 72 20 69 error i
24530 66 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 f the index of a
24540 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 n SQL parameter
24550 69 73 20 6c 65 73 73 20 74 68 61 6e 20 31 0a 2a is less than 1.*
24560 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 67 72 * or gr
24570 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 63 eater than the c
24580 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 53 51 4c 49 ompile-time SQLI
24590 54 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f TE_MAX_VARIABLE_
245a0 4e 55 4d 42 45 52 0a 2a 2a 20 20 20 20 20 20 20 NUMBER.**
245b0 20 20 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a parameter..**
245c0 0a 2a 2a 20 7b 48 31 33 35 32 34 7d 20 43 61 6c .** {H13524} Cal
245d0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 ls to [sqlite3_b
245e0 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 ind_text | sqlit
245f0 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 56 2c 2e 2e e3_bind(S,N,V,..
24600 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 .)].**
24610 61 73 73 6f 63 69 61 74 65 20 74 68 65 20 76 61 associate the va
24620 6c 75 65 20 56 20 77 69 74 68 20 61 6c 6c 20 53 lue V with all S
24630 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 68 61 QL parameters ha
24640 76 69 6e 67 20 61 6e 0a 2a 2a 20 20 20 20 20 20 ving an.**
24650 20 20 20 20 69 6e 64 65 78 20 6f 66 20 4e 20 69 index of N i
24660 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 n the [prepared
24670 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a statement] S..**
24680 0a 2a 2a 20 7b 48 31 33 35 32 37 7d 20 43 61 6c .** {H13527} Cal
24690 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 ls to [sqlite3_b
246a0 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 ind_text | sqlit
246b0 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 2e 2e 2e 29 e3_bind(S,N,...)
246c0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76 ].** ov
246d0 65 72 72 69 64 65 20 70 72 69 6f 72 20 63 61 6c erride prior cal
246e0 6c 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 ls with the same
246f0 20 76 61 6c 75 65 73 20 6f 66 20 53 20 61 6e 64 values of S and
24700 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 N..**.** {H1353
24710 30 7d 20 42 69 6e 64 69 6e 67 73 20 65 73 74 61 0} Bindings esta
24720 62 6c 69 73 68 65 64 20 62 79 20 5b 73 71 6c 69 blished by [sqli
24730 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 te3_bind_text |
24740 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 2e sqlite3_bind(S,.
24750 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 ..)].**
24760 20 70 65 72 73 69 73 74 20 61 63 72 6f 73 73 20 persist across
24770 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
24780 33 5f 72 65 73 65 74 28 53 29 5d 2e 0a 2a 2a 0a 3_reset(S)]..**.
24790 2a 2a 20 7b 48 31 33 35 33 33 7d 20 49 6e 20 63 ** {H13533} In c
247a0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
247b0 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 _bind_blob(S,N,V
247c0 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 ,L,D)],.**
247d0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e [sqlite3_bin
247e0 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 d_text(S,N,V,L,D
247f0 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 )], or.**
24800 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 [sqlite3_bind
24810 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c _text16(S,N,V,L,
24820 44 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 D)] SQLite binds
24830 20 74 68 65 20 66 69 72 73 74 20 4c 0a 2a 2a 20 the first L.**
24840 20 20 20 20 20 20 20 20 20 62 79 74 65 73 20 6f bytes o
24850 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 f the BLOB or st
24860 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 ring pointed to
24870 62 79 20 56 2c 20 77 68 65 6e 20 4c 0a 2a 2a 20 by V, when L.**
24880 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d is non-
24890 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 negative..**.**
248a0 7b 48 31 33 35 33 36 7d 20 49 6e 20 63 61 6c 6c {H13536} In call
248b0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 s to [sqlite3_bi
248c0 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c nd_text(S,N,V,L,
248d0 44 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 D)] or.**
248e0 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 [sqlite3_bind
248f0 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c _text16(S,N,V,L,
24900 44 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 D)] SQLite binds
24910 20 63 68 61 72 61 63 74 65 72 73 0a 2a 2a 20 20 characters.**
24920 20 20 20 20 20 20 20 20 66 72 6f 6d 20 56 20 74 from V t
24930 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 hrough the first
24940 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 20 zero character
24950 77 68 65 6e 20 4c 20 69 73 20 6e 65 67 61 74 69 when L is negati
24960 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 ve..**.** {H1353
24970 39 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 9} In calls to [
24980 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
24990 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a b(S,N,V,L,D)],.*
249a0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
249b0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c te3_bind_text(S,
249c0 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a N,V,L,D)], or.**
249d0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
249e0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 e3_bind_text16(S
249f0 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 ,N,V,L,D)] when
24a00 44 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c D is the special
24a10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e .** con
24a20 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 stant [SQLITE_ST
24a30 41 54 49 43 5d 2c 20 53 51 4c 69 74 65 20 61 73 ATIC], SQLite as
24a40 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 76 sumes that the v
24a50 61 6c 75 65 20 56 0a 2a 2a 20 20 20 20 20 20 20 alue V.**
24a60 20 20 20 69 73 20 68 65 6c 64 20 69 6e 20 73 74 is held in st
24a70 61 74 69 63 20 75 6e 6d 61 6e 61 67 65 64 20 73 atic unmanaged s
24a80 70 61 63 65 20 74 68 61 74 20 77 69 6c 6c 20 6e pace that will n
24a90 6f 74 20 63 68 61 6e 67 65 0a 2a 2a 20 20 20 20 ot change.**
24aa0 20 20 20 20 20 20 64 75 72 69 6e 67 20 74 68 65 during the
24ab0 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 lifetime of the
24ac0 20 62 69 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 binding..**.**
24ad0 7b 48 31 33 35 34 32 7d 20 49 6e 20 63 61 6c 6c {H13542} In call
24ae0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 s to [sqlite3_bi
24af0 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c nd_blob(S,N,V,L,
24b00 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 D)],.**
24b10 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 [sqlite3_bind_t
24b20 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c ext(S,N,V,L,D)],
24b30 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 or.**
24b40 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 [sqlite3_bind_te
24b50 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d xt16(S,N,V,L,D)]
24b60 20 77 68 65 6e 20 44 20 69 73 20 74 68 65 20 73 when D is the s
24b70 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 pecial.**
24b80 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c constant [SQL
24b90 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 ITE_TRANSIENT],
24ba0 74 68 65 20 72 6f 75 74 69 6e 65 20 6d 61 6b 65 the routine make
24bb0 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 s a.**
24bc0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 private copy of
24bd0 74 68 65 20 76 61 6c 75 65 20 56 20 62 65 66 6f the value V befo
24be0 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a re it returns..*
24bf0 2a 0a 2a 2a 20 7b 48 31 33 35 34 35 7d 20 49 6e *.** {H13545} In
24c00 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 calls to [sqlit
24c10 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e e3_bind_blob(S,N
24c20 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 ,V,L,D)],.**
24c30 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 [sqlite3_b
24c40 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c ind_text(S,N,V,L
24c50 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 ,D)], or.**
24c60 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 [sqlite3_bi
24c70 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c nd_text16(S,N,V,
24c80 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20 L,D)] when D is
24c90 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 a pointer to.**
24ca0 20 20 20 20 20 20 20 20 20 61 20 66 75 6e 63 74 a funct
24cb0 69 6f 6e 2c 20 53 51 4c 69 74 65 20 69 6e 76 6f ion, SQLite invo
24cc0 6b 65 73 20 74 68 61 74 20 66 75 6e 63 74 69 6f kes that functio
24cd0 6e 20 74 6f 20 64 65 73 74 72 6f 79 20 74 68 65 n to destroy the
24ce0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c .** val
24cf0 75 65 20 56 20 61 66 74 65 72 20 69 74 20 68 61 ue V after it ha
24d00 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 s finished using
24d10 20 74 68 65 20 76 61 6c 75 65 20 56 2e 0a 2a 2a the value V..**
24d20 0a 2a 2a 20 7b 48 31 33 35 34 38 7d 20 49 6e 20 .** {H13548} In
24d30 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
24d40 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 3_bind_zeroblob(
24d50 53 2c 4e 2c 56 2c 4c 29 5d 20 74 68 65 20 76 61 S,N,V,L)] the va
24d60 6c 75 65 20 62 6f 75 6e 64 0a 2a 2a 20 20 20 20 lue bound.**
24d70 20 20 20 20 20 20 69 73 20 61 20 42 4c 4f 42 20 is a BLOB
24d80 6f 66 20 4c 20 62 79 74 65 73 2c 20 6f 72 20 61 of L bytes, or a
24d90 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f zero-length BLO
24da0 42 20 69 66 20 4c 20 69 73 20 6e 65 67 61 74 69 B if L is negati
24db0 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 35 ve..**.** {H1355
24dc0 31 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 1} In calls to [
24dd0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c sqlite3_bind_val
24de0 75 65 28 53 2c 4e 2c 56 29 5d 20 74 68 65 20 56 ue(S,N,V)] the V
24df0 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 0a 2a 2a argument may.**
24e00 20 20 20 20 20 20 20 20 20 20 62 65 20 65 69 74 be eit
24e10 68 65 72 20 61 20 5b 70 72 6f 74 65 63 74 65 64 her a [protected
24e20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
24e30 6f 62 6a 65 63 74 20 6f 72 20 61 6e 0a 2a 2a 20 object or an.**
24e40 20 20 20 20 20 20 20 20 20 5b 75 6e 70 72 6f 74 [unprot
24e50 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
24e60 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a lue] object..*/.
24e70 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
24e80 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 _blob(sqlite3_st
24e90 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 mt*, int, const
24ea0 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f void*, int n, vo
24eb0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 id(*)(void*));.i
24ec0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
24ed0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 double(sqlite3_s
24ee0 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c tmt*, int, doubl
24ef0 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f e);.int sqlite3_
24f00 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 bind_int(sqlite3
24f10 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 _stmt*, int, int
24f20 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 );.int sqlite3_b
24f30 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 ind_int64(sqlite
24f40 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 3_stmt*, int, sq
24f50 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e lite3_int64);.in
24f60 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e t sqlite3_bind_n
24f70 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ull(sqlite3_stmt
24f80 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c *, int);.int sql
24f90 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 ite3_bind_text(s
24fa0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
24fb0 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 t, const char*,
24fc0 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 int n, void(*)(v
24fd0 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 oid*));.int sqli
24fe0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 te3_bind_text16(
24ff0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
25000 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c nt, const void*,
25010 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f int, void(*)(vo
25020 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 id*));.int sqlit
25030 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 e3_bind_value(sq
25040 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
25050 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f , const sqlite3_
25060 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c value*);.int sql
25070 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c ite3_bind_zerobl
25080 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ob(sqlite3_stmt*
25090 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a , int, int n);..
250a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
250b0 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 Number Of SQL Pa
250c0 72 61 6d 65 74 65 72 73 20 7b 48 31 33 36 30 30 rameters {H13600
250d0 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a } <S70300>.**.**
250e0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 This routine ca
250f0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e n be used to fin
25100 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 d the number of
25110 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d [SQL parameters]
25120 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 .** in a [prepar
25130 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 ed statement].
25140 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 SQL parameters a
25150 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 re tokens of the
25160 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f .** form "?", "?
25170 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 NNN", ":AAA", "$
25180 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 AAA", or "@AAA"
25190 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a that serve as.**
251a0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f placeholders fo
251b0 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 r values that ar
251c0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f e [sqlite3_bind_
251d0 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a blob | bound].**
251e0 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 to the paramete
251f0 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 rs at a later ti
25200 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 me..**.** This r
25210 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 outine actually
25220 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 returns the inde
25230 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 x of the largest
25240 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 (rightmost).**
25250 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 parameter. For a
25260 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 ll forms except
25270 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 ?NNN, this will
25280 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 correspond to th
25290 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 e.** number of u
252a0 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 nique parameters
252b0 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 . If parameters
252c0 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 61 72 65 of the ?NNN are
252d0 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 used,.** there
252e0 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 may be gaps in t
252f0 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 he list..**.** S
25300 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
25310 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 3_bind_blob|sqli
25320 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 te3_bind()],.**
25330 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
25340 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c rameter_name()],
25350 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
25360 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
25370 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 index()]..**.**
25380 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
25390 2a 20 7b 48 31 33 36 30 31 7d 20 54 68 65 20 5b * {H13601} The [
253a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
253b0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 53 29 5d ameter_count(S)]
253c0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
253d0 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 ns.** t
253e0 68 65 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 he largest index
253f0 20 6f 66 20 61 6c 6c 20 53 51 4c 20 70 61 72 61 of all SQL para
25400 6d 65 74 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a meters in the.**
25410 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 [prepa
25420 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
25430 2c 20 6f 72 20 30 20 69 66 20 53 20 63 6f 6e 74 , or 0 if S cont
25440 61 69 6e 73 20 6e 6f 20 53 51 4c 20 70 61 72 61 ains no SQL para
25450 6d 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e 74 20 73 meters..*/.int s
25460 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
25470 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 meter_count(sqli
25480 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a te3_stmt*);../*.
25490 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d ** CAPI3REF: Nam
254a0 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 e Of A Host Para
254b0 6d 65 74 65 72 20 7b 48 31 33 36 32 30 7d 20 3c meter {H13620} <
254c0 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S70300>.**.** Th
254d0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 is routine retur
254e0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
254f0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
25500 6e 2d 74 68 0a 2a 2a 20 5b 53 51 4c 20 70 61 72 n-th.** [SQL par
25510 61 6d 65 74 65 72 5d 20 69 6e 20 61 20 5b 70 72 ameter] in a [pr
25520 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
25530 5d 2e 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 ]..** SQL parame
25540 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d ters of the form
25550 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 "?NNN" or ":AAA
25560 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 " or "@AAA" or "
25570 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 $AAA".** have a
25580 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 name which is th
25590 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 e string "?NNN"
255a0 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 or ":AAA" or "@A
255b0 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a AA" or "$AAA".**
255c0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a respectively..*
255d0 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 * In other words
255e0 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a , the initial ":
255f0 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 " or "$" or "@"
25600 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 or "?".** is inc
25610 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 luded as part of
25620 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 the name..** Pa
25630 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 rameters of the
25640 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 form "?" without
25650 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 a following int
25660 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d eger have no nam
25670 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 61 6c 73 e.** and are als
25680 6f 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 o referred to as
25690 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 "anonymous para
256a0 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 54 meters"..**.** T
256b0 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 he first host pa
256c0 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 rameter has an i
256d0 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 ndex of 1, not 0
256e0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 76 ..**.** If the v
256f0 61 6c 75 65 20 6e 20 69 73 20 6f 75 74 20 6f 66 alue n is out of
25700 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 range or if the
25710 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 n-th parameter
25720 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 is.** nameless,
25730 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 then NULL is ret
25740 75 72 6e 65 64 2e 20 20 54 68 65 20 72 65 74 75 urned. The retu
25750 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a rned string is.*
25760 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d * always in UTF-
25770 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 8 encoding even
25780 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 if the named par
25790 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 ameter was.** or
257a0 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 iginally specifi
257b0 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 ed as UTF-16 in
257c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
257d0 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 16()] or.** [sql
257e0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
257f0 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 2()]..**.** See
25800 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 also: [sqlite3_b
25810 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 ind_blob|sqlite3
25820 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 _bind()],.** [sq
25830 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
25840 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 eter_count()], a
25850 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 nd.** [sqlite3_b
25860 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e ind_parameter_in
25870 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e dex()]..**.** IN
25880 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
25890 7b 48 31 33 36 32 31 7d 20 54 68 65 20 5b 73 71 {H13621} The [sq
258a0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
258b0 65 74 65 72 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 eter_name(S,N)]
258c0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
258d0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 s.** a
258e0 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 UTF-8 rendering
258f0 6f 66 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 of the name of t
25900 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 he SQL parameter
25910 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 in.**
25920 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
25930 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 76 69 6e atement] S havin
25940 67 20 69 6e 64 65 78 20 4e 2c 20 6f 72 0a 2a 2a g index N, or.**
25950 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 69 NULL i
25960 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 53 51 f there is no SQ
25970 4c 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 L parameter with
25980 20 69 6e 64 65 78 20 4e 20 6f 72 20 69 66 20 74 index N or if t
25990 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 he.** p
259a0 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 69 6e arameter with in
259b0 64 65 78 20 4e 20 69 73 20 61 6e 20 61 6e 6f 6e dex N is an anon
259c0 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 20 ymous parameter
259d0 22 3f 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 "?"..*/.const ch
259e0 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 ar *sqlite3_bind
259f0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 _parameter_name(
25a00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
25a10 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 nt);../*.** CAPI
25a20 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 3REF: Index Of A
25a30 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 Parameter With
25a40 41 20 47 69 76 65 6e 20 4e 61 6d 65 20 7b 48 31 A Given Name {H1
25a50 33 36 34 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 3640} <S70300>.*
25a60 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 *.** Return the
25a70 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 index of an SQL
25a80 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 parameter given
25a90 69 74 73 20 6e 61 6d 65 2e 20 20 54 68 65 0a 2a its name. The.*
25aa0 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 * index value re
25ab0 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 turned is suitab
25ac0 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 le for use as th
25ad0 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 e second.** para
25ae0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 meter to [sqlite
25af0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 3_bind_blob|sqli
25b00 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 41 20 te3_bind()]. A
25b10 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 zero.** is retur
25b20 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 ned if no matchi
25b30 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 ng parameter is
25b40 66 6f 75 6e 64 2e 20 20 54 68 65 20 70 61 72 61 found. The para
25b50 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 meter.** name mu
25b60 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 st be given in U
25b70 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 TF-8 even if the
25b80 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d original statem
25b90 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 ent.** was prepa
25ba0 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 red from UTF-16
25bb0 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 text using [sqli
25bc0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
25bd0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ()]..**.** See a
25be0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 lso: [sqlite3_bi
25bf0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f nd_blob|sqlite3_
25c00 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c bind()],.** [sql
25c10 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
25c20 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e ter_count()], an
25c30 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 d.** [sqlite3_bi
25c40 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 nd_parameter_ind
25c50 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 ex()]..**.** INV
25c60 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
25c70 48 31 33 36 34 31 7d 20 54 68 65 20 5b 73 71 6c H13641} The [sql
25c80 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
25c90 74 65 72 5f 69 6e 64 65 78 28 53 2c 4e 29 5d 20 ter_index(S,N)]
25ca0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
25cb0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 s.** th
25cc0 65 20 69 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 e index of SQL p
25cd0 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 arameter in the
25ce0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
25cf0 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 ent].**
25d00 20 53 20 77 68 6f 73 65 20 6e 61 6d 65 20 6d 61 S whose name ma
25d10 74 63 68 65 73 20 74 68 65 20 55 54 46 2d 38 20 tches the UTF-8
25d20 73 74 72 69 6e 67 20 4e 2c 20 6f 72 20 30 20 69 string N, or 0 i
25d30 66 20 74 68 65 72 65 20 69 73 0a 2a 2a 20 20 20 f there is.**
25d40 20 20 20 20 20 20 20 6e 6f 20 6d 61 74 63 68 2e no match.
25d50 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
25d60 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 bind_parameter_i
25d70 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d ndex(sqlite3_stm
25d80 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a t*, const char *
25d90 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 zName);../*.** C
25da0 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 API3REF: Reset A
25db0 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 ll Bindings On A
25dc0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d Prepared Statem
25dd0 65 6e 74 20 7b 48 31 33 36 36 30 7d 20 3c 53 37 ent {H13660} <S7
25de0 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 0300>.**.** Cont
25df0 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 rary to the intu
25e00 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b ition of many, [
25e10 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
25e20 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a does not reset.
25e30 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f ** the [sqlite3_
25e40 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 bind_blob | bind
25e50 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 ings] on a [prep
25e60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
25e70 0a 2a 2a 20 55 73 65 20 74 68 69 73 20 72 6f 75 .** Use this rou
25e80 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c tine to reset al
25e90 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 l host parameter
25ea0 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a s to NULL..**.**
25eb0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
25ec0 2a 2a 20 7b 48 31 33 36 36 31 7d 20 54 68 65 20 ** {H13661} The
25ed0 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 [sqlite3_clear_b
25ee0 69 6e 64 69 6e 67 73 28 53 29 5d 20 69 6e 74 65 indings(S)] inte
25ef0 72 66 61 63 65 20 72 65 73 65 74 73 20 61 6c 6c rface resets all
25f00 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 SQL.**
25f10 20 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 parameter bindi
25f20 6e 67 73 20 69 6e 20 74 68 65 20 5b 70 72 65 70 ngs in the [prep
25f30 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
25f40 53 20 62 61 63 6b 20 74 6f 20 4e 55 4c 4c 2e 0a S back to NULL..
25f50 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 */.int sqlite3_c
25f60 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 lear_bindings(sq
25f70 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f lite3_stmt*);../
25f80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e *.** CAPI3REF: N
25f90 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 umber Of Columns
25fa0 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 In A Result Set
25fb0 20 7b 48 31 33 37 31 30 7d 20 3c 53 31 30 37 30 {H13710} <S1070
25fc0 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 0>.**.** Return
25fd0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f the number of co
25fe0 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 lumns in the res
25ff0 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 ult set returned
26000 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 by the.** [prep
26010 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
26020 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 This routine re
26030 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 turns 0 if pStmt
26040 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 is an SQL.** st
26050 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 atement that doe
26060 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 s not return dat
26070 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 a (for example a
26080 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a n [UPDATE])..**.
26090 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
260a0 2a 0a 2a 2a 20 7b 48 31 33 37 31 31 7d 20 54 68 *.** {H13711} Th
260b0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d e [sqlite3_colum
260c0 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 n_count(S)] inte
260d0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 rface returns th
260e0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 e number of.**
260f0 20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 73 20 columns
26100 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 in the result se
26110 74 20 67 65 6e 65 72 61 74 65 64 20 62 79 20 74 t generated by t
26120 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
26130 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20 20 tement] S,.**
26140 20 20 20 20 20 20 20 6f 72 20 30 20 69 66 20 53 or 0 if S
26150 20 64 6f 65 73 20 6e 6f 74 20 67 65 6e 65 72 61 does not genera
26160 74 65 20 61 20 72 65 73 75 6c 74 20 73 65 74 2e te a result set.
26170 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
26180 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c column_count(sql
26190 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
261a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
261b0 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 EF: Column Names
261c0 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 In A Result Set
261d0 20 7b 48 31 33 37 32 30 7d 20 3c 53 31 30 37 30 {H13720} <S1070
261e0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 0>.**.** These r
261f0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 outines return t
26200 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 he name assigned
26210 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 to a particular
26220 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 column.** in th
26230 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 e result set of
26240 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 a [SELECT] state
26250 6d 65 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 ment. The sqlit
26260 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 e3_column_name()
26270 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 .** interface re
26280 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
26290 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e to a zero-termin
262a0 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e ated UTF-8 strin
262b0 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 g.** and sqlite3
262c0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 _column_name16()
262d0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
262e0 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 er to a zero-ter
262f0 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 minated.** UTF-1
26300 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 66 6 string. The f
26310 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 irst parameter i
26320 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 s the [prepared
26330 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 statement].** th
26340 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 at implements th
26350 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 e [SELECT] state
26360 6d 65 6e 74 2e 20 54 68 65 20 73 65 63 6f 6e 64 ment. The second
26370 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
26380 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 e.** column numb
26390 65 72 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 er. The leftmos
263a0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 t column is numb
263b0 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 er 0..**.** The
263c0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 returned string
263d0 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 pointer is valid
263e0 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 until either th
263f0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
26400 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 ement].** is des
26410 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 troyed by [sqlit
26420 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f e3_finalize()] o
26430 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 r until the next
26440 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 call to.** sqli
26450 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 te3_column_name(
26460 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c ) or sqlite3_col
26470 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 umn_name16() on
26480 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e the same column.
26490 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 .**.** If sqlite
264a0 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 3_malloc() fails
264b0 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 during the proc
264c0 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 essing of either
264d0 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 routine.** (for
264e0 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 example during
264f0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f a conversion fro
26500 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 m UTF-8 to UTF-1
26510 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 6) then a.** NUL
26520 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 L pointer is ret
26530 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 urned..**.** The
26540 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c name of a resul
26550 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 t column is the
26560 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 value of the "AS
26570 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 " clause for.**
26580 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 that column, if
26590 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 there is an AS c
265a0 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 lause. If there
265b0 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 is no AS clause
265c0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d .** then the nam
265d0 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 e of the column
265e0 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 is unspecified a
265f0 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 nd may change fr
26600 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 om.** one releas
26610 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 e of SQLite to t
26620 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 49 he next..**.** I
26630 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
26640 20 7b 48 31 33 37 32 31 7d 20 41 20 73 75 63 63 {H13721} A succ
26650 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f essful invocatio
26660 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 n of the [sqlite
26670 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 3_column_name(S,
26680 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 N)].**
26690 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
266a0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
266b0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 e Nth column (wh
266c0 65 72 65 20 30 20 69 73 0a 2a 2a 20 20 20 20 20 ere 0 is.**
266d0 20 20 20 20 20 74 68 65 20 6c 65 66 74 6d 6f 73 the leftmos
266e0 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68 t column) for th
266f0 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 e result set of
26700 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
26710 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
26720 65 6e 74 5d 20 53 20 61 73 20 61 20 7a 65 72 6f ent] S as a zero
26730 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d -terminated UTF-
26740 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 8 string..**.**
26750 7b 48 31 33 37 32 33 7d 20 41 20 73 75 63 63 65 {H13723} A succe
26760 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e ssful invocation
26770 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
26780 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 _column_name16(S
26790 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 ,N)].**
267a0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
267b0 6e 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 ns the name of t
267c0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 he Nth column (w
267d0 68 65 72 65 20 30 20 69 73 0a 2a 2a 20 20 20 20 here 0 is.**
267e0 20 20 20 20 20 20 74 68 65 20 6c 65 66 74 6d 6f the leftmo
267f0 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 st column) for t
26800 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 he result set of
26810 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
26820 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
26830 6d 65 6e 74 5d 20 53 20 61 73 20 61 20 7a 65 72 ment] S as a zer
26840 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 o-terminated UTF
26850 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 -16 string.**
26860 20 20 20 20 20 20 20 69 6e 20 74 68 65 20 6e 61 in the na
26870 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e tive byte order.
26880 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 34 7d 20 .**.** {H13724}
26890 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c The [sqlite3_col
268a0 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 umn_name()] and
268b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
268c0 6e 61 6d 65 31 36 28 29 5d 0a 2a 2a 20 20 20 20 name16()].**
268d0 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 interfaces
268e0 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 return a NULL p
268f0 6f 69 6e 74 65 72 20 69 66 20 74 68 65 79 20 61 ointer if they a
26900 72 65 20 75 6e 61 62 6c 65 20 74 6f 0a 2a 2a 20 re unable to.**
26910 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 allocat
26920 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 e memory to hold
26930 20 74 68 65 69 72 20 6e 6f 72 6d 61 6c 20 72 65 their normal re
26940 74 75 72 6e 20 73 74 72 69 6e 67 73 2e 0a 2a 2a turn strings..**
26950 0a 2a 2a 20 7b 48 31 33 37 32 35 7d 20 49 66 20 .** {H13725} If
26960 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 the N parameter
26970 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to [sqlite3_colu
26980 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 6f 72 mn_name(S,N)] or
26990 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
269a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
269b0 65 31 36 28 53 2c 4e 29 5d 20 69 73 20 6f 75 74 e16(S,N)] is out
269c0 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 6e 20 of range, then
269d0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
269e0 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 72 interfaces retur
269f0 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 n a NULL pointer
26a00 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 36 7d ..**.** {H13726}
26a10 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 The strings ret
26a20 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 urned by [sqlite
26a30 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 3_column_name(S,
26a40 4e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 N)] and.**
26a50 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c [sqlite3_col
26a60 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d umn_name16(S,N)]
26a70 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c are valid until
26a80 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 20 20 20 the next.**
26a90 20 20 20 20 20 20 63 61 6c 6c 20 74 6f 20 65 69 call to ei
26aa0 74 68 65 72 20 72 6f 75 74 69 6e 65 20 77 69 74 ther routine wit
26ab0 68 20 74 68 65 20 73 61 6d 65 20 53 20 61 6e 64 h the same S and
26ac0 20 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a N parameters.**
26ad0 20 20 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74 or unt
26ae0 69 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 il [sqlite3_fina
26af0 6c 69 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c lize(S)] is call
26b00 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 ed..**.** {H1372
26b10 37 7d 20 57 68 65 6e 20 61 20 72 65 73 75 6c 74 7} When a result
26b20 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 5b 53 45 column of a [SE
26b30 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 LECT] statement
26b40 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 contains.**
26b50 20 20 20 20 20 61 6e 20 41 53 20 63 6c 61 75 73 an AS claus
26b60 65 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 e, the name of t
26b70 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 hat column is th
26b80 65 20 69 64 65 6e 74 69 66 69 65 72 0a 2a 2a 20 e identifier.**
26b90 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 to the
26ba0 72 69 67 68 74 20 6f 66 20 74 68 65 20 41 53 20 right of the AS
26bb0 6b 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63 6f 6e 73 keyword..*/.cons
26bc0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
26bd0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 column_name(sqli
26be0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e te3_stmt*, int N
26bf0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
26c00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
26c10 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d me16(sqlite3_stm
26c20 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a t*, int N);../*.
26c30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 ** CAPI3REF: Sou
26c40 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 rce Of Data In A
26c50 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48 Query Result {H
26c60 31 33 37 34 30 7d 20 3c 53 31 30 37 30 30 3e 0a 13740} <S10700>.
26c70 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
26c80 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d ines provide a m
26c90 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e eans to determin
26ca0 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 e what column of
26cb0 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69 what.** table i
26cc0 6e 20 77 68 69 63 68 20 64 61 74 61 62 61 73 65 n which database
26cd0 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 20 5b a result of a [
26ce0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
26cf0 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a t comes from..**
26d00 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 The name of the
26d10 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 database or tab
26d20 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e le or column can
26d30 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a be returned as.
26d40 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d ** either a UTF-
26d50 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 8 or UTF-16 stri
26d60 6e 67 2e 20 20 54 68 65 20 5f 64 61 74 61 62 61 ng. The _databa
26d70 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 se_ routines ret
26d80 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 urn.** the datab
26d90 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 ase name, the _t
26da0 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 able_ routines r
26db0 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 eturn the table
26dc0 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 name, and.** the
26dd0 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 origin_ routine
26de0 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c s return the col
26df0 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 umn name..** The
26e00 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 returned string
26e10 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 is valid until
26e20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
26e30 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 atement] is dest
26e40 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b royed.** using [
26e50 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
26e60 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 ()] or until the
26e70 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f same informatio
26e80 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a n is requested.*
26e90 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 * again in a dif
26ea0 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e ferent encoding.
26eb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73 .**.** The names
26ec0 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 returned are th
26ed0 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c e original un-al
26ee0 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 iased names of t
26ef0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 he.** database,
26f00 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d table, and colum
26f10 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 n..**.** The fir
26f20 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 st argument to t
26f30 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c he following cal
26f40 6c 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 ls is a [prepare
26f50 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a d statement]..**
26f60 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 These functions
26f70 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 return informat
26f80 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 ion about the Nt
26f90 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 h column returne
26fa0 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 d by.** the stat
26fb0 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 ement, where N i
26fc0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e s the second fun
26fd0 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a ction argument..
26fe0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74 68 **.** If the Nth
26ff0 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 column returned
27000 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e by the statemen
27010 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 t is an expressi
27020 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 on or.** subquer
27030 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 y and is not a c
27040 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 olumn value, the
27050 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 n all of these f
27060 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a unctions return.
27070 2a 2a 20 4e 55 4c 4c 2e 20 20 54 68 65 73 65 20 ** NULL. These
27080 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c routine might al
27090 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 so return NULL i
270a0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 f a memory alloc
270b0 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f ation error.** o
270c0 63 63 75 72 73 2e 20 20 4f 74 68 65 72 77 69 73 ccurs. Otherwis
270d0 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 e, they return t
270e0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 he name of the a
270f0 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 ttached database
27100 2c 20 74 61 62 6c 65 0a 2a 2a 20 61 6e 64 20 63 , table.** and c
27110 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 olumn that query
27120 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 result column w
27130 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f as extracted fro
27140 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 68 m..**.** As with
27150 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 all other SQLit
27160 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 70 6f e APIs, those po
27170 73 74 66 69 78 65 64 20 77 69 74 68 20 22 31 36 stfixed with "16
27180 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d " return.** UTF-
27190 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 16 encoded strin
271a0 67 73 2c 20 74 68 65 20 6f 74 68 65 72 20 66 75 gs, the other fu
271b0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 nctions return U
271c0 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a TF-8. {END}.**.*
271d0 2a 20 54 68 65 73 65 20 41 50 49 73 20 61 72 65 * These APIs are
271e0 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 only available
271f0 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 if the library w
27200 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 as compiled with
27210 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
27220 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 ENABLE_COLUMN_ME
27230 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f TADATA] C-prepro
27240 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 cessor symbol de
27250 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 fined..**.** {A1
27260 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77 6f 20 3751}.** If two
27270 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 or more threads
27280 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 call one or more
27290 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e of these routin
272a0 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 es against the s
272b0 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 ame.** prepared
272c0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f statement and co
272d0 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 lumn at the same
272e0 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 time then the r
272f0 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e esults are.** un
27300 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 defined..**.** I
27310 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
27320 20 7b 48 31 33 37 34 31 7d 20 54 68 65 20 5b 73 {H13741} The [s
27330 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 qlite3_column_da
27340 74 61 62 61 73 65 5f 6e 61 6d 65 28 53 2c 4e 29 tabase_name(S,N)
27350 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ] interface retu
27360 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 rns either.**
27370 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 the UTF-8
27380 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
27390 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 name of the dat
273a0 61 62 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 abase from which
273b0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
273c0 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 Nth result colu
273d0 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 mn of the [prepa
273e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
273f0 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 0a 2a is extracted,.*
27400 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 * or NU
27410 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f LL if the Nth co
27420 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 lumn of S is a g
27430 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f eneral expressio
27440 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 n.** or
27450 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c if unable to al
27460 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f locate memory to
27470 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e store the name.
27480 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 32 7d 20 .**.** {H13742}
27490 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c The [sqlite3_col
274a0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d umn_database_nam
274b0 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 e16(S,N)] interf
274c0 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 ace returns eith
274d0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 er.** t
274e0 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 he UTF-16 native
274f0 20 62 79 74 65 20 6f 72 64 65 72 20 7a 65 72 6f byte order zero
27500 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 -terminated name
27510 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
27520 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f .** fro
27530 6d 20 77 68 69 63 68 20 74 68 65 20 4e 74 68 20 m which the Nth
27540 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 result column of
27550 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
27560 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 0a 2a tatement] S is.*
27570 2a 20 20 20 20 20 20 20 20 20 20 65 78 74 72 61 * extra
27580 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 cted, or NULL if
27590 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
275a0 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 of S is a genera
275b0 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 l expression.**
275c0 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 or if u
275d0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 nable to allocat
275e0 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 e memory to stor
275f0 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a e the name..**.*
27600 2a 20 7b 48 31 33 37 34 33 7d 20 54 68 65 20 5b * {H13743} The [
27610 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
27620 61 62 6c 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 able_name(S,N)]
27630 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
27640 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 s either.**
27650 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a the UTF-8 z
27660 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e ero-terminated n
27670 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 ame of the table
27680 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 0a from which the.
27690 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 ** Nth
276a0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 result column of
276b0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
276c0 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 tatement] S is e
276d0 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 xtracted,.**
276e0 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 or NULL if
276f0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
27700 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 of S is a genera
27710 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 l expression.**
27720 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 or if u
27730 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 nable to allocat
27740 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 e memory to stor
27750 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a e the name..**.*
27760 2a 20 7b 48 31 33 37 34 34 7d 20 54 68 65 20 5b * {H13744} The [
27770 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
27780 61 62 6c 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 able_name16(S,N)
27790 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ] interface retu
277a0 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 rns either.**
277b0 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 the UTF-1
277c0 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 6 native byte or
277d0 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 der zero-termina
277e0 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 ted name of the
277f0 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 table.**
27800 20 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 from which the
27810 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 Nth result colu
27820 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 mn of the [prepa
27830 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
27840 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 is.**
27850 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 extracted, or NU
27860 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f LL if the Nth co
27870 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 lumn of S is a g
27880 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f eneral expressio
27890 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 n.** or
278a0 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c if unable to al
278b0 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f locate memory to
278c0 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e store the name.
278d0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 35 7d 20 .**.** {H13745}
278e0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c The [sqlite3_col
278f0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 umn_origin_name(
27900 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 S,N)] interface
27910 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a returns either.*
27920 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 * the U
27930 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e TF-8 zero-termin
27940 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 ated name of the
27950 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 66 72 table column fr
27960 6f 6d 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 om which the.**
27970 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73 Nth res
27980 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 ult column of th
27990 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
279a0 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74 72 ement] S is extr
279b0 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 acted,.**
279c0 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 or NULL if th
279d0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 e Nth column of
279e0 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 S is a general e
279f0 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 xpression.**
27a00 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62 or if unab
27a10 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d le to allocate m
27a20 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74 emory to store t
27a30 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b he name..**.** {
27a40 48 31 33 37 34 36 7d 20 54 68 65 20 5b 73 71 6c H13746} The [sql
27a50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 ite3_column_orig
27a60 69 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 in_name16(S,N)]
27a70 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
27a80 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 s either.**
27a90 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20 the UTF-16
27aa0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
27ab0 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 r zero-terminate
27ac0 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 d name of the ta
27ad0 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ble.**
27ae0 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63 column from whic
27af0 68 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 h the Nth result
27b00 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a column of the.*
27b10 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 * [prep
27b20 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
27b30 53 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 20 S is extracted,
27b40 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e or NULL if the N
27b50 74 68 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20 th column.**
27b60 20 20 20 20 20 20 6f 66 20 53 20 69 73 20 61 20 of S is a
27b70 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 general expressi
27b80 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 on or if unable
27b90 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f to allocate memo
27ba0 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 ry.** t
27bb0 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 o store the name
27bc0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 38 7d ..**.** {H13748}
27bd0 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 The return valu
27be0 65 73 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 es from.**
27bf0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c [sqlite3_col
27c00 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d umn_database_nam
27c10 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 e | column metad
27c20 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a ata interfaces].
27c30 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20 ** are
27c40 76 61 6c 69 64 20 66 6f 72 20 74 68 65 20 6c 69 valid for the li
27c50 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20 5b 70 fetime of the [p
27c60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
27c70 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f t].** o
27c80 72 20 75 6e 74 69 6c 20 74 68 65 20 65 6e 63 6f r until the enco
27c90 64 69 6e 67 20 69 73 20 63 68 61 6e 67 65 64 20 ding is changed
27ca0 62 79 20 61 6e 6f 74 68 65 72 20 6d 65 74 61 64 by another metad
27cb0 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ata.**
27cc0 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 66 interface call f
27cd0 6f 72 20 74 68 65 20 73 61 6d 65 20 70 72 65 70 or the same prep
27ce0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 ared statement a
27cf0 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a nd column..**.**
27d00 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a ASSUMPTIONS:.**
27d10 0a 2a 2a 20 7b 41 31 33 37 35 31 7d 20 49 66 20 .** {A13751} If
27d20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 two or more thre
27d30 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 ads call one or
27d40 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 more.**
27d50 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
27d60 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c _database_name |
27d70 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 column metadata
27d80 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 interfaces].**
27d90 20 20 20 20 20 20 20 20 20 66 6f 72 20 74 68 65 for the
27da0 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 same [prepared
27db0 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 statement] and r
27dc0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 esult column.**
27dd0 20 20 20 20 20 20 20 20 20 61 74 20 74 68 65 20 at the
27de0 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 same time then t
27df0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 he results are u
27e00 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e ndefined..*/.con
27e10 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
27e20 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 _column_database
27e30 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 _name(sqlite3_st
27e40 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 mt*,int);.const
27e50 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
27e60 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 lumn_database_na
27e70 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d me16(sqlite3_stm
27e80 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 t*,int);.const c
27e90 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c har *sqlite3_col
27ea0 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 umn_table_name(s
27eb0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
27ec0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
27ed0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 qlite3_column_ta
27ee0 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 ble_name16(sqlit
27ef0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 e3_stmt*,int);.c
27f00 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
27f10 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e e3_column_origin
27f20 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 _name(sqlite3_st
27f30 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 mt*,int);.const
27f40 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
27f50 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 lumn_origin_name
27f60 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
27f70 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ,int);../*.** CA
27f80 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 PI3REF: Declared
27f90 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 Datatype Of A Q
27fa0 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31 33 uery Result {H13
27fb0 37 36 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 760} <S10700>.**
27fc0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 .** The first pa
27fd0 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 rameter is a [pr
27fe0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
27ff0 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 ]..** If this st
28000 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 atement is a [SE
28010 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 LECT] statement
28020 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 and the Nth colu
28030 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 mn of the.** ret
28040 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 urned result set
28050 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 of that [SELECT
28060 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c ] is a table col
28070 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 umn (not an.** e
28080 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 xpression or sub
28090 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 query) then the
280a0 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 declared type of
280b0 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f the table.** co
280c0 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 lumn is returned
280d0 2e 20 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f . If the Nth co
280e0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 lumn of the resu
280f0 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 lt set is an.**
28100 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 expression or su
28110 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e bquery, then a N
28120 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 ULL pointer is r
28130 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 eturned..** The
28140 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 returned string
28150 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 is always UTF-8
28160 65 6e 63 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a 2a encoded. {END}.*
28170 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 *.** For example
28180 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 , given the data
28190 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a base schema:.**.
281a0 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 ** CREATE TABLE
281b0 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a t1(c1 VARIANT);.
281c0 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f **.** and the fo
281d0 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e llowing statemen
281e0 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 t to be compiled
281f0 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 :.**.** SELECT c
28200 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 1 + 1, c1 FROM t
28210 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 1;.**.** this ro
28220 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 utine would retu
28230 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 rn the string "V
28240 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 ARIANT" for the
28250 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a second result.**
28260 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 column (i==1),
28270 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 and a NULL point
28280 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 er for the first
28290 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 result column (
282a0 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c i==0)..**.** SQL
282b0 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 ite uses dynamic
282c0 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 run-time typing
282d0 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75 . So just becau
282e0 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 se a column.** i
282f0 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f s declared to co
28300 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c ntain a particul
28310 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 ar type does not
28320 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a mean that the.*
28330 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e * data stored in
28340 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 that column is
28350 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 of the declared
28360 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 type. SQLite is
28370 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 .** strongly typ
28380 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 ed, but the typi
28390 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f ng is dynamic no
283a0 74 20 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a t static. Type.
283b0 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 ** is associated
283c0 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c with individual
283d0 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 values, not wit
283e0 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 h the containers
283f0 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 .** used to hold
28400 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a those values..*
28410 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
28420 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36 31 7d 20 .**.** {H13761}
28430 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 A successful ca
28440 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ll to [sqlite3_c
28450 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53 olumn_decltype(S
28460 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 0a 2a ,N)] returns a.*
28470 2a 20 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f * zero
28480 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d -terminated UTF-
28490 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 8 string contain
284a0 69 6e 67 20 74 68 65 20 64 65 63 6c 61 72 65 64 ing the declared
284b0 20 64 61 74 61 74 79 70 65 0a 2a 2a 20 20 20 20 datatype.**
284c0 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 74 61 of the ta
284d0 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 ble column that
284e0 61 70 70 65 61 72 73 20 61 73 20 74 68 65 20 4e appears as the N
284f0 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 th column (numbe
28500 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 red.**
28510 20 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 from 0) of the
28520 72 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68 result set to th
28530 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
28540 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 ement] S..**.**
28550 7b 48 31 33 37 36 32 7d 20 20 41 20 73 75 63 63 {H13762} A succ
28560 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b essful call to [
28570 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
28580 65 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d 0a ecltype16(S,N)].
28590 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74 ** ret
285a0 75 72 6e 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d urns a zero-term
285b0 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20 6e 61 inated UTF-16 na
285c0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 tive byte order
285d0 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 string.**
285e0 20 20 20 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 containing t
285f0 68 65 20 64 65 63 6c 61 72 65 64 20 64 61 74 61 he declared data
28600 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c type of the tabl
28610 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70 e column that ap
28620 70 65 61 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 pears.**
28630 20 20 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f as the Nth co
28640 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20 66 lumn (numbered f
28650 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65 rom 0) of the re
28660 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65 0a sult set to the.
28670 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70 72 ** [pr
28680 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
28690 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 ] S..**.** {H137
286a0 36 33 7d 20 20 49 66 20 4e 20 69 73 20 6c 65 73 63} If N is les
286b0 73 20 74 68 61 6e 20 30 20 6f 72 20 4e 20 69 73 s than 0 or N is
286c0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 6f 72 greater than or
286d0 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 20 20 20 equal to.**
286e0 20 20 20 20 20 20 20 74 68 65 20 6e 75 6d 62 65 the numbe
286f0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 r of columns in
28700 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
28710 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20 atement] S,.**
28720 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 74 or if t
28730 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 he Nth column of
28740 20 53 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 S is an express
28750 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 20 ion or subquery
28760 72 61 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 rather.**
28770 20 20 20 20 74 68 61 6e 20 61 20 74 61 62 6c 65 than a table
28780 20 63 6f 6c 75 6d 6e 2c 20 6f 72 20 69 66 20 61 column, or if a
28790 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
287a0 6f 6e 20 66 61 69 6c 75 72 65 0a 2a 2a 20 20 20 on failure.**
287b0 20 20 20 20 20 20 20 20 6f 63 63 75 72 73 20 64 occurs d
287c0 75 72 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20 63 uring encoding c
287d0 6f 6e 76 65 72 73 69 6f 6e 73 2c 20 74 68 65 6e onversions, then
287e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 61 .** ca
287f0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
28800 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 column_decltype(
28810 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 S,N)] or.**
28820 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 [sqlite3_c
28830 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 olumn_decltype16
28840 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e 20 4e 55 (S,N)] return NU
28850 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 LL..*/.const cha
28860 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d r *sqlite3_colum
28870 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 n_decltype(sqlit
28880 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 e3_stmt*,int);.c
28890 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
288a0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 e3_column_declty
288b0 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d pe16(sqlite3_stm
288c0 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 t*,int);../*.**
288d0 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 CAPI3REF: Evalua
288e0 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d te An SQL Statem
288f0 65 6e 74 20 7b 48 31 33 32 30 30 7d 20 3c 53 31 ent {H13200} <S1
28900 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 0000>.**.** Afte
28910 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 r a [prepared st
28920 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 atement] has bee
28930 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 n prepared using
28940 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 either.** [sqli
28950 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
28960 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 ] or [sqlite3_pr
28970 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 epare16_v2()] or
28980 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 one of the lega
28990 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 cy.** interfaces
289a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
289b0 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 e()] or [sqlite3
289c0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 _prepare16()], t
289d0 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 his function.**
289e0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f must be called o
289f0 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 ne or more times
28a00 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 to evaluate the
28a10 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a statement..**.*
28a20 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 * The details of
28a30 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 the behavior of
28a40 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 the sqlite3_ste
28a50 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 p() interface de
28a60 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 pend.** on wheth
28a70 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 er the statement
28a80 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 was prepared us
28a90 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 ing the newer "v
28aa0 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 2" interface.**
28ab0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
28ac0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 _v2()] and [sqli
28ad0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
28ae0 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 ()] or the older
28af0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 legacy.** inter
28b00 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 face [sqlite3_pr
28b10 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 epare()] and [sq
28b20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
28b30 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 )]. The use of
28b40 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 the.** new "v2"
28b50 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 interface is rec
28b60 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 ommended for new
28b70 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 applications bu
28b80 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 t the legacy.**
28b90 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 interface will c
28ba0 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 ontinue to be su
28bb0 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 pported..**.** I
28bc0 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 n the legacy int
28bd0 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 erface, the retu
28be0 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 rn value will be
28bf0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f either [SQLITE_
28c00 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 BUSY],.** [SQLIT
28c10 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 E_DONE], [SQLITE
28c20 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 _ROW], [SQLITE_E
28c30 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 RROR], or [SQLIT
28c40 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 E_MISUSE]..** Wi
28c50 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 th the "v2" inte
28c60 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 rface, any of th
28c70 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 e other [result
28c80 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 codes] or.** [ex
28c90 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
28ca0 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 des] might be re
28cb0 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a turned as well..
28cc0 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 **.** [SQLITE_BU
28cd0 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 SY] means that t
28ce0 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 he database engi
28cf0 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f ne was unable to
28d00 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 acquire the.**
28d10 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 database locks i
28d20 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 t needs to do it
28d30 73 20 6a 6f 62 2e 20 20 49 66 20 74 68 65 20 73 s job. If the s
28d40 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 tatement is a [C
28d50 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 OMMIT].** or occ
28d60 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 urs outside of a
28d70 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 n explicit trans
28d80 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 action, then you
28d90 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a can retry the.*
28da0 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 * statement. If
28db0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
28dc0 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d s not a [COMMIT]
28dd0 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 and occurs with
28de0 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 in a.** explicit
28df0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 transaction the
28e00 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c n you should rol
28e10 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 lback the transa
28e20 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 ction before.**
28e30 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a continuing..**.*
28e40 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 * [SQLITE_DONE]
28e50 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 means that the s
28e60 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e tatement has fin
28e70 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a ished executing.
28e80 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e ** successfully.
28e90 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 sqlite3_step()
28ea0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 should not be c
28eb0 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 alled again on t
28ec0 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d his virtual.** m
28ed0 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 achine without f
28ee0 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 irst calling [sq
28ef0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 lite3_reset()] t
28f00 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 o reset the virt
28f10 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 ual.** machine b
28f20 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 ack to its initi
28f30 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 al state..**.**
28f40 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 If the SQL state
28f50 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 ment being execu
28f60 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 ted returns any
28f70 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 data, then [SQLI
28f80 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 TE_ROW].** is re
28f90 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 turned each time
28fa0 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 a new row of da
28fb0 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 ta is ready for
28fc0 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 processing by th
28fd0 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 e.** caller. The
28fe0 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 values may be a
28ff0 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 ccessed using th
29000 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 e [column access
29010 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 functions]..**
29020 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 sqlite3_step() i
29030 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 s called again t
29040 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e o retrieve the n
29050 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e ext row of data.
29060 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 .**.** [SQLITE_E
29070 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 RROR] means that
29080 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f a run-time erro
29090 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e r (such as a con
290a0 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 straint.** viola
290b0 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 tion) has occurr
290c0 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 ed. sqlite3_ste
290d0 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 p() should not b
290e0 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f e called again o
290f0 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 n.** the VM. Mor
29100 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 e information ma
29110 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 y be found by ca
29120 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 lling [sqlite3_e
29130 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 rrmsg()]..** Wit
29140 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 h the legacy int
29150 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 erface, a more s
29160 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f pecific error co
29170 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c de (for example,
29180 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 .** [SQLITE_INTE
29190 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f RRUPT], [SQLITE_
291a0 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 SCHEMA], [SQLITE
291b0 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 _CORRUPT], and s
291c0 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 o forth).** can
291d0 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 be obtained by c
291e0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
291f0 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a reset()] on the.
29200 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
29210 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65 tement]. In the
29220 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c "v2" interface,
29230 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 .** the more spe
29240 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 cific error code
29250 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 is returned dir
29260 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 ectly by sqlite3
29270 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b _step()..**.** [
29280 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d SQLITE_MISUSE] m
29290 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 eans that the th
292a0 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 is routine was c
292b0 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 alled inappropri
292c0 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 ately..** Perhap
292d0 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 s it was called
292e0 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 on a [prepared s
292f0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 tatement] that h
29300 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 as.** already be
29310 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 en [sqlite3_fina
29320 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 lize | finalized
29330 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 ] or on one that
29340 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 had.** previous
29350 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c ly returned [SQL
29360 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 ITE_ERROR] or [S
29370 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 QLITE_DONE]. Or
29380 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 it could.** be
29390 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 the case that th
293a0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 e same database
293b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 connection is be
293c0 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 ing used by two
293d0 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 or.** more threa
293e0 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d ds at the same m
293f0 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a oment in time..*
29400 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e *.** <b>Goofy In
29410 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f terface Alert:</
29420 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 b> In the legacy
29430 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 interface, the
29440 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a sqlite3_step().*
29450 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 * API always ret
29460 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 urns a generic e
29470 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 rror code, [SQLI
29480 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f TE_ERROR], follo
29490 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f wing any.** erro
294a0 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 r other than [SQ
294b0 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b LITE_BUSY] and [
294c0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 SQLITE_MISUSE].
294d0 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a You must call.*
294e0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 * [sqlite3_reset
294f0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
29500 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f finalize()] in o
29510 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 rder to find one
29520 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 of the.** speci
29530 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 fic [error codes
29540 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 ] that better de
29550 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f scribes the erro
29560 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 r..** We admit t
29570 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f hat this is a go
29580 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 ofy design. The
29590 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 problem has bee
295a0 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 n fixed.** with
295b0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
295c0 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 ce. If you prep
295d0 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 are all of your
295e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a SQL statements.*
295f0 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b * using either [
29600 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
29610 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 v2()] or [sqlite
29620 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
29630 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 ] instead.** of
29640 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 the legacy [sqli
29650 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 te3_prepare()] a
29660 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 nd [sqlite3_prep
29670 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 are16()] interfa
29680 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ces,.** then the
29690 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b more specific [
296a0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 error codes] are
296b0 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 returned direct
296c0 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 ly.** by sqlite3
296d0 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 _step(). The us
296e0 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e e of the "v2" in
296f0 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d terface is recom
29700 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e mended..**.** IN
29710 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
29720 7b 48 31 33 32 30 32 7d 20 20 49 66 20 74 68 65 {H13202} If the
29730 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
29740 6d 65 6e 74 5d 20 53 20 69 73 20 72 65 61 64 79 ment] S is ready
29750 20 74 6f 20 62 65 20 72 75 6e 2c 20 74 68 65 6e to be run, then
29760 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 .** [s
29770 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 qlite3_step(S)]
29780 61 64 76 61 6e 63 65 73 20 74 68 61 74 20 70 72 advances that pr
29790 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
297a0 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 20 20 20 20 until.**
297b0 20 20 20 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f completion o
297c0 72 20 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65 r until it is re
297d0 61 64 79 20 74 6f 20 72 65 74 75 72 6e 20 61 6e ady to return an
297e0 6f 74 68 65 72 20 72 6f 77 20 6f 66 20 74 68 65 other row of the
297f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 .** re
29800 73 75 6c 74 20 73 65 74 2c 20 6f 72 20 75 6e 74 sult set, or unt
29810 69 6c 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 il an [sqlite3_i
29820 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 nterrupt | inter
29830 72 75 70 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 rupt].**
29840 20 20 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 or a run-time
29850 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a error occurs..*
29860 2a 0a 2a 2a 20 7b 48 31 35 33 30 34 7d 20 20 57 *.** {H15304} W
29870 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 hen a call to [s
29880 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 qlite3_step(S)]
29890 63 61 75 73 65 73 20 74 68 65 20 5b 70 72 65 70 causes the [prep
298a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a ared statement].
298b0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 53 20 74 ** S t
298c0 6f 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 o run to complet
298d0 69 6f 6e 2c 20 74 68 65 20 66 75 6e 63 74 69 6f ion, the functio
298e0 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 n returns [SQLIT
298f0 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b E_DONE]..**.** {
29900 48 31 35 33 30 36 7d 20 20 57 68 65 6e 20 61 20 H15306} When a
29910 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
29920 5f 73 74 65 70 28 53 29 5d 20 73 74 6f 70 73 20 _step(S)] stops
29930 62 65 63 61 75 73 65 20 69 74 20 69 73 20 72 65 because it is re
29940 61 64 79 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 ady to.**
29950 20 20 20 20 72 65 74 75 72 6e 20 61 6e 6f 74 68 return anoth
29960 65 72 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 er row of the re
29970 73 75 6c 74 20 73 65 74 2c 20 69 74 20 72 65 74 sult set, it ret
29980 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f 57 urns [SQLITE_ROW
29990 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 38 ]..**.** {H15308
299a0 7d 20 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 } If a call to
299b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
299c0 5d 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 6e 0a ] encounters an.
299d0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 ** [sq
299e0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 lite3_interrupt
299f0 7c 20 69 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 | interrupt] or
29a00 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 a run-time error
29a10 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 ,.** i
29a20 74 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 t returns an app
29a30 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 63 ropriate error c
29a40 6f 64 65 20 74 68 61 74 20 69 73 20 6e 6f 74 20 ode that is not
29a50 6f 6e 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 one of.**
29a60 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c [SQLITE_OK],
29a70 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 6f [SQLITE_ROW], o
29a80 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e r [SQLITE_DONE].
29a90 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 31 30 7d 20 .**.** {H15310}
29aa0 20 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f If an [sqlite3_
29ab0 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 interrupt | inte
29ac0 72 72 75 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d rrupt] or a run-
29ad0 74 69 6d 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 time error.**
29ae0 20 20 20 20 20 20 20 20 6f 63 63 75 72 73 20 64 occurs d
29af0 75 72 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 uring a call to
29b00 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
29b10 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 66 ].** f
29b20 6f 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 or a [prepared s
29b30 74 61 74 65 6d 65 6e 74 5d 20 53 20 63 72 65 61 tatement] S crea
29b40 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 ted using.**
29b50 20 20 20 20 20 20 20 6c 65 67 61 63 79 20 69 6e legacy in
29b60 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 terfaces [sqlite
29b70 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 3_prepare()] or.
29b80 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 ** [sq
29b90 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
29ba0 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 75 6e )], then the fun
29bb0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 65 69 ction returns ei
29bc0 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 ther.**
29bd0 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d [SQLITE_ERROR]
29be0 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c , [SQLITE_BUSY],
29bf0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 or [SQLITE_MISU
29c00 53 45 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 SE]..*/.int sqli
29c10 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 te3_step(sqlite3
29c20 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 _stmt*);../*.**
29c30 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 CAPI3REF: Number
29c40 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 of columns in a
29c50 20 72 65 73 75 6c 74 20 73 65 74 20 7b 48 31 33 result set {H13
29c60 37 37 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 770} <S10700>.**
29c70 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74 68 65 20 .** Returns the
29c80 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c 75 65 73 number of values
29c90 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 in the current
29ca0 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c row of the resul
29cb0 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 t set..**.** INV
29cc0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
29cd0 48 31 33 37 37 31 7d 20 20 41 66 74 65 72 20 61 H13771} After a
29ce0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
29cf0 33 5f 73 74 65 70 28 53 29 5d 20 74 68 61 74 20 3_step(S)] that
29d00 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
29d10 52 4f 57 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 ROW],.**
29d20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f the [sqlite3_
29d30 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 20 72 data_count(S)] r
29d40 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 outine will retu
29d50 72 6e 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 rn the same valu
29d60 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 e.** a
29d70 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 s the [sqlite3_c
29d80 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 olumn_count(S)]
29d90 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 function..**.**
29da0 7b 48 31 33 37 37 32 7d 20 20 41 66 74 65 72 20 {H13772} After
29db0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
29dc0 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 61 ] has returned a
29dd0 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 ny value other t
29de0 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 han.**
29df0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 [SQLITE_ROW] or
29e00 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 before [sqlite3
29e10 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 62 65 _step(S)] has be
29e20 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 en called on the
29e30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70 .** [p
29e40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
29e50 74 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 t] for the first
29e60 20 74 69 6d 65 20 73 69 6e 63 65 20 69 74 20 77 time since it w
29e70 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 as.**
29e80 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
29e90 20 7c 20 70 72 65 70 61 72 65 64 5d 20 6f 72 20 | prepared] or
29ea0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 20 7c [sqlite3_reset |
29eb0 20 72 65 73 65 74 5d 2c 0a 2a 2a 20 20 20 20 20 reset],.**
29ec0 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 the [sqlit
29ed0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 e3_data_count(S)
29ee0 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ] routine return
29ef0 73 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 s zero..*/.int s
29f00 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e qlite3_data_coun
29f10 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a t(sqlite3_stmt *
29f20 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 pStmt);../*.** C
29f30 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 API3REF: Fundame
29f40 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 20 7b ntal Datatypes {
29f50 48 31 30 32 36 35 7d 20 3c 53 31 30 31 31 30 3e H10265} <S10110>
29f60 3c 53 31 30 31 32 30 3e 0a 2a 2a 20 4b 45 59 57 <S10120>.** KEYW
29f70 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 ORDS: SQLITE_TEX
29f80 54 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 36 36 7d T.**.** {H10266}
29f90 20 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 Every value in
29fa0 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f SQLite has one o
29fb0 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 f five fundament
29fc0 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a al datatypes:.**
29fd0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
29fe0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 64-bit signed i
29ff0 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 nteger.** <li> 6
2a000 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 4-bit IEEE float
2a010 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 ing point number
2a020 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a .** <li> string.
2a030 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 ** <li> BLOB.**
2a040 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 <li> NULL.** </u
2a050 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 l> {END}.**.** T
2a060 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 hese constants a
2a070 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 re codes for eac
2a080 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 h of those types
2a090 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ..**.** Note tha
2a0a0 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 t the SQLITE_TEX
2a0b0 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 T constant was a
2a0c0 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 lso used in SQLi
2a0d0 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 te version 2.**
2a0e0 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 for a completely
2a0f0 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 different meani
2a100 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 ng. Software th
2a110 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 at links against
2a120 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 both.** SQLite
2a130 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 version 2 and SQ
2a140 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 Lite version 3 s
2a150 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 hould use SQLITE
2a160 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 3_TEXT, not.** S
2a170 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 QLITE_TEXT..*/.#
2a180 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e define SQLITE_IN
2a190 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 TEGER 1.#define
2a1a0 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 SQLITE_FLOAT
2a1b0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
2a1c0 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 E_BLOB 4.#de
2a1d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c fine SQLITE_NULL
2a1e0 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 5.#ifdef SQ
2a1f0 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 LITE_TEXT.# unde
2a200 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 f SQLITE_TEXT.#e
2a210 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c lse.# define SQL
2a220 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 ITE_TEXT 3.#
2a230 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 endif.#define SQ
2a240 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 LITE3_TEXT 3
2a250 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2a260 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 : Result Values
2a270 46 72 6f 6d 20 41 20 51 75 65 72 79 20 7b 48 31 From A Query {H1
2a280 33 38 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 3800} <S10700>.*
2a290 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c * KEYWORDS: {col
2a2a0 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 umn access funct
2a2b0 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ions}.**.** Thes
2a2c0 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 e routines form
2a2d0 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 20 the "result set
2a2e0 71 75 65 72 79 22 20 69 6e 74 65 72 66 61 63 65 query" interface
2a2f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f ..**.** These ro
2a300 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e utines return in
2a310 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 formation about
2a320 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 a single column
2a330 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a of the current.*
2a340 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 * result row of
2a350 61 20 71 75 65 72 79 2e 20 20 49 6e 20 65 76 65 a query. In eve
2a360 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 ry case the firs
2a370 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 t argument is a
2a380 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 pointer.** to th
2a390 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
2a3a0 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 ement] that is b
2a3b0 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 eing evaluated (
2a3c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d the [sqlite3_stm
2a3d0 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 t*].** that was
2a3e0 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 returned from [s
2a3f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
2a400 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 2()] or one of i
2a410 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 ts variants).**
2a420 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 and the second a
2a430 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 rgument is the i
2a440 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 ndex of the colu
2a450 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 mn for which inf
2a460 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 ormation.** shou
2a470 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 ld be returned.
2a480 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f The leftmost co
2a490 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 lumn of the resu
2a4a0 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 lt set has the i
2a4b0 6e 64 65 78 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 ndex 0..**.** If
2a4c0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
2a4d0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 nt does not curr
2a4e0 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 ently point to a
2a4f0 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 valid row, or i
2a500 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 f the.** column
2a510 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 index is out of
2a520 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c range, the resul
2a530 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a t is undefined..
2a540 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
2a550 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 s may only be ca
2a560 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f lled when the mo
2a570 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 st recent call t
2a580 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 o.** [sqlite3_st
2a590 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e ep()] has return
2a5a0 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 ed [SQLITE_ROW]
2a5b0 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b and neither.** [
2a5c0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
2a5d0 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 nor [sqlite3_fi
2a5e0 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 nalize()] have b
2a5f0 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 een called subse
2a600 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 quently..** If a
2a610 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 ny of these rout
2a620 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 ines are called
2a630 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 after [sqlite3_r
2a640 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 eset()] or.** [s
2a650 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2a660 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c )] or after [sql
2a670 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 ite3_step()] has
2a680 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d returned.** som
2a690 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 ething other tha
2a6a0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 n [SQLITE_ROW],
2a6b0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 the results are
2a6c0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 undefined..** If
2a6d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
2a6e0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 ] or [sqlite3_re
2a6f0 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 set()] or [sqlit
2a700 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a e3_finalize()].*
2a710 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f * are called fro
2a720 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 m a different th
2a730 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f read while any o
2a740 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
2a750 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c .** are pending,
2a760 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 then the result
2a770 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e s are undefined.
2a780 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
2a790 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 e3_column_type()
2a7a0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
2a7b0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
2a7c0 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 INTEGER | dataty
2a7d0 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 pe code] for the
2a7e0 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 initial data ty
2a7f0 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 pe.** of the res
2a800 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 ult column. The
2a810 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 returned value
2a820 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 is one of [SQLIT
2a830 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b E_INTEGER],.** [
2a840 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b SQLITE_FLOAT], [
2a850 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 SQLITE_TEXT], [S
2a860 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 QLITE_BLOB], or
2a870 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 [SQLITE_NULL].
2a880 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 The value.** ret
2a890 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
2a8a0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 _column_type() i
2a8b0 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 s only meaningfu
2a8c0 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 l if no type.**
2a8d0 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 conversions have
2a8e0 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73 occurred as des
2a8f0 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 cribed below. A
2a900 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 fter a type conv
2a910 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 ersion,.** the v
2a920 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 alue returned by
2a930 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2a940 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 type() is undefi
2a950 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 ned. Future.**
2a960 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
2a970 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 te may change th
2a980 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 e behavior of sq
2a990 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 lite3_column_typ
2a9a0 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 e().** following
2a9b0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 a type conversi
2a9c0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 on..**.** If the
2a9d0 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f result is a BLO
2a9e0 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e B or UTF-8 strin
2a9f0 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 g then the sqlit
2aa00 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
2aa10 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 ).** routine ret
2aa20 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
2aa30 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 of bytes in that
2aa40 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e BLOB or string.
2aa50 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c .** If the resul
2aa60 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 t is a UTF-16 st
2aa70 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 ring, then sqlit
2aa80 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
2aa90 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 ) converts.** th
2aaa0 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d e string to UTF-
2aab0 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 8 and then retur
2aac0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
2aad0 20 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 bytes..** If th
2aae0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 e result is a nu
2aaf0 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e meric value then
2ab00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2ab10 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 bytes() uses.**
2ab20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 [sqlite3_snprint
2ab30 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 f()] to convert
2ab40 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 that value to a
2ab50 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 UTF-8 string and
2ab60 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 returns.** the
2ab70 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
2ab80 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a in that string..
2ab90 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 ** The value ret
2aba0 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 urned does not i
2abb0 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 nclude the zero
2abc0 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 terminator at th
2abd0 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 e end.** of the
2abe0 73 74 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 string. For cla
2abf0 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20 rity: the value
2ac00 72 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 returned is the
2ac10 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 number of.** byt
2ac20 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 es in the string
2ac30 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 , not the number
2ac40 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a of characters..
2ac50 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 20 72 65 **.** Strings re
2ac60 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 turned by sqlite
2ac70 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 3_column_text()
2ac80 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 and sqlite3_colu
2ac90 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 mn_text16(),.**
2aca0 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e even empty strin
2acb0 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a gs, are always z
2acc0 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 ero terminated.
2acd0 20 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 The return.** v
2ace0 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 alue from sqlite
2acf0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 3_column_blob()
2ad00 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 for a zero-lengt
2ad10 68 20 42 4c 4f 42 20 69 73 20 61 6e 20 61 72 62 h BLOB is an arb
2ad20 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 itrary.** pointe
2ad30 72 2c 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e r, possibly even
2ad40 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
2ad50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
2ad60 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
2ad70 36 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 6() routine is s
2ad80 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 imilar to sqlite
2ad90 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
2ada0 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74 .** but leaves t
2adb0 68 65 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46 he result in UTF
2adc0 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 -16 in native by
2add0 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 te order instead
2ade0 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 54 68 of UTF-8..** Th
2adf0 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f e zero terminato
2ae00 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 r is not include
2ae10 64 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e d in this count.
2ae20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a 65 63 .**.** The objec
2ae30 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 t returned by [s
2ae40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 qlite3_column_va
2ae50 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 lue()] is an.**
2ae60 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c [unprotected sql
2ae70 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
2ae80 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 ct. An unprotec
2ae90 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
2aea0 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 e object.** may
2aeb0 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 only be used wit
2aec0 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f h [sqlite3_bind_
2aed0 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 value()] and [sq
2aee0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c lite3_result_val
2aef0 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 ue()]..** If the
2af00 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 [unprotected sq
2af10 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
2af20 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a ect returned by.
2af30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ** [sqlite3_colu
2af40 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 mn_value()] is u
2af50 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 sed in any other
2af60 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 way, including
2af70 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 calls.** to rout
2af80 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 ines like [sqlit
2af90 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c e3_value_int()],
2afa0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
2afb0 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b text()],.** or [
2afc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 sqlite3_value_by
2afd0 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 tes()], then the
2afe0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 behavior is und
2aff0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 efined..**.** Th
2b000 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 ese routines att
2b010 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 empt to convert
2b020 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 the value where
2b030 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 46 6f appropriate. Fo
2b040 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 r.** example, if
2b050 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 the internal re
2b060 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 presentation is
2b070 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 FLOAT and a text
2b080 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 result.** is re
2b090 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 quested, [sqlite
2b0a0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 3_snprintf()] is
2b0b0 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 used internally
2b0c0 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a to perform the.
2b0d0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 ** conversion au
2b0e0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 tomatically. Th
2b0f0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c e following tabl
2b100 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f e details the co
2b110 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 nversions.** tha
2b120 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a t are applied:.*
2b130 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
2b140 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 >.** <table bord
2b150 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c er="1">.** <tr><
2b160 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e th> Internal<br>
2b170 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 Type <th> Reques
2b180 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e ted<br>Type <th>
2b190 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a Conversion.**.
2b1a0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c ** <tr><td> NUL
2b1b0 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 L <td> INTEGE
2b1c0 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 R <td> Result
2b1d0 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e is 0.** <tr><td>
2b1e0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 NULL <td>
2b1f0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 FLOAT <td> Re
2b200 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c sult is 0.0.** <
2b210 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 tr><td> NULL
2b220 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 <td> TEXT
2b230 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e <td> Result is N
2b240 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c ULL pointer.** <
2b250 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 tr><td> NULL
2b260 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 <td> BLOB
2b270 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e <td> Result is N
2b280 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c ULL pointer.** <
2b290 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 tr><td> INTEGER
2b2a0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 <td> FLOAT
2b2b0 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f <td> Convert fro
2b2c0 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f m integer to flo
2b2d0 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 at.** <tr><td> I
2b2e0 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 NTEGER <td> T
2b2f0 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 EXT <td> ASCI
2b300 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 I rendering of t
2b310 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 he integer.** <t
2b320 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 r><td> INTEGER
2b330 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c <td> BLOB <
2b340 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 td> Same as INTE
2b350 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 GER->TEXT.** <tr
2b360 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c ><td> FLOAT <
2b370 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 td> INTEGER <t
2b380 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 d> Convert from
2b390 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 float to integer
2b3a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c .** <tr><td> FL
2b3b0 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 OAT <td> TEX
2b3c0 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 T <td> ASCII
2b3d0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 rendering of the
2b3e0 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 float.** <tr><t
2b3f0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e d> FLOAT <td>
2b400 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 BLOB <td>
2b410 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 Same as FLOAT->T
2b420 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 EXT.** <tr><td>
2b430 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e TEXT <td> IN
2b440 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 TEGER <td> Use
2b450 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c atoi().** <tr><
2b460 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 td> TEXT <td
2b470 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e > FLOAT <td>
2b480 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c Use atof().** <
2b490 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 tr><td> TEXT
2b4a0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 <td> BLOB
2b4b0 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a <td> No change.*
2b4c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 * <tr><td> BLOB
2b4d0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 <td> INTEGER
2b4e0 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 <td> Convert
2b4f0 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 to TEXT then use
2b500 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c atoi().** <tr><
2b510 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 td> BLOB <td
2b520 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e > FLOAT <td>
2b530 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 Convert to TEXT
2b540 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 then use atof()
2b550 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c .** <tr><td> BL
2b560 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 OB <td> TEX
2b570 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 T <td> Add a
2b580 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 zero terminator
2b590 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 if needed.** </t
2b5a0 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b able>.** </block
2b5b0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 quote>.**.** The
2b5c0 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b table above mak
2b5d0 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 es reference to
2b5e0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 standard C libra
2b5f0 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f ry functions ato
2b600 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 i().** and atof(
2b610 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 ). SQLite does
2b620 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 not really use t
2b630 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 hese functions.
2b640 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f It has its.** o
2b650 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e wn equivalent in
2b660 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e ternal routines.
2b670 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 The atoi() and
2b680 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 atof() names ar
2b690 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 e.** used in the
2b6a0 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 table for brevi
2b6b0 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 ty and because t
2b6c0 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 hey are familiar
2b6d0 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 to most.** C pr
2b6e0 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a ogrammers..**.**
2b6f0 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 Note that when
2b700 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 type conversions
2b710 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 occur, pointers
2b720 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 returned by pri
2b730 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 or.** calls to s
2b740 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
2b750 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f ob(), sqlite3_co
2b760 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 lumn_text(), and
2b770 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 /or.** sqlite3_c
2b780 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d olumn_text16() m
2b790 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 ay be invalidate
2b7a0 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 d..** Type conve
2b7b0 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 rsions and point
2b7c0 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 er invalidations
2b7d0 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 might occur.**
2b7e0 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 in the following
2b7f0 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 cases:.**.** <u
2b800 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 l>.** <li> The i
2b810 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 nitial content i
2b820 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c s a BLOB and sql
2b830 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
2b840 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 () or.** sq
2b850 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
2b860 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e t16() is called.
2b870 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 A zero-termina
2b880 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 tor might.**
2b890 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 need to be add
2b8a0 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 ed to the string
2b8b0 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 .</li>.** <li> T
2b8c0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 he initial conte
2b8d0 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 nt is UTF-8 text
2b8e0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
2b8f0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 umn_bytes16() or
2b900 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 .** sqlite3
2b910 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
2b920 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 is called. The
2b930 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 content must be
2b940 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 converted.**
2b950 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c to UTF-16.</l
2b960 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 i>.** <li> The i
2b970 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 nitial content i
2b980 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e s UTF-16 text an
2b990 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e d sqlite3_column
2b9a0 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 _bytes() or.**
2b9b0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 sqlite3_colu
2b9c0 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c mn_text() is cal
2b9d0 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e led. The conten
2b9e0 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 t must be conver
2b9f0 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 ted.** to U
2ba00 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f TF-8.</li>.** </
2ba10 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 ul>.**.** Conver
2ba20 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 sions between UT
2ba30 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 F-16be and UTF-1
2ba40 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6le are always d
2ba50 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 one in place and
2ba60 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c do.** not inval
2ba70 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f idate a prior po
2ba80 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 inter, though of
2ba90 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 course the cont
2baa0 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 ent of the buffe
2bab0 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 r.** that the pr
2bac0 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e ior pointer poin
2bad0 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 ts to will have
2bae0 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 been modified.
2baf0 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f Other kinds.** o
2bb00 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 f conversion are
2bb10 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 done in place w
2bb20 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 hen it is possib
2bb30 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 le, but sometime
2bb40 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f s they.** are no
2bb50 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 t possible and i
2bb60 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 n those cases pr
2bb70 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 ior pointers are
2bb80 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a invalidated..**
2bb90 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 .** The safest a
2bba0 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 nd easiest to re
2bbb0 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 member policy is
2bbc0 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 to invoke these
2bbd0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 routines.** in
2bbe0 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f one of the follo
2bbf0 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a wing ways:.**.**
2bc00 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 <ul>.** <li>sq
2bc10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
2bc20 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 t() followed by
2bc30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2bc40 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 ytes()</li>.**
2bc50 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 <li>sqlite3_colu
2bc60 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 mn_blob() follow
2bc70 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f ed by sqlite3_co
2bc80 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 lumn_bytes()</li
2bc90 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 >.** <li>sqlite
2bca0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
2bcb0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 ) followed by sq
2bcc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2bcd0 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c es16()</li>.** <
2bce0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 /ul>.**.** In ot
2bcf0 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 her words, you s
2bd00 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 hould call sqlit
2bd10 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
2bd20 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c ,.** sqlite3_col
2bd30 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 umn_blob(), or s
2bd40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
2bd50 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 xt16() first to
2bd60 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 force the result
2bd70 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 .** into the des
2bd80 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 ired format, the
2bd90 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 n invoke sqlite3
2bda0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 _column_bytes()
2bdb0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f or.** sqlite3_co
2bdc0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 lumn_bytes16() t
2bdd0 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 o find the size
2bde0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 of the result.
2bdf0 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 Do not mix calls
2be00 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 .** to sqlite3_c
2be10 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 olumn_text() or
2be20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2be30 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 lob() with calls
2be40 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 to.** sqlite3_c
2be50 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c olumn_bytes16(),
2be60 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 and do not mix
2be70 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
2be80 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
2be90 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 .** with calls t
2bea0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e o sqlite3_column
2beb0 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 _bytes()..**.**
2bec0 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 The pointers ret
2bed0 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 urned are valid
2bee0 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e until a type con
2bef0 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 version occurs a
2bf00 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 s.** described a
2bf10 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b bove, or until [
2bf20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
2bf30 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 or [sqlite3_rese
2bf40 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 t()] or.** [sqli
2bf50 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
2bf60 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 is called. The
2bf70 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 memory space use
2bf80 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 d to hold string
2bf90 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 s.** and BLOBs i
2bfa0 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 s freed automati
2bfb0 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f cally. Do <b>no
2bfc0 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 t</b> pass the p
2bfd0 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 ointers returned
2bfe0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c .** [sqlite3_col
2bff0 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 umn_blob()], [sq
2c000 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
2c010 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a t()], etc. into.
2c020 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ** [sqlite3_free
2c030 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 ()]..**.** If a
2c040 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
2c050 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 n error occurs d
2c060 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 uring the evalua
2c070 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f tion of any.** o
2c080 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
2c090 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 , a default valu
2c0a0 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 e is returned.
2c0b0 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 The default valu
2c0c0 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 e.** is either t
2c0d0 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 he integer 0, th
2c0e0 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 e floating point
2c0f0 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 number 0.0, or
2c100 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 a NULL.** pointe
2c110 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 r. Subsequent c
2c120 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
2c130 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c _errcode()] will
2c140 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 return.** [SQLI
2c150 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a TE_NOMEM]..**.**
2c160 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
2c170 2a 2a 20 7b 48 31 33 38 30 33 7d 20 54 68 65 20 ** {H13803} The
2c180 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
2c190 62 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e 74 65 72 blob(S,N)] inter
2c1a0 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 face converts th
2c1b0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 e.** Nt
2c1c0 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 h column in the
2c1d0 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 current row of t
2c1e0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f he result set fo
2c1f0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 r.** th
2c200 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
2c210 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 ement] S into a
2c220 42 4c 4f 42 20 61 6e 64 20 74 68 65 6e 20 72 65 BLOB and then re
2c230 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 turns a.**
2c240 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 pointer to t
2c250 68 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c he converted val
2c260 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30 ue..**.** {H1380
2c270 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6} The [sqlite3_
2c280 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 53 2c 4e column_bytes(S,N
2c290 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
2c2a0 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 urns the.**
2c2b0 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 number of b
2c2c0 79 74 65 73 20 69 6e 20 74 68 65 20 42 4c 4f 42 ytes in the BLOB
2c2d0 20 6f 72 20 73 74 72 69 6e 67 20 28 65 78 63 6c or string (excl
2c2e0 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 usive of the.**
2c2f0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 zero te
2c300 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 rminator on the
2c310 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 string) that was
2c320 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 returned by the
2c330 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 .** mos
2c340 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f t recent call to
2c350 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
2c360 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f 72 0a 2a _blob(S,N)] or.*
2c370 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
2c380 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
2c390 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 S,N)]..**.** {H1
2c3a0 33 38 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 3809} The [sqlit
2c3b0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
2c3c0 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 6(S,N)] interfac
2c3d0 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a e returns the.**
2c3e0 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 number
2c3f0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 of bytes in the
2c400 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 string (exclusi
2c410 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 ve of the.**
2c420 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 zero termi
2c430 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 nator on the str
2c440 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65 ing) that was re
2c450 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a turned by the.**
2c460 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 most r
2c470 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 ecent call to [s
2c480 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
2c490 78 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a xt16(S,N)]..**.*
2c4a0 2a 20 7b 48 31 33 38 31 32 7d 20 54 68 65 20 5b * {H13812} The [
2c4b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
2c4c0 6f 75 62 6c 65 28 53 2c 4e 29 5d 20 69 6e 74 65 ouble(S,N)] inte
2c4d0 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 rface converts t
2c4e0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e he.** N
2c4f0 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 th column in the
2c500 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 current row of
2c510 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 the result set f
2c520 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 or the.**
2c530 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 [prepared sta
2c540 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 tement] S into a
2c550 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 floating point
2c560 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 value and.**
2c570 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 returns a
2c580 63 6f 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c copy of that val
2c590 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 31 ue..**.** {H1381
2c5a0 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 5} The [sqlite3_
2c5b0 63 6f 6c 75 6d 6e 5f 69 6e 74 28 53 2c 4e 29 5d column_int(S,N)]
2c5c0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 interface conve
2c5d0 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 rts the.**
2c5e0 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 Nth column i
2c5f0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f n the current ro
2c600 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 w of the result
2c610 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 set for the.**
2c620 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 [prepare
2c630 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 d statement] S i
2c640 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 nto a 64-bit sig
2c650 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a ned integer and.
2c660 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 ** retu
2c670 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 20 33 32 rns the lower 32
2c680 20 62 69 74 73 20 6f 66 20 74 68 61 74 20 69 6e bits of that in
2c690 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 teger..**.** {H1
2c6a0 33 38 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 3818} The [sqlit
2c6b0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 e3_column_int64(
2c6c0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 S,N)] interface
2c6d0 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 converts the.**
2c6e0 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c Nth col
2c6f0 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 umn in the curre
2c700 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 nt row of the re
2c710 73 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65 sult set for the
2c720 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 .** [pr
2c730 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2c740 5d 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 ] S into a 64-bi
2c750 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 t signed integer
2c760 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 and.**
2c770 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 returns a copy
2c780 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e of that integer.
2c790 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 31 7d 20 .**.** {H13821}
2c7a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c The [sqlite3_col
2c7b0 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 20 69 umn_text(S,N)] i
2c7c0 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 nterface convert
2c7d0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 s the.**
2c7e0 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 Nth column in
2c7f0 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 the current row
2c800 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 of the result se
2c810 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 t for.**
2c820 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 the [prepared
2c830 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 statement] S int
2c840 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 o a zero-termina
2c850 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 ted UTF-8.**
2c860 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 string and
2c870 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
2c880 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e er to that strin
2c890 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 34 g..**.** {H13824
2c8a0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 } The [sqlite3_c
2c8b0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e olumn_text16(S,N
2c8c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e )] interface con
2c8d0 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 verts the.**
2c8e0 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e Nth column
2c8f0 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 in the current
2c900 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c row of the resul
2c910 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a t set for the.**
2c920 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 [prepa
2c930 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
2c940 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 into a zero-ter
2c950 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a minated 2-byte.*
2c960 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e * align
2c970 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 ed UTF-16 native
2c980 20 62 79 74 65 20 6f 72 64 65 72 20 73 74 72 69 byte order stri
2c990 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a ng and returns.*
2c9a0 2a 20 20 20 20 20 20 20 20 20 20 61 20 70 6f 69 * a poi
2c9b0 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 nter to that str
2c9c0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 ing..**.** {H138
2c9d0 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 27} The [sqlite3
2c9e0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 53 2c 4e _column_type(S,N
2c9f0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
2ca00 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 urns.**
2ca10 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f one of [SQLITE_
2ca20 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 NULL], [SQLITE_I
2ca30 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 NTEGER], [SQLITE
2ca40 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 _FLOAT],.**
2ca50 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 [SQLITE_TEX
2ca60 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 T], or [SQLITE_B
2ca70 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 LOB] as appropri
2ca80 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 ate for.**
2ca90 20 20 20 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 the Nth colu
2caa0 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e mn in the curren
2cab0 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 t row of the res
2cac0 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 ult set for.**
2cad0 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 the [pre
2cae0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2caf0 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 33 S..**.** {H1383
2cb00 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 0} The [sqlite3_
2cb10 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 53 2c 4e column_value(S,N
2cb20 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
2cb30 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 urns a.**
2cb40 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e pointer to an
2cb50 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 [unprotected sq
2cb60 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
2cb70 65 63 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 ect for the.**
2cb80 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 Nth colu
2cb90 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e mn in the curren
2cba0 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 t row of the res
2cbb0 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 ult set for.**
2cbc0 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 the [pre
2cbd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2cbe0 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 S..*/.const voi
2cbf0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
2cc00 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 n_blob(sqlite3_s
2cc10 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
2cc20 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c .int sqlite3_col
2cc30 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 umn_bytes(sqlite
2cc40 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
2cc50 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f l);.int sqlite3_
2cc60 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 column_bytes16(s
2cc70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
2cc80 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 t iCol);.double
2cc90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
2cca0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 ouble(sqlite3_st
2ccb0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
2ccc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 int sqlite3_colu
2ccd0 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 mn_int(sqlite3_s
2cce0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
2ccf0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 .sqlite3_int64 s
2cd00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e qlite3_column_in
2cd10 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 t64(sqlite3_stmt
2cd20 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f *, int iCol);.co
2cd30 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 nst unsigned cha
2cd40 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d r *sqlite3_colum
2cd50 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 n_text(sqlite3_s
2cd60 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
2cd70 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
2cd80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
2cd90 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
2cda0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 , int iCol);.int
2cdb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2cdc0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d type(sqlite3_stm
2cdd0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 t*, int iCol);.s
2cde0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 qlite3_value *sq
2cdf0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c lite3_column_val
2ce00 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ue(sqlite3_stmt*
2ce10 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a , int iCol);../*
2ce20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
2ce30 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 stroy A Prepared
2ce40 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 Statement Objec
2ce50 74 20 7b 48 31 33 33 30 30 7d 20 3c 53 37 30 33 t {H13300} <S703
2ce60 30 30 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 00><S30100>.**.*
2ce70 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 * The sqlite3_fi
2ce80 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f nalize() functio
2ce90 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 n is called to d
2cea0 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 elete a [prepare
2ceb0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a d statement]..**
2cec0 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e If the statemen
2ced0 74 20 77 61 73 20 65 78 65 63 75 74 65 64 20 73 t was executed s
2cee0 75 63 63 65 73 73 66 75 6c 6c 79 20 6f 72 20 6e uccessfully or n
2cef0 6f 74 20 65 78 65 63 75 74 65 64 20 61 74 20 61 ot executed at a
2cf00 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 49 ll, then.** SQLI
2cf10 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 TE_OK is returne
2cf20 64 2e 20 49 66 20 65 78 65 63 75 74 69 6f 6e 20 d. If execution
2cf30 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 of the statement
2cf40 20 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 0a failed then an.
2cf50 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 ** [error code]
2cf60 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 or [extended err
2cf70 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 or code] is retu
2cf80 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 rned..**.** This
2cf90 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 routine can be
2cfa0 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f called at any po
2cfb0 69 6e 74 20 64 75 72 69 6e 67 20 74 68 65 20 65 int during the e
2cfc0 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a xecution of the.
2cfd0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
2cfe0 74 65 6d 65 6e 74 5d 2e 20 20 49 66 20 74 68 65 tement]. If the
2cff0 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 virtual machine
2d000 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 has not.** comp
2d010 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20 leted execution
2d020 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e when this routin
2d030 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 e is called, tha
2d040 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 t is like.** enc
2d050 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72 ountering an err
2d060 6f 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 or or an [sqlite
2d070 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 3_interrupt | in
2d080 74 65 72 72 75 70 74 5d 2e 0a 2a 2a 20 49 6e 63 terrupt]..** Inc
2d090 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 65 73 20 omplete updates
2d0a0 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 may be rolled ba
2d0b0 63 6b 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69 ck and transacti
2d0c0 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a ons canceled,.**
2d0d0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 depending on th
2d0e0 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c e circumstances,
2d0f0 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72 and the.** [err
2d100 6f 72 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 or code] returne
2d110 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 d will be [SQLIT
2d120 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 E_ABORT]..**.**
2d130 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
2d140 2a 20 7b 48 31 31 33 30 32 7d 20 54 68 65 20 5b * {H11302} The [
2d150 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
2d160 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 (S)] interface d
2d170 65 73 74 72 6f 79 73 20 74 68 65 0a 2a 2a 20 20 estroys the.**
2d180 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 [prepare
2d190 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 d statement] S a
2d1a0 6e 64 20 72 65 6c 65 61 73 65 73 20 61 6c 6c 0a nd releases all.
2d1b0 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f ** memo
2d1c0 72 79 20 61 6e 64 20 66 69 6c 65 20 72 65 73 6f ry and file reso
2d1d0 75 72 63 65 73 20 68 65 6c 64 20 62 79 20 74 68 urces held by th
2d1e0 61 74 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a at object..**.**
2d1f0 20 7b 48 31 31 33 30 34 7d 20 49 66 20 74 68 65 {H11304} If the
2d200 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c most recent cal
2d210 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 l to [sqlite3_st
2d220 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a ep(S)] for the.*
2d230 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 * [prep
2d240 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2d250 53 20 72 65 74 75 72 6e 65 64 20 61 6e 20 65 72 S returned an er
2d260 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 ror,.**
2d270 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 then [sqlite3_f
2d280 69 6e 61 6c 69 7a 65 28 53 29 5d 20 72 65 74 75 inalize(S)] retu
2d290 72 6e 73 20 74 68 61 74 20 73 61 6d 65 20 65 72 rns that same er
2d2a0 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ror..*/.int sqli
2d2b0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c te3_finalize(sql
2d2c0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
2d2d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2d2e0 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 EF: Reset A Prep
2d2f0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f ared Statement O
2d300 62 6a 65 63 74 20 7b 48 31 33 33 33 30 7d 20 3c bject {H13330} <
2d310 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S70300>.**.** Th
2d320 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 e sqlite3_reset(
2d330 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 ) function is ca
2d340 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 lled to reset a
2d350 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2d360 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 ent].** object b
2d370 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 ack to its initi
2d380 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 al state, ready
2d390 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 to be re-execute
2d3a0 64 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c 20 73 74 d..** Any SQL st
2d3b0 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 atement variable
2d3c0 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 s that had value
2d3d0 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 s bound to them
2d3e0 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 using.** the [sq
2d3f0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 lite3_bind_blob
2d400 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a | sqlite3_bind_*
2d410 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 () API] retain t
2d420 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 heir values..**
2d430 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 Use [sqlite3_cle
2d440 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 ar_bindings()] t
2d450 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 o reset the bind
2d460 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 ings..**.** {H11
2d470 33 33 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 332} The [sqlite
2d480 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 3_reset(S)] inte
2d490 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 rface resets the
2d4a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2d4b0 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20 ment] S.**
2d4c0 20 20 20 20 62 61 63 6b 20 74 6f 20 74 68 65 20 back to the
2d4d0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 beginning of its
2d4e0 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 program..**.**
2d4f0 7b 48 31 31 33 33 34 7d 20 49 66 20 74 68 65 20 {H11334} If the
2d500 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c most recent call
2d510 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 to [sqlite3_ste
2d520 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a p(S)] for the.**
2d530 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 [prepa
2d540 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
2d550 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 returned [SQLIT
2d560 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 E_ROW] or [SQLIT
2d570 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20 20 20 E_DONE],.**
2d580 20 20 20 20 20 6f 72 20 69 66 20 5b 73 71 6c 69 or if [sqli
2d590 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 te3_step(S)] has
2d5a0 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 never before be
2d5b0 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a en called on S,.
2d5c0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e ** then
2d5d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
2d5e0 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c S)] returns [SQL
2d5f0 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b ITE_OK]..**.** {
2d600 48 31 31 33 33 36 7d 20 49 66 20 74 68 65 20 6d H11336} If the m
2d610 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 ost recent call
2d620 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 to [sqlite3_step
2d630 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 (S)] for the.**
2d640 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 [prepar
2d650 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 ed statement] S
2d660 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 indicated an err
2d670 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 or, then.**
2d680 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 [sqlite3_re
2d690 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 set(S)] returns
2d6a0 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b an appropriate [
2d6b0 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a error code]..**.
2d6c0 2a 2a 20 7b 48 31 31 33 33 38 7d 20 54 68 65 20 ** {H11338} The
2d6d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 [sqlite3_reset(S
2d6e0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 )] interface doe
2d6f0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 s not change the
2d700 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 values.**
2d710 20 20 20 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 of any [sqli
2d720 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 te3_bind_blob|bi
2d730 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b ndings] on the [
2d740 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2d750 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 nt] S..*/.int sq
2d760 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 lite3_reset(sqli
2d770 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
2d780 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2d790 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 F: Create Or Red
2d7a0 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 efine SQL Functi
2d7b0 6f 6e 73 20 7b 48 31 36 31 30 30 7d 20 3c 53 32 ons {H16100} <S2
2d7c0 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 0200>.** KEYWORD
2d7d0 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 S: {function cre
2d7e0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a ation routines}.
2d7f0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 ** KEYWORDS: {ap
2d800 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
2d810 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a d SQL function}.
2d820 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 ** KEYWORDS: {ap
2d830 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
2d840 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d d SQL functions}
2d850 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 74 77 6f .**.** These two
2d860 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c functions (coll
2d870 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 ectively known a
2d880 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 s "function crea
2d890 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a tion routines").
2d8a0 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 ** are used to a
2d8b0 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 dd SQL functions
2d8c0 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f or aggregates o
2d8d0 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 r to redefine th
2d8e0 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 e behavior.** of
2d8f0 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 existing SQL fu
2d900 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 nctions or aggre
2d910 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 gates. The only
2d920 20 64 69 66 66 65 72 65 6e 63 65 20 62 65 74 77 difference betw
2d930 65 65 6e 20 74 68 65 0a 2a 2a 20 74 77 6f 20 69 een the.** two i
2d940 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e s that the secon
2d950 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 d parameter, the
2d960 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63 name of the (sc
2d970 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f alar) function o
2d980 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2c 20 r.** aggregate,
2d990 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 is encoded in UT
2d9a0 46 2d 38 20 66 6f 72 20 73 71 6c 69 74 65 33 5f F-8 for sqlite3_
2d9b0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
2d9c0 29 20 61 6e 64 20 55 54 46 2d 31 36 0a 2a 2a 20 ) and UTF-16.**
2d9d0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 for sqlite3_crea
2d9e0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e te_function16().
2d9f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 .**.** The first
2da00 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
2da10 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
2da20 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 ection] to which
2da30 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 the SQL.** func
2da40 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 tion is to be ad
2da50 64 65 64 2e 20 20 49 66 20 61 20 73 69 6e 67 6c ded. If a singl
2da60 65 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 6d e program uses m
2da70 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 ore than one dat
2da80 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 abase.** connect
2da90 69 6f 6e 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 ion internally,
2daa0 74 68 65 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f then SQL functio
2dab0 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 ns must be added
2dac0 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 20 74 6f individually to
2dad0 0a 2a 2a 20 65 61 63 68 20 64 61 74 61 62 61 73 .** each databas
2dae0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a e connection..**
2daf0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 .** The second p
2db00 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 arameter is the
2db10 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 name of the SQL
2db20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 function to be c
2db30 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 reated or.** red
2db40 65 66 69 6e 65 64 2e 20 20 54 68 65 20 6c 65 6e efined. The len
2db50 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 gth of the name
2db60 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 is limited to 25
2db70 35 20 62 79 74 65 73 2c 20 65 78 63 6c 75 73 69 5 bytes, exclusi
2db80 76 65 20 6f 66 0a 2a 2a 20 74 68 65 20 7a 65 72 ve of.** the zer
2db90 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e o-terminator. N
2dba0 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d ote that the nam
2dbb0 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 e length limit i
2dbc0 73 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a s in bytes, not.
2dbd0 2a 2a 20 63 68 61 72 61 63 74 65 72 73 2e 20 20 ** characters.
2dbe0 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 Any attempt to c
2dbf0 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e reate a function
2dc00 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e with a longer n
2dc10 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 ame.** will resu
2dc20 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 45 52 lt in [SQLITE_ER
2dc30 52 4f 52 5d 20 62 65 69 6e 67 20 72 65 74 75 72 ROR] being retur
2dc40 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 ned..**.** The t
2dc50 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 hird parameter (
2dc60 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 nArg).** is the
2dc70 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 number of argume
2dc80 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c nts that the SQL
2dc90 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 function or.**
2dca0 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e aggregate takes.
2dcb0 20 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 If this paramet
2dcc0 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 er is negative,
2dcd0 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e then the SQL fun
2dce0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 ction or.** aggr
2dcf0 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 egate may take a
2dd00 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 ny number of arg
2dd10 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 uments..**.** Th
2dd20 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
2dd30 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 er, eTextRep, sp
2dd40 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 ecifies what.**
2dd50 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 [SQLITE_UTF8 | t
2dd60 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 ext encoding] th
2dd70 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 is SQL function
2dd80 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 prefers for.** i
2dd90 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 ts parameters.
2dda0 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e Any SQL function
2ddb0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
2ddc0 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20 74 should be able t
2ddd0 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 o work.** work w
2dde0 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 ith UTF-8, UTF-1
2ddf0 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 6le, or UTF-16be
2de00 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c . But some impl
2de10 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 ementations may
2de20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 be.** more effic
2de30 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e ient with one en
2de40 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 coding than anot
2de50 68 65 72 2e 20 20 49 74 20 69 73 20 61 6c 6c 6f her. It is allo
2de60 77 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 wed to.** invoke
2de70 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
2de80 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 function() or sq
2de90 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
2dea0 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 ction16() multip
2deb0 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 le.** times with
2dec0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 the same functi
2ded0 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 on but with diff
2dee0 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 erent values of
2def0 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 57 68 65 eTextRep..** Whe
2df00 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 n multiple imple
2df10 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 mentations of th
2df20 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 e same function
2df30 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 are available, S
2df40 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 QLite.** will pi
2df50 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 ck the one that
2df60 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 involves the lea
2df70 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 st amount of dat
2df80 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a a conversion..**
2df90 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c If there is onl
2dfa0 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 y a single imple
2dfb0 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 mentation which
2dfc0 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 does not care wh
2dfd0 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 at text.** encod
2dfe0 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 ing is used, the
2dff0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 n the fourth arg
2e000 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 ument should be
2e010 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a [SQLITE_ANY]..**
2e020 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 70 61 .** The fifth pa
2e030 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 rameter is an ar
2e040 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e bitrary pointer.
2e050 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 The implementa
2e060 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 tion of the.** f
2e070 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e unction can gain
2e080 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 access to this
2e090 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 pointer using [s
2e0a0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 qlite3_user_data
2e0b0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ()]..**.** The s
2e0c0 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61 eventh, eighth a
2e0d0 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 nd ninth paramet
2e0e0 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 ers, xFunc, xSte
2e0f0 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 p and xFinal, ar
2e100 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f e.** pointers to
2e110 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 C-language func
2e120 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 tions that imple
2e130 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e ment the SQL fun
2e140 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 ction or.** aggr
2e150 65 67 61 74 65 2e 20 41 20 73 63 61 6c 61 72 20 egate. A scalar
2e160 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 SQL function req
2e170 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 uires an impleme
2e180 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 ntation of the x
2e190 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b Func.** callback
2e1a0 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e only, NULL poin
2e1b0 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70 ters should be p
2e1c0 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 assed as the xSt
2e1d0 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a ep and xFinal.**
2e1e0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 41 6e 20 parameters. An
2e1f0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 aggregate SQL fu
2e200 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 nction requires
2e210 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f an implementatio
2e220 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e n of xStep.** an
2e230 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c d xFinal and NUL
2e240 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 L should be pass
2e250 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f ed for xFunc. To
2e260 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 delete an exist
2e270 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 ing.** SQL funct
2e280 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 ion or aggregate
2e290 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 , pass NULL for
2e2a0 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 all three functi
2e2b0 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a on callbacks..**
2e2c0 0a 2a 2a 20 49 74 20 69 73 20 70 65 72 6d 69 74 .** It is permit
2e2d0 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 ted to register
2e2e0 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 multiple impleme
2e2f0 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 ntations of the
2e300 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e same.** function
2e310 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 s with the same
2e320 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 name but with ei
2e330 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e ther differing n
2e340 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 umbers of.** arg
2e350 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 uments or differ
2e360 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 ing preferred te
2e370 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53 xt encodings. S
2e380 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a QLite will use.*
2e390 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 * the implementa
2e3a0 74 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c tion most closel
2e3b0 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 y matches the wa
2e3c0 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a y in which the.*
2e3d0 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 * SQL function i
2e3e0 73 20 75 73 65 64 2e 20 20 41 20 66 75 6e 63 74 s used. A funct
2e3f0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ion implementati
2e400 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 on with a non-ne
2e410 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 gative.** nArg p
2e420 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 arameter is a be
2e430 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 tter match than
2e440 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 a function imple
2e450 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a mentation with.*
2e460 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 * a negative nAr
2e470 67 2e 20 20 41 20 66 75 6e 63 74 69 6f 6e 20 77 g. A function w
2e480 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72 here the preferr
2e490 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 ed text encoding
2e4a0 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 .** matches the
2e4b0 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e database encodin
2e4c0 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a g is a better.**
2e4d0 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 match than a fu
2e4e0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 nction where the
2e4f0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 encoding is dif
2e500 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 41 20 66 ferent. .** A f
2e510 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 unction where th
2e520 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 e encoding diffe
2e530 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e rence is between
2e540 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 UTF16le and UTF
2e550 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 16be.** is a clo
2e560 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 ser match than a
2e570 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 function where
2e580 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 the encoding dif
2e590 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 ference is.** be
2e5a0 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 tween UTF8 and U
2e5b0 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 42 75 69 6c TF16..**.** Buil
2e5c0 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d t-in functions m
2e5d0 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 ay be overloaded
2e5e0 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 by new applicat
2e5f0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
2e600 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 66 69 tions..** The fi
2e610 72 73 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d rst application-
2e620 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
2e630 20 77 69 74 68 20 61 20 67 69 76 65 6e 20 6e 61 with a given na
2e640 6d 65 20 6f 76 65 72 72 69 64 65 73 20 61 6c 6c me overrides all
2e650 0a 2a 2a 20 62 75 69 6c 74 2d 69 6e 20 66 75 6e .** built-in fun
2e660 63 74 69 6f 6e 73 20 69 6e 20 74 68 65 20 73 61 ctions in the sa
2e670 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e me [database con
2e680 6e 65 63 74 69 6f 6e 5d 20 77 69 74 68 20 74 68 nection] with th
2e690 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 20 e same name..**
2e6a0 53 75 62 73 65 71 75 65 6e 74 20 61 70 70 6c 69 Subsequent appli
2e6b0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
2e6c0 75 6e 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 unctions of the
2e6d0 73 61 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79 20 6f same name only o
2e6e0 76 65 72 72 69 64 65 20 0a 2a 2a 20 70 72 69 6f verride .** prio
2e6f0 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 r application-de
2e700 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 fined functions
2e710 74 68 61 74 20 61 72 65 20 61 6e 20 65 78 61 63 that are an exac
2e720 74 20 6d 61 74 63 68 20 66 6f 72 20 74 68 65 0a t match for the.
2e730 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 ** number of par
2e740 61 6d 65 74 65 72 73 20 61 6e 64 20 70 72 65 66 ameters and pref
2e750 65 72 72 65 64 20 65 6e 63 6f 64 69 6e 67 2e 0a erred encoding..
2e760 2a 2a 0a 2a 2a 20 41 6e 20 61 70 70 6c 69 63 61 **.** An applica
2e770 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
2e780 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 ction is permitt
2e790 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 ed to call other
2e7a0 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 .** SQLite inter
2e7b0 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c faces. However,
2e7c0 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 such calls must
2e7d0 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 not.** close th
2e7e0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
2e7f0 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 ction nor finali
2e800 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 ze or reset the
2e810 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 prepared.** stat
2e820 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 ement in which t
2e830 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 he function is r
2e840 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e unning..**.** IN
2e850 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
2e860 7b 48 31 36 31 30 33 7d 20 54 68 65 20 5b 73 71 {H16103} The [sq
2e870 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
2e880 63 74 69 6f 6e 31 36 28 44 2c 58 2c 2e 2e 2e 29 ction16(D,X,...)
2e890 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c ] interface shal
2e8a0 6c 20 62 65 68 61 76 65 0a 2a 2a 20 20 20 20 20 l behave.**
2e8b0 20 20 20 20 20 61 73 20 5b 73 71 6c 69 74 65 33 as [sqlite3
2e8c0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
2e8d0 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 20 65 76 (D,X,...)] in ev
2e8e0 65 72 79 20 77 61 79 20 65 78 63 65 70 74 20 74 ery way except t
2e8f0 68 61 74 20 69 74 0a 2a 2a 20 20 20 20 20 20 20 hat it.**
2e900 20 20 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 interprets th
2e910 65 20 58 20 61 72 67 75 6d 65 6e 74 20 61 73 20 e X argument as
2e920 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
2e930 55 54 46 2d 31 36 0a 2a 2a 20 20 20 20 20 20 20 UTF-16.**
2e940 20 20 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f native byte o
2e950 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 rder instead of
2e960 61 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 as zero-terminat
2e970 65 64 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 ed UTF-8..**.**
2e980 7b 48 31 36 31 30 36 7d 20 41 20 73 75 63 63 65 {H16106} A succe
2e990 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e ssful invocation
2e9a0 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 of the.**
2e9b0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 [sqlite3_cre
2e9c0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 ate_function(D,X
2e9d0 2c 4e 2c 45 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 ,N,E,...)] inter
2e9e0 66 61 63 65 20 73 68 61 6c 6c 20 72 65 67 69 73 face shall regis
2e9f0 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ter.**
2ea00 6f 72 20 72 65 70 6c 61 63 65 73 20 63 61 6c 6c or replaces call
2ea10 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 69 back functions i
2ea20 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 n the [database
2ea30 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a connection] D.**
2ea40 20 20 20 20 20 20 20 20 20 20 75 73 65 64 20 74 used t
2ea50 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 o implement the
2ea60 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d SQL function nam
2ea70 65 64 20 58 20 77 69 74 68 20 4e 20 70 61 72 61 ed X with N para
2ea80 6d 65 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 meters.**
2ea90 20 20 20 61 6e 64 20 68 61 76 69 6e 67 20 61 20 and having a
2eaa0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 preferred text e
2eab0 6e 63 6f 64 69 6e 67 20 6f 66 20 45 2e 0a 2a 2a ncoding of E..**
2eac0 0a 2a 2a 20 7b 48 31 36 31 30 39 7d 20 41 20 73 .** {H16109} A s
2ead0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 uccessful call t
2eae0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 o [sqlite3_creat
2eaf0 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e e_function(D,X,N
2eb00 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 ,E,P,F,S,L)].**
2eb10 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 72 shall r
2eb20 65 70 6c 61 63 65 20 74 68 65 20 50 2c 20 46 2c eplace the P, F,
2eb30 20 53 2c 20 61 6e 64 20 4c 20 76 61 6c 75 65 73 S, and L values
2eb40 20 66 72 6f 6d 20 61 6e 79 20 70 72 69 6f 72 20 from any prior
2eb50 63 61 6c 6c 73 20 77 69 74 68 0a 2a 2a 20 20 20 calls with.**
2eb60 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 the same
2eb70 44 2c 20 58 2c 20 4e 2c 20 61 6e 64 20 45 20 76 D, X, N, and E v
2eb80 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 alues..**.** {H1
2eb90 36 31 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 6112} The [sqlit
2eba0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
2ebb0 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 74 on(D,X,...)] int
2ebc0 65 72 66 61 63 65 20 73 68 61 6c 6c 20 66 61 69 erface shall fai
2ebd0 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 l.** if
2ebe0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
2ebf0 6e 20 6e 61 6d 65 20 58 20 69 73 0a 2a 2a 20 20 n name X is.**
2ec00 20 20 20 20 20 20 20 20 6c 6f 6e 67 65 72 20 74 longer t
2ec10 68 61 6e 20 32 35 35 20 62 79 74 65 73 20 65 78 han 255 bytes ex
2ec20 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a clusive of the z
2ec30 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a ero terminator..
2ec40 2a 2a 0a 2a 2a 20 7b 48 31 36 31 31 38 7d 20 54 **.** {H16118} T
2ec50 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 he [sqlite3_crea
2ec60 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c te_function(D,X,
2ec70 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 69 6e N,E,P,F,S,L)] in
2ec80 74 65 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 terface.**
2ec90 20 20 20 20 73 68 61 6c 6c 20 66 61 69 6c 20 75 shall fail u
2eca0 6e 6c 65 73 73 20 65 69 74 68 65 72 20 46 20 69 nless either F i
2ecb0 73 20 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64 s NULL and S and
2ecc0 20 4c 20 61 72 65 20 6e 6f 6e 2d 4e 55 4c 4c 20 L are non-NULL
2ecd0 6f 72 0a 2a 2a 2a 20 20 20 20 20 20 20 20 20 46 or.*** F
2ece0 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 20 61 6e 64 is non-NULL and
2ecf0 20 53 20 61 6e 64 20 4c 20 61 72 65 20 4e 55 4c S and L are NUL
2ed00 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 31 L..**.** {H16121
2ed10 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 } The [sqlite3_c
2ed20 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 reate_function(D
2ed30 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 ,...)] interface
2ed40 20 73 68 61 6c 6c 20 66 61 69 6c 73 20 77 69 74 shall fails wit
2ed50 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 h an.**
2ed60 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b error code of [
2ed70 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 66 20 SQLITE_BUSY] if
2ed80 74 68 65 72 65 20 65 78 69 73 74 20 5b 70 72 65 there exist [pre
2ed90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 pared statements
2eda0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 ].** as
2edb0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 sociated with th
2edc0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
2edd0 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a ection] D..**.**
2ede0 20 7b 48 31 36 31 32 34 7d 20 54 68 65 20 5b 73 {H16124} The [s
2edf0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
2ee00 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e nction(D,X,N,...
2ee10 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 )] interface sha
2ee20 6c 6c 20 66 61 69 6c 20 77 69 74 68 0a 2a 2a 20 ll fail with.**
2ee30 20 20 20 20 20 20 20 20 20 61 6e 20 65 72 72 6f an erro
2ee40 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 r code of [SQLIT
2ee50 45 5f 45 52 52 4f 52 5d 20 69 66 20 70 61 72 61 E_ERROR] if para
2ee60 6d 65 74 65 72 20 4e 20 69 73 20 6c 65 73 73 0a meter N is less.
2ee70 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 6e ** than
2ee80 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 -1 or greater t
2ee90 68 61 6e 20 31 32 37 2e 0a 2a 2a 0a 2a 2a 20 7b han 127..**.** {
2eea0 48 31 36 31 32 37 7d 20 57 68 65 6e 20 4e 20 69 H16127} When N i
2eeb0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 s non-negative,
2eec0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 the [sqlite3_cre
2eed0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 ate_function(D,X
2eee0 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 ,N,...)].**
2eef0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 73 interface s
2ef00 68 61 6c 6c 20 72 65 67 69 73 74 65 72 20 63 61 hall register ca
2ef10 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e llbacks to be in
2ef20 76 6f 6b 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a voked for the.**
2ef30 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 66 75 SQL fu
2ef40 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 nction.**
2ef50 20 20 20 6e 61 6d 65 64 20 58 20 77 68 65 6e 20 named X when
2ef60 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 the number of ar
2ef70 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 53 guments to the S
2ef80 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a QL function is.*
2ef90 2a 20 20 20 20 20 20 20 20 20 20 65 78 61 63 74 * exact
2efa0 6c 79 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 ly N..**.** {H16
2efb0 31 33 30 7d 20 57 68 65 6e 20 4e 20 69 73 20 2d 130} When N is -
2efc0 31 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 1, the [sqlite3_
2efd0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
2efe0 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 D,X,N,...)].**
2eff0 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 interfac
2f000 65 20 73 68 61 6c 6c 20 72 65 67 69 73 74 65 72 e shall register
2f010 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65 callbacks to be
2f020 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 65 invoked for the
2f030 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 SQL.**
2f040 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 64 20 function named
2f050 58 20 77 69 74 68 20 61 6e 79 20 6e 75 6d 62 65 X with any numbe
2f060 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a r of arguments..
2f070 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 33 7d 20 57 **.** {H16133} W
2f080 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 hen calls to [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 58 2c 4e 2c 2e 2e 2e 29 ction(D,X,N,...)
2f0b0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 70 ].** sp
2f0c0 65 63 69 66 79 20 6d 75 6c 74 69 70 6c 65 20 69 ecify multiple i
2f0d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f mplementations o
2f0e0 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 f the same funct
2f0f0 69 6f 6e 20 58 0a 2a 2a 20 20 20 20 20 20 20 20 ion X.**
2f100 20 20 61 6e 64 20 77 68 65 6e 20 6f 6e 65 20 69 and when one i
2f110 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 68 61 mplementation ha
2f120 73 20 4e 3e 3d 30 20 61 6e 64 20 74 68 65 20 6f s N>=0 and the o
2f130 74 68 65 72 20 68 61 73 20 4e 3d 28 2d 31 29 0a ther has N=(-1).
2f140 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
2f150 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 implementation w
2f160 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 4e ith a non-zero N
2f170 20 73 68 61 6c 6c 20 62 65 20 70 72 65 66 65 72 shall be prefer
2f180 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 red..**.** {H161
2f190 33 36 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20 74 36} When calls t
2f1a0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 o [sqlite3_creat
2f1b0 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e e_function(D,X,N
2f1c0 2c 45 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 ,E,...)].**
2f1d0 20 20 20 20 20 73 70 65 63 69 66 79 20 6d 75 6c specify mul
2f1e0 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 tiple implementa
2f1f0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d tions of the sam
2f200 65 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 e function X wit
2f210 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 h.** th
2f220 65 20 73 61 6d 65 20 6e 75 6d 62 65 72 20 6f 66 e same number of
2f230 20 61 72 67 75 6d 65 6e 74 73 20 4e 20 62 75 74 arguments N but
2f240 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 0a with different.
2f250 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e 63 6f ** enco
2f260 64 69 6e 67 73 20 45 2c 20 74 68 65 6e 20 74 68 dings E, then th
2f270 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
2f280 20 77 68 65 72 65 20 45 20 6d 61 74 63 68 65 73 where E matches
2f290 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
2f2a0 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 database encodi
2f2b0 6e 67 20 73 68 61 6c 6c 20 70 72 65 66 65 72 72 ng shall preferr
2f2c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 ed..**.** {H1613
2f2d0 39 7d 20 46 6f 72 20 61 6e 20 61 67 67 72 65 67 9} For an aggreg
2f2e0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ate SQL function
2f2f0 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a created using.*
2f300 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
2f310 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
2f320 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 30 2c ion(D,X,N,E,P,0,
2f330 53 2c 4c 29 5d 20 74 68 65 20 66 69 6e 61 6c 69 S,L)] the finali
2f340 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 zer.**
2f350 66 75 6e 63 74 69 6f 6e 20 4c 20 73 68 61 6c 6c function L shall
2f360 20 61 6c 77 61 79 73 20 62 65 20 69 6e 76 6f 6b always be invok
2f370 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 20 ed exactly once
2f380 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 if the.**
2f390 20 20 20 73 74 65 70 20 66 75 6e 63 74 69 6f 6e step function
2f3a0 20 53 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 65 S is called one
2f3b0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a or more times..
2f3c0 2a 2a 0a 2a 2a 20 7b 48 31 36 31 34 32 7d 20 57 **.** {H16142} W
2f3d0 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b hen SQLite invok
2f3e0 65 73 20 65 69 74 68 65 72 20 74 68 65 20 78 46 es either the xF
2f3f0 75 6e 63 20 6f 72 20 78 53 74 65 70 20 66 75 6e unc or xStep fun
2f400 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20 20 ction of.**
2f410 20 20 20 20 20 61 6e 20 61 70 70 6c 69 63 61 74 an applicat
2f420 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
2f430 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 function or aggr
2f440 65 67 61 74 65 20 63 72 65 61 74 65 64 0a 2a 2a egate created.**
2f450 20 20 20 20 20 20 20 20 20 20 62 79 20 5b 73 71 by [sq
2f460 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
2f470 63 74 69 6f 6e 28 29 5d 20 6f 72 20 5b 73 71 6c ction()] or [sql
2f480 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
2f490 74 69 6f 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 tion16()],.**
2f4a0 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 then the
2f4b0 61 72 72 61 79 20 6f 66 20 5b 73 71 6c 69 74 65 array of [sqlite
2f4c0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 3_value] objects
2f4d0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a passed as the.*
2f4e0 2a 20 20 20 20 20 20 20 20 20 20 74 68 69 72 64 * third
2f4f0 20 70 61 72 61 6d 65 74 65 72 20 73 68 61 6c 6c parameter shall
2f500 20 62 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 be [protected s
2f510 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
2f520 6a 65 63 74 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 jects..*/.int sq
2f530 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
2f540 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 ction(. sqlite3
2f550 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 *db,. const ch
2f560 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d ar *zFunctionNam
2f570 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 e,. int nArg,.
2f580 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 int eTextRep,.
2f590 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 void *pApp,. v
2f5a0 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c oid (*xFunc)(sql
2f5b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e ite3_context*,in
2f5c0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t,sqlite3_value*
2f5d0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 *),. void (*xSt
2f5e0 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ep)(sqlite3_cont
2f5f0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
2f600 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
2f610 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 d (*xFinal)(sqli
2f620 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b te3_context*).);
2f630 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 .int sqlite3_cre
2f640 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a ate_function16(.
2f650 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 sqlite3 *db,.
2f660 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 const void *zFu
2f670 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e nctionName,. in
2f680 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 t nArg,. int eT
2f690 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a extRep,. void *
2f6a0 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 pApp,. void (*x
2f6b0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f Func)(sqlite3_co
2f6c0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 ntext*,int,sqlit
2f6d0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 e3_value**),. v
2f6e0 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c oid (*xStep)(sql
2f6f0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e ite3_context*,in
2f700 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t,sqlite3_value*
2f710 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 *),. void (*xFi
2f720 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e nal)(sqlite3_con
2f730 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a text*).);../*.**
2f740 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 CAPI3REF: Text
2f750 45 6e 63 6f 64 69 6e 67 73 20 7b 48 31 30 32 36 Encodings {H1026
2f760 37 7d 20 3c 53 35 30 32 30 30 3e 20 3c 48 31 36 7} <S50200> <H16
2f770 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 100>.**.** These
2f780 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 constant define
2f790 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 integer codes t
2f7a0 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 hat represent th
2f7b0 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 e various.** tex
2f7c0 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 t encodings supp
2f7d0 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e orted by SQLite.
2f7e0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
2f7f0 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 TE_UTF8
2f800 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 1.#define SQLI
2f810 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 TE_UTF16LE
2f820 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 2.#define SQLI
2f830 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 TE_UTF16BE
2f840 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 3.#define SQLI
2f850 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 TE_UTF16
2f860 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 4 /* Use na
2f870 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 tive byte order
2f880 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
2f890 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 E_ANY
2f8a0 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5 /* sqlite3
2f8b0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
2f8c0 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 only */.#define
2f8d0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c SQLITE_UTF16_AL
2f8e0 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 IGNED 8 /* s
2f8f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
2f900 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a llation only */.
2f910 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2f920 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 Deprecated Func
2f930 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 tions.** DEPRECA
2f940 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 TED.**.** These
2f950 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 functions are [d
2f960 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 eprecated]. In
2f970 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 order to maintai
2f980 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 n.** backwards c
2f990 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 ompatibility wit
2f9a0 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 h older code, th
2f9b0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f ese functions co
2f9c0 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 ntinue .** to be
2f9d0 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 supported. How
2f9e0 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 ever, new applic
2f9f0 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 ations should av
2fa00 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f oid.** the use o
2fa10 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e f these function
2fa20 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f s. To help enco
2fa30 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 urage people to
2fa40 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 avoid.** using t
2fa50 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 hese functions,
2fa60 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 we are not going
2fa70 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 61 6e to tell you wan
2fa80 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 t they do..*/.#i
2fa90 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 fndef SQLITE_OMI
2faa0 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c T_DEPRECATED.SQL
2fab0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 ITE_DEPRECATED i
2fac0 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 nt sqlite3_aggre
2fad0 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 gate_count(sqlit
2fae0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 e3_context*);.SQ
2faf0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 LITE_DEPRECATED
2fb00 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 int sqlite3_expi
2fb10 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 red(sqlite3_stmt
2fb20 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 *);.SQLITE_DEPRE
2fb30 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 CATED int sqlite
2fb40 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 3_transfer_bindi
2fb50 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ngs(sqlite3_stmt
2fb60 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a *, sqlite3_stmt*
2fb70 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 );.SQLITE_DEPREC
2fb80 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 ATED int sqlite3
2fb90 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 _global_recover(
2fba0 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 void);.SQLITE_DE
2fbb0 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 PRECATED void sq
2fbc0 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 lite3_thread_cle
2fbd0 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 anup(void);.SQLI
2fbe0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e TE_DEPRECATED in
2fbf0 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 t sqlite3_memory
2fc00 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 _alarm(void(*)(v
2fc10 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 oid*,sqlite3_int
2fc20 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 64,int),void*,sq
2fc30 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 lite3_int64);.#e
2fc40 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ndif../*.** CAPI
2fc50 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 3REF: Obtaining
2fc60 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 SQL Function Par
2fc70 61 6d 65 74 65 72 20 56 61 6c 75 65 73 20 7b 48 ameter Values {H
2fc80 31 35 31 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 15100} <S20200>.
2fc90 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 **.** The C-lang
2fca0 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 uage implementat
2fcb0 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 ion of SQL funct
2fcc0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 ions and aggrega
2fcd0 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 tes uses.** this
2fce0 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 set of interfac
2fcf0 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 e routines to ac
2fd00 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 cess the paramet
2fd10 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 er values on.**
2fd20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 the function or
2fd30 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a aggregate..**.**
2fd40 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 The xFunc (for
2fd50 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 scalar functions
2fd60 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 ) or xStep (for
2fd70 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61 aggregates) para
2fd80 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 meters.** to [sq
2fd90 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
2fda0 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 ction()] and [sq
2fdb0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
2fdc0 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 ction16()].** de
2fdd0 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 fine callbacks t
2fde0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 hat implement th
2fdf0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 e SQL functions
2fe00 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a and aggregates..
2fe10 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d ** The 4th param
2fe20 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 eter to these ca
2fe30 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 llbacks is an ar
2fe40 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 ray of pointers
2fe50 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 to.** [protected
2fe60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
2fe70 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 objects. There
2fe80 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f is one [sqlite3_
2fe90 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f value] object fo
2fea0 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 r.** each parame
2feb0 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 ter to the SQL f
2fec0 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 unction. These
2fed0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 routines are use
2fee0 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 d to.** extract
2fef0 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 values from the
2ff00 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 [sqlite3_value]
2ff10 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 objects..**.** T
2ff20 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f hese routines wo
2ff30 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 rk only with [pr
2ff40 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
2ff50 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a value] objects..
2ff60 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 ** Any attempt t
2ff70 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 o use these rout
2ff80 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 ines on an [unpr
2ff90 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
2ffa0 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 value].** object
2ffb0 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 results in unde
2ffc0 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a fined behavior..
2ffd0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
2ffe0 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c ines work just l
2fff0 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f ike the correspo
30000 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 nding [column ac
30010 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a cess functions].
30020 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20 ** except that
30030 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 these routines t
30040 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 ake a single [pr
30050 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
30060 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a value] object.**
30070 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 pointer instead
30080 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 of a [sqlite3_s
30090 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e tmt*] pointer an
300a0 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c d an integer col
300b0 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a umn number..**.*
300c0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 * The sqlite3_va
300d0 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 lue_text16() int
300e0 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 erface extracts
300f0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a a UTF-16 string.
30100 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 ** in the native
30110 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 byte-order of t
30120 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e he host machine.
30130 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 The.** sqlite3
30140 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 _value_text16be(
30150 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 ) and sqlite3_va
30160 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 lue_text16le() i
30170 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 nterfaces.** ext
30180 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 ract UTF-16 stri
30190 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 ngs as big-endia
301a0 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 n and little-end
301b0 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 ian respectively
301c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
301d0 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 te3_value_numeri
301e0 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 c_type() interfa
301f0 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 ce attempts to a
30200 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 pply.** numeric
30210 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 affinity to the
30220 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 value. This mea
30230 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d ns that an attem
30240 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f pt is.** made to
30250 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c convert the val
30260 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 ue to an integer
30270 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 or floating poi
30280 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 nt. If.** such
30290 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 a conversion is
302a0 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 possible without
302b0 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 loss of informa
302c0 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a tion (in other.*
302d0 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 * words, if the
302e0 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e value is a strin
302f0 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b g that looks lik
30300 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 e a number).** t
30310 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 hen the conversi
30320 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e on is performed.
30330 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 Otherwise no c
30340 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 onversion occurs
30350 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ..** The [SQLITE
30360 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 _INTEGER | datat
30370 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 ype] after conve
30380 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 rsion is returne
30390 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 d..**.** Please
303a0 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 pay particular a
303b0 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 ttention to the
303c0 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f fact that the po
303d0 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a inter returned.*
303e0 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f * from [sqlite3_
303f0 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b value_blob()], [
30400 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
30410 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 xt()], or.** [sq
30420 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
30430 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 16()] can be inv
30440 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 alidated by a su
30450 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f bsequent call to
30460 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c .** [sqlite3_val
30470 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 ue_bytes()], [sq
30480 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 lite3_value_byte
30490 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 s16()], [sqlite3
304a0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a _value_text()],.
304b0 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 ** or [sqlite3_v
304c0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a alue_text16()]..
304d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
304e0 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c ines must be cal
304f0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d led from the sam
30500 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 e thread as.** t
30510 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 he SQL function
30520 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 that supplied th
30530 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 e [sqlite3_value
30540 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a *] parameters..*
30550 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
30560 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 33 7d 20 .**.** {H15103}
30570 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c The [sqlite3_val
30580 75 65 5f 62 6c 6f 62 28 56 29 5d 20 69 6e 74 65 ue_blob(V)] inte
30590 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 rface converts t
305a0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b he.** [
305b0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
305c0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
305d0 56 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 61 6e V into a BLOB an
305e0 64 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 d then.**
305f0 20 20 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 returns a poi
30600 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6e 76 nter to the conv
30610 65 72 74 65 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a erted value..**.
30620 2a 2a 20 7b 48 31 35 31 30 36 7d 20 54 68 65 20 ** {H15106} The
30630 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 [sqlite3_value_b
30640 79 74 65 73 28 56 29 5d 20 69 6e 74 65 72 66 61 ytes(V)] interfa
30650 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a ce returns the.*
30660 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 * numbe
30670 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
30680 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 e BLOB or string
30690 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 (exclusive of t
306a0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a he.** z
306b0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f ero terminator o
306c0 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 n the string) th
306d0 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 at was returned
306e0 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 by the.**
306f0 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 most recent c
30700 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
30710 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20 6f value_blob(V)] o
30720 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 r.** [s
30730 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
30740 74 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 t(V)]..**.** {H1
30750 35 31 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 5109} The [sqlit
30760 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 e3_value_bytes16
30770 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 (V)] interface r
30780 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 eturns the.**
30790 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 number of
307a0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 bytes in the st
307b0 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 ring (exclusive
307c0 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 of the.**
307d0 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 zero terminat
307e0 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 or on the string
307f0 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 ) that was retur
30800 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 ned by the.**
30810 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 most rece
30820 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 nt call to [sqli
30830 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
30840 28 56 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 (V)],.**
30850 20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 [sqlite3_value
30860 5f 74 65 78 74 31 36 62 65 28 56 29 5d 2c 20 6f _text16be(V)], o
30870 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 r [sqlite3_value
30880 5f 74 65 78 74 31 36 6c 65 28 56 29 5d 2e 0a 2a _text16le(V)]..*
30890 2a 0a 2a 2a 20 7b 48 31 35 31 31 32 7d 20 54 68 *.** {H15112} Th
308a0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 e [sqlite3_value
308b0 5f 64 6f 75 62 6c 65 28 56 29 5d 20 69 6e 74 65 _double(V)] inte
308c0 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 rface converts t
308d0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b he.** [
308e0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
308f0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
30900 56 20 69 6e 74 6f 20 61 20 66 6c 6f 61 74 69 6e V into a floatin
30910 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 61 6e g point value an
30920 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 d.** re
30930 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 turns a copy of
30940 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a that value..**.*
30950 2a 20 7b 48 31 35 31 31 35 7d 20 54 68 65 20 5b * {H15115} The [
30960 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e sqlite3_value_in
30970 74 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 t(V)] interface
30980 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 converts the.**
30990 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 [protec
309a0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
309b0 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f e] object V into
309c0 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 a 64-bit signed
309d0 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 integer and.**
309e0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 returns
309f0 20 74 68 65 20 6c 6f 77 65 72 20 33 32 20 62 69 the lower 32 bi
30a00 74 73 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 ts of that integ
30a10 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31 er..**.** {H1511
30a20 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 8} The [sqlite3_
30a30 76 61 6c 75 65 5f 69 6e 74 36 34 28 56 29 5d 20 value_int64(V)]
30a40 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 interface conver
30a50 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 ts the.**
30a60 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 [protected sq
30a70 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
30a80 65 63 74 20 56 20 69 6e 74 6f 20 61 20 36 34 2d ect V into a 64-
30a90 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 bit signed integ
30aa0 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 er and.**
30ab0 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 returns a cop
30ac0 79 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 y of that intege
30ad0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32 31 r..**.** {H15121
30ae0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 } The [sqlite3_v
30af0 61 6c 75 65 5f 74 65 78 74 28 56 29 5d 20 69 6e alue_text(V)] in
30b00 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 terface converts
30b10 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
30b20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 [protected sqli
30b30 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
30b40 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d t V into a zero-
30b50 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 terminated UTF-8
30b60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 .** str
30b70 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 ing and returns
30b80 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 a pointer to tha
30b90 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 t string..**.**
30ba0 7b 48 31 35 31 32 34 7d 20 54 68 65 20 5b 73 71 {H15124} The [sq
30bb0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
30bc0 31 36 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 16(V)] interface
30bd0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a converts the.**
30be0 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 [prote
30bf0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
30c00 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 ue] object V int
30c10 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 o a zero-termina
30c20 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 ted 2-byte.**
30c30 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 aligned U
30c40 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 TF-16 native byt
30c50 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 e order.**
30c60 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 string and r
30c70 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
30c80 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e to that string.
30c90 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32 37 7d 20 .**.** {H15127}
30ca0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c The [sqlite3_val
30cb0 75 65 5f 74 65 78 74 31 36 62 65 28 56 29 5d 20 ue_text16be(V)]
30cc0 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 interface conver
30cd0 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 ts the.**
30ce0 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 [protected sq
30cf0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
30d00 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 ect V into a zer
30d10 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 o-terminated 2-b
30d20 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 yte.**
30d30 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 62 aligned UTF-16 b
30d40 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 ig-endian.**
30d50 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 string and
30d60 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
30d70 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e er to that strin
30d80 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33 30 g..**.** {H15130
30d90 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 } The [sqlite3_v
30da0 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56 29 alue_text16le(V)
30db0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 ] interface conv
30dc0 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 erts the.**
30dd0 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 [protected
30de0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
30df0 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a bject V into a z
30e00 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 ero-terminated 2
30e10 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 -byte.**
30e20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 aligned UTF-16
30e30 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a little-endian.*
30e40 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e * strin
30e50 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 g and returns a
30e60 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 pointer to that
30e70 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 string..**.** {H
30e80 31 35 31 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 15133} The [sqli
30e90 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 56 te3_value_type(V
30ea0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
30eb0 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 urns.**
30ec0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f one of [SQLITE_
30ed0 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 NULL], [SQLITE_I
30ee0 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 NTEGER], [SQLITE
30ef0 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 _FLOAT],.**
30f00 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 [SQLITE_TEX
30f10 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 T], or [SQLITE_B
30f20 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 LOB] as appropri
30f30 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 ate for.**
30f40 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 the [sqlite3
30f50 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 _value] object V
30f60 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33 36 7d ..**.** {H15136}
30f70 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 The [sqlite3_va
30f80 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 lue_numeric_type
30f90 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 (V)] interface c
30fa0 6f 6e 76 65 72 74 73 0a 2a 2a 20 20 20 20 20 20 onverts.**
30fb0 20 20 20 20 74 68 65 20 5b 70 72 6f 74 65 63 74 the [protect
30fc0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
30fd0 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 ] object V into
30fe0 65 69 74 68 65 72 20 61 6e 20 69 6e 74 65 67 65 either an intege
30ff0 72 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 r or.**
31000 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e a floating poin
31010 74 20 76 61 6c 75 65 20 69 66 20 69 74 20 63 61 t value if it ca
31020 6e 20 64 6f 20 73 6f 20 77 69 74 68 6f 75 74 20 n do so without
31030 6c 6f 73 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 loss of.**
31040 20 20 20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c information,
31050 20 61 6e 64 20 72 65 74 75 72 6e 73 20 6f 6e 65 and returns one
31060 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c of [SQLITE_NULL
31070 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b ],.** [
31080 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c SQLITE_INTEGER],
31090 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c [SQLITE_FLOAT],
310a0 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 [SQLITE_TEXT],
310b0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b or.** [
310c0 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 SQLITE_BLOB] as
310d0 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 appropriate for
310e0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
310f0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 [protected sqlit
31100 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
31110 20 56 20 61 66 74 65 72 20 74 68 65 20 63 6f 6e V after the con
31120 76 65 72 73 69 6f 6e 20 61 74 74 65 6d 70 74 2e version attempt.
31130 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a .*/.const void *
31140 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c sqlite3_value_bl
31150 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ob(sqlite3_value
31160 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f *);.int sqlite3_
31170 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 value_bytes(sqli
31180 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 te3_value*);.int
31190 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 sqlite3_value_b
311a0 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 ytes16(sqlite3_v
311b0 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 alue*);.double s
311c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 qlite3_value_dou
311d0 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 ble(sqlite3_valu
311e0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 e*);.int sqlite3
311f0 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 _value_int(sqlit
31200 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 e3_value*);.sqli
31210 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 te3_int64 sqlite
31220 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 3_value_int64(sq
31230 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 lite3_value*);.c
31240 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 onst unsigned ch
31250 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 ar *sqlite3_valu
31260 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 e_text(sqlite3_v
31270 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f alue*);.const vo
31280 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 id *sqlite3_valu
31290 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 e_text16(sqlite3
312a0 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 _value*);.const
312b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 void *sqlite3_va
312c0 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c lue_text16le(sql
312d0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f ite3_value*);.co
312e0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
312f0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 3_value_text16be
31300 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
31310 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 ;.int sqlite3_va
31320 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 lue_type(sqlite3
31330 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 _value*);.int sq
31340 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 lite3_value_nume
31350 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 ric_type(sqlite3
31360 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a _value*);../*.**
31370 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 CAPI3REF: Obtai
31380 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 n Aggregate Func
31390 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 7b 48 31 tion Context {H1
313a0 36 32 31 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 6210} <S20200>.*
313b0 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 *.** The impleme
313c0 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 ntation of aggre
313d0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f gate SQL functio
313e0 6e 73 20 75 73 65 20 74 68 69 73 20 72 6f 75 74 ns use this rout
313f0 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a ine to allocate.
31400 2a 2a 20 61 20 73 74 72 75 63 74 75 72 65 20 66 ** a structure f
31410 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 or storing their
31420 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 state..**.** Th
31430 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 e first time the
31440 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 sqlite3_aggrega
31450 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 72 6f 75 te_context() rou
31460 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 66 tine is called f
31470 6f 72 20 61 0a 2a 2a 20 70 61 72 74 69 63 75 6c or a.** particul
31480 61 72 20 61 67 67 72 65 67 61 74 65 2c 20 53 51 ar aggregate, SQ
31490 4c 69 74 65 20 61 6c 6c 6f 63 61 74 65 73 20 6e Lite allocates n
314a0 42 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c Bytes of memory,
314b0 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 zeroes out that
314c0 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 .** memory, and
314d0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
314e0 72 20 74 6f 20 69 74 2e 20 4f 6e 20 73 65 63 6f r to it. On seco
314f0 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e nd and subsequen
31500 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 t calls to.** sq
31510 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
31520 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 context() for th
31530 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 e same aggregate
31540 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64 65 78 2c function index,
31550 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 .** the same buf
31560 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e fer is returned.
31570 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 The implementat
31580 69 6f 6e 20 6f 66 20 74 68 65 20 61 67 67 72 65 ion of the aggre
31590 67 61 74 65 20 63 61 6e 20 75 73 65 0a 2a 2a 20 gate can use.**
315a0 74 68 65 20 72 65 74 75 72 6e 65 64 20 62 75 66 the returned buf
315b0 66 65 72 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 fer to accumulat
315c0 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 e data..**.** SQ
315d0 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c Lite automatical
315e0 6c 79 20 66 72 65 65 73 20 74 68 65 20 61 6c 6c ly frees the all
315f0 6f 63 61 74 65 64 20 62 75 66 66 65 72 20 77 68 ocated buffer wh
31600 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 en the aggregate
31610 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 .** query conclu
31620 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 des..**.** The f
31630 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 73 irst parameter s
31640 68 6f 75 6c 64 20 62 65 20 61 20 63 6f 70 79 20 hould be a copy
31650 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 of the.** [sqlit
31660 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c e3_context | SQL
31670 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 function contex
31680 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 t] that is the f
31690 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a irst parameter.*
316a0 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 * to the callbac
316b0 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 k routine that i
316c0 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 mplements the ag
316d0 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e gregate function
316e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 ..**.** This rou
316f0 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c tine must be cal
31700 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d led from the sam
31710 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 e thread in whic
31720 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 h.** the aggrega
31730 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 te SQL function
31740 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a is running..**.*
31750 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
31760 0a 2a 2a 20 7b 48 31 36 32 31 31 7d 20 54 68 65 .** {H16211} The
31770 20 66 69 72 73 74 20 69 6e 76 6f 63 61 74 69 6f first invocatio
31780 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 61 67 n of [sqlite3_ag
31790 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
317a0 43 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20 20 20 20 C,N)] for.**
317b0 20 20 20 20 20 20 61 20 70 61 72 74 69 63 75 6c a particul
317c0 61 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 61 ar instance of a
317d0 6e 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 n aggregate func
317e0 74 69 6f 6e 20 28 66 6f 72 20 61 20 70 61 72 74 tion (for a part
317f0 69 63 75 6c 61 72 0a 2a 2a 20 20 20 20 20 20 20 icular.**
31800 20 20 20 63 6f 6e 74 65 78 74 20 43 29 20 63 61 context C) ca
31810 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 61 uses SQLite to a
31820 6c 6c 6f 63 61 74 65 20 4e 20 62 79 74 65 73 20 llocate N bytes
31830 6f 66 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 20 20 of memory,.**
31840 20 20 20 20 20 20 20 7a 65 72 6f 20 74 68 61 74 zero that
31850 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 memory, and ret
31860 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f urn a pointer to
31870 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 6d the allocated m
31880 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 emory..**.** {H1
31890 36 32 31 33 7d 20 49 66 20 61 20 6d 65 6d 6f 72 6213} If a memor
318a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 y allocation err
318b0 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 or occurs during
318c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
318d0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
318e0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 74 68 context(C,N)] th
318f0 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 en the function
31900 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 0a 2a 2a returns 0..**.**
31910 20 7b 48 31 36 32 31 35 7d 20 53 65 63 6f 6e 64 {H16215} Second
31920 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 and subsequent
31930 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 0a 2a invocations of.*
31940 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
31950 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
31960 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72 20 ntext(C,N)] for
31970 74 68 65 20 73 61 6d 65 20 63 6f 6e 74 65 78 74 the same context
31980 20 70 6f 69 6e 74 65 72 20 43 0a 2a 2a 20 20 20 pointer C.**
31990 20 20 20 20 20 20 20 69 67 6e 6f 72 65 20 74 68 ignore th
319a0 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 61 6e e N parameter an
319b0 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 d return a point
319c0 65 72 20 74 6f 20 74 68 65 20 73 61 6d 65 0a 2a er to the same.*
319d0 2a 20 20 20 20 20 20 20 20 20 20 62 6c 6f 63 6b * block
319e0 20 6f 66 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 of memory retur
319f0 6e 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 ned by the first
31a00 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a invocation..**.
31a10 2a 2a 20 7b 48 31 36 32 31 37 7d 20 54 68 65 20 ** {H16217} The
31a20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 memory allocated
31a30 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 by [sqlite3_agg
31a40 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 regate_context(C
31a50 2c 4e 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 ,N)] is.**
31a60 20 20 20 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c automaticall
31a70 79 20 66 72 65 65 64 20 6f 6e 20 74 68 65 20 6e y freed on the n
31a80 65 78 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ext call to [sql
31a90 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a ite3_reset()].**
31aa0 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 or [sq
31ab0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
31ac0 5d 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 ] for the [prepa
31ad0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 63 red statement] c
31ae0 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 20 20 20 ontaining.**
31af0 20 20 20 20 20 20 74 68 65 20 61 67 67 72 65 67 the aggreg
31b00 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 ate function ass
31b10 6f 63 69 61 74 65 64 20 77 69 74 68 20 63 6f 6e ociated with con
31b20 74 65 78 74 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 text C..*/.void
31b30 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 *sqlite3_aggrega
31b40 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 te_context(sqlit
31b50 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 e3_context*, int
31b60 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a nBytes);../*.**
31b70 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 CAPI3REF: User
31b80 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f Data For Functio
31b90 6e 73 20 7b 48 31 36 32 34 30 7d 20 3c 53 32 30 ns {H16240} <S20
31ba0 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 200>.**.** The s
31bb0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 qlite3_user_data
31bc0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 () interface ret
31bd0 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a urns a copy of.*
31be0 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 * the pointer th
31bf0 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72 at was the pUser
31c00 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 Data parameter (
31c10 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 the 5th paramete
31c20 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 r).** of the [sq
31c30 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
31c40 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 ction()].** and
31c50 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
31c60 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f function16()] ro
31c70 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 utines that orig
31c80 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 inally.** regist
31c90 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 ered the applica
31ca0 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e tion defined fun
31cb0 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a ction. {END}.**.
31cc0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
31cd0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 must be called f
31ce0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 rom the same thr
31cf0 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 ead in which.**
31d00 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
31d10 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
31d20 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a is running..**.
31d30 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
31d40 2a 0a 2a 2a 20 7b 48 31 36 32 34 33 7d 20 54 68 *.** {H16243} Th
31d50 65 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f e [sqlite3_user_
31d60 64 61 74 61 28 43 29 5d 20 69 6e 74 65 72 66 61 data(C)] interfa
31d70 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 ce returns a cop
31d80 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 y of the.**
31d90 20 20 20 20 20 50 20 70 6f 69 6e 74 65 72 20 66 P pointer f
31da0 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 rom the [sqlite3
31db0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
31dc0 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c (D,X,N,E,P,F,S,L
31dd0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f )].** o
31de0 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 r [sqlite3_creat
31df0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 e_function16(D,X
31e00 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 ,N,E,P,F,S,L)] c
31e10 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 all that.**
31e20 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20 registered
31e30 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
31e40 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
31e50 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 [sqlite3_contex
31e60 74 5d 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 t] C..*/.void *s
31e70 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 qlite3_user_data
31e80 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
31e90 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
31ea0 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f REF: Database Co
31eb0 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e nnection For Fun
31ec0 63 74 69 6f 6e 73 20 7b 48 31 36 32 35 30 7d 20 ctions {H16250}
31ed0 3c 53 36 30 36 30 30 3e 3c 53 32 30 32 30 30 3e <S60600><S20200>
31ee0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
31ef0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 e3_context_db_ha
31f00 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 ndle() interface
31f10 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 returns a copy
31f20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 of.** the pointe
31f30 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 r to the [databa
31f40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 se connection] (
31f50 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 the 1st paramete
31f60 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 r).** of the [sq
31f70 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
31f80 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 ction()].** and
31f90 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
31fa0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f function16()] ro
31fb0 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 utines that orig
31fc0 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 inally.** regist
31fd0 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 ered the applica
31fe0 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e tion defined fun
31ff0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 ction..**.** INV
32000 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
32010 48 31 36 32 35 33 7d 20 54 68 65 20 5b 73 71 6c H16253} The [sql
32020 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f ite3_context_db_
32030 68 61 6e 64 6c 65 28 43 29 5d 20 69 6e 74 65 72 handle(C)] inter
32040 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 face returns a c
32050 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 opy of the.**
32060 20 20 20 20 20 20 20 44 20 70 6f 69 6e 74 65 72 D pointer
32070 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 from the [sqlit
32080 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
32090 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 on(D,X,N,E,P,F,S
320a0 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 ,L)].**
320b0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 or [sqlite3_cre
320c0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44 ate_function16(D
320d0 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d ,X,N,E,P,F,S,L)]
320e0 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 20 call that.**
320f0 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65 registere
32100 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 d the SQL functi
32110 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 on associated wi
32120 74 68 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 th [sqlite3_cont
32130 65 78 74 5d 20 43 2e 0a 2a 2f 0a 73 71 6c 69 74 ext] C..*/.sqlit
32140 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 e3 *sqlite3_cont
32150 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 ext_db_handle(sq
32160 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b lite3_context*);
32170 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
32180 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c : Function Auxil
32190 69 61 72 79 20 44 61 74 61 20 7b 48 31 36 32 37 iary Data {H1627
321a0 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 0} <S20200>.**.*
321b0 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 * The following
321c0 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 two functions ma
321d0 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61 y be used by sca
321e0 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e lar SQL function
321f0 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 s to.** associat
32200 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 e metadata with
32210 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e argument values.
32220 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c If the same val
32230 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a ue is passed to.
32240 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f ** multiple invo
32250 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 cations of the s
32260 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ame SQL function
32270 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 during query ex
32280 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a ecution, under.*
32290 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 * some circumsta
322a0 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 nces the associa
322b0 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 ted metadata may
322c0 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 be preserved. T
322d0 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 his may.** be us
322e0 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c ed, for example,
322f0 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 to add a regula
32300 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 r-expression mat
32310 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 ching scalar.**
32320 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f function. The co
32330 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f mpiled version o
32340 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 f the regular ex
32350 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 pression is stor
32360 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 ed as.** metadat
32370 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 a associated wit
32380 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 h the SQL value
32390 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65 passed as the re
323a0 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e gular expression
323b0 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 .** pattern. Th
323c0 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c e compiled regul
323d0 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 ar expression ca
323e0 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d n be reused on m
323f0 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 ultiple.** invoc
32400 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 ations of the sa
32410 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 me function so t
32420 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c hat the original
32430 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a pattern string.
32440 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 ** does not need
32450 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 to be recompile
32460 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 d on each invoca
32470 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 tion..**.** The
32480 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 sqlite3_get_auxd
32490 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 ata() interface
324a0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
324b0 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 r to the metadat
324c0 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 a.** associated
324d0 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 by the sqlite3_s
324e0 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e et_auxdata() fun
324f0 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e ction with the N
32500 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 th argument.** v
32510 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c alue to the appl
32520 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
32530 66 75 6e 63 74 69 6f 6e 2e 20 49 66 20 6e 6f 20 function. If no
32540 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65 metadata has bee
32550 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 n ever.** been s
32560 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 et for the Nth a
32570 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 rgument of the f
32580 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 unction, or if t
32590 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
325a0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 .** function par
325b0 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 ameter has chang
325c0 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 ed since the met
325d0 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a a-data was set,.
325e0 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f ** then sqlite3_
325f0 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 get_auxdata() re
32600 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 turns a NULL poi
32610 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 nter..**.** The
32620 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 sqlite3_set_auxd
32630 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 ata() interface
32640 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64 61 saves the metada
32650 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f ta.** pointed to
32660 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61 by its 3rd para
32670 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 meter as the met
32680 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d adata for the N-
32690 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f th.** argument o
326a0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
326b0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
326c0 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a on. Subsequent.
326d0 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 ** calls to sqli
326e0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 te3_get_auxdata(
326f0 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 ) might return t
32700 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 his data, if it
32710 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 has.** not been
32720 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 49 66 destroyed..** If
32730 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c it is not NULL,
32740 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 SQLite will inv
32750 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 oke the destruct
32760 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 or.** function g
32770 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 iven by the 4th
32780 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
32790 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 ite3_set_auxdata
327a0 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 () on.** the met
327b0 61 64 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 adata when the c
327c0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e orresponding fun
327d0 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 ction parameter
327e0 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 changes.** or wh
327f0 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 en the SQL state
32800 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 ment completes,
32810 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 whichever comes
32820 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c first..**.** SQL
32830 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 ite is free to c
32840 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 all the destruct
32850 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 or and drop meta
32860 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 data on any.** p
32870 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 arameter of any
32880 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 function at any
32890 74 69 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20 time. The only
328a0 67 75 61 72 61 6e 74 65 65 20 69 73 20 74 68 61 guarantee is tha
328b0 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63 t.** the destruc
328c0 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c tor will be call
328d0 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 ed before the me
328e0 74 61 64 61 74 61 20 69 73 20 64 72 6f 70 70 65 tadata is droppe
328f0 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 d..**.** In prac
32900 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 tice, metadata i
32910 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 s preserved betw
32920 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c een function cal
32930 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 ls for.** expres
32940 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 sions that are c
32950 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 onstant at compi
32960 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e le time. This in
32970 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a cludes literal.*
32980 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 53 51 4c * values and SQL
32990 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a variables..**.*
329a0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
329b0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 must be called
329c0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 from the same th
329d0 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a read in which.**
329e0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
329f0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a n is running..**
32a00 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
32a10 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 32 7d 20 54 **.** {H16272} T
32a20 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f he [sqlite3_get_
32a30 61 75 78 64 61 74 61 28 43 2c 4e 29 5d 20 69 6e auxdata(C,N)] in
32a40 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
32a50 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 a pointer.**
32a60 20 20 20 20 20 20 74 6f 20 6d 65 74 61 64 61 74 to metadat
32a70 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 a associated wit
32a80 68 20 74 68 65 20 4e 74 68 20 70 61 72 61 6d 65 h the Nth parame
32a90 74 65 72 20 6f 66 20 74 68 65 20 53 51 4c 20 66 ter of the SQL f
32aa0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 unction.**
32ab0 20 20 20 20 77 68 6f 73 65 20 63 6f 6e 74 65 78 whose contex
32ac0 74 20 69 73 20 43 2c 20 6f 72 20 4e 55 4c 4c 20 t is C, or NULL
32ad0 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d if there is no m
32ae0 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 etadata associat
32af0 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 ed.** w
32b00 69 74 68 20 74 68 61 74 20 70 61 72 61 6d 65 74 ith that paramet
32b10 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 er..**.** {H1627
32b20 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 4} The [sqlite3_
32b30 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c set_auxdata(C,N,
32b40 50 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 P,D)] interface
32b50 61 73 73 69 67 6e 73 20 61 20 6d 65 74 61 64 61 assigns a metada
32b60 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 ta.** p
32b70 6f 69 6e 74 65 72 20 50 20 74 6f 20 74 68 65 20 ointer P to the
32b80 4e 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 Nth parameter of
32b90 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
32ba0 6e 20 77 69 74 68 20 63 6f 6e 74 65 78 74 20 43 n with context C
32bb0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 36 7d ..**.** {H16276}
32bc0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 SQLite will inv
32bd0 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 oke the destruct
32be0 6f 72 20 44 20 77 69 74 68 20 61 20 73 69 6e 67 or D with a sing
32bf0 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 le argument.**
32c00 20 20 20 20 20 20 20 20 77 68 69 63 68 20 69 73 which is
32c10 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 70 6f the metadata po
32c20 69 6e 74 65 72 20 50 20 66 6f 6c 6c 6f 77 69 6e inter P followin
32c30 67 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 g a call to.**
32c40 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
32c50 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e _set_auxdata(C,N
32c60 2c 50 2c 44 29 5d 20 77 68 65 6e 20 53 51 4c 69 ,P,D)] when SQLi
32c70 74 65 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c te ceases to hol
32c80 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 d.** th
32c90 65 20 6d 65 74 61 64 61 74 61 2e 0a 2a 2a 0a 2a e metadata..**.*
32ca0 2a 20 7b 48 31 36 32 37 37 7d 20 53 51 4c 69 74 * {H16277} SQLit
32cb0 65 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64 e ceases to hold
32cc0 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 61 6e metadata for an
32cd0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 61 SQL function pa
32ce0 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 rameter.**
32cf0 20 20 20 20 77 68 65 6e 20 74 68 65 20 76 61 6c when the val
32d00 75 65 20 6f 66 20 74 68 61 74 20 70 61 72 61 6d ue of that param
32d10 65 74 65 72 20 63 68 61 6e 67 65 73 2e 0a 2a 2a eter changes..**
32d20 0a 2a 2a 20 7b 48 31 36 32 37 38 7d 20 57 68 65 .** {H16278} Whe
32d30 6e 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 n [sqlite3_set_a
32d40 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d uxdata(C,N,P,D)]
32d50 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 is invoked, the
32d60 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 20 destructor.**
32d70 20 20 20 20 20 20 20 20 69 73 20 63 61 6c 6c 65 is calle
32d80 64 20 66 6f 72 20 61 6e 79 20 70 72 69 6f 72 20 d for any prior
32d90 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 metadata associa
32da0 74 65 64 20 77 69 74 68 20 74 68 65 20 73 61 6d ted with the sam
32db0 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 e function.**
32dc0 20 20 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43 context C
32dd0 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20 4e and parameter N
32de0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 39 7d ..**.** {H16279}
32df0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 63 61 6c SQLite will cal
32e00 6c 20 64 65 73 74 72 75 63 74 6f 72 73 20 66 6f l destructors fo
32e10 72 20 61 6e 79 20 6d 65 74 61 64 61 74 61 20 69 r any metadata i
32e20 74 20 69 73 20 68 6f 6c 64 69 6e 67 0a 2a 2a 20 t is holding.**
32e30 20 20 20 20 20 20 20 20 20 69 6e 20 61 20 70 61 in a pa
32e40 72 74 69 63 75 6c 61 72 20 5b 70 72 65 70 61 72 rticular [prepar
32e50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 ed statement] S
32e60 77 68 65 6e 20 65 69 74 68 65 72 0a 2a 2a 20 20 when either.**
32e70 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
32e80 5f 72 65 73 65 74 28 53 29 5d 20 6f 72 20 5b 73 _reset(S)] or [s
32e90 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
32ea0 53 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a S)] is called..*
32eb0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f /.void *sqlite3_
32ec0 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 get_auxdata(sqli
32ed0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
32ee0 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 t N);.void sqlit
32ef0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 e3_set_auxdata(s
32f00 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
32f10 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 int N, void*, v
32f20 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b oid (*)(void*));
32f30 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 .../*.** CAPI3RE
32f40 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 F: Constants Def
32f50 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 ining Special De
32f60 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f structor Behavio
32f70 72 20 7b 48 31 30 32 38 30 7d 20 3c 53 33 30 31 r {H10280} <S301
32f80 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 00>.**.** These
32f90 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 are special valu
32fa0 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 es for the destr
32fb0 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 uctor that is pa
32fc0 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a ssed in as the.*
32fd0 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 * final argument
32fe0 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b to routines lik
32ff0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c e [sqlite3_resul
33000 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74 t_blob()]. If t
33010 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a he destructor.**
33020 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c argument is SQL
33030 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d ITE_STATIC, it m
33040 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f eans that the co
33050 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 ntent pointer is
33060 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 constant.** and
33070 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e will never chan
33080 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 ge. It does not
33090 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 need to be dest
330a0 72 6f 79 65 64 2e 20 20 54 68 65 0a 2a 2a 20 53 royed. The.** S
330b0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 QLITE_TRANSIENT
330c0 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 value means that
330d0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c the content wil
330e0 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 l likely change
330f0 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 in.** the near f
33100 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 uture and that S
33110 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b QLite should mak
33120 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 e its own privat
33130 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 e copy of.** the
33140 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 content before
33150 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a returning..**.**
33160 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20 The typedef is
33170 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 necessary to wor
33180 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d k around problem
33190 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 s in certain.**
331a0 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 C++ compilers.
331b0 53 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 See ticket #2191
331c0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 ..*/.typedef voi
331d0 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 d (*sqlite3_dest
331e0 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 ructor_type)(voi
331f0 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c d*);.#define SQL
33200 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 ITE_STATIC
33210 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 ((sqlite3_destru
33220 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 ctor_type)0).#de
33230 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e fine SQLITE_TRAN
33240 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 SIENT ((sqlite
33250 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 3_destructor_typ
33260 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 e)-1)../*.** CAP
33270 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 I3REF: Setting T
33280 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 he Result Of An
33290 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 7b 48 31 SQL Function {H1
332a0 36 34 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 6400} <S20200>.*
332b0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
332c0 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20 nes are used by
332d0 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 the xFunc or xFi
332e0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 nal callbacks th
332f0 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 at.** implement
33300 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e SQL functions an
33310 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 d aggregates. S
33320 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 ee.** [sqlite3_c
33330 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
33340 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 ] and [sqlite3_c
33350 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
33360 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 ()].** for addit
33370 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f ional informatio
33380 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 n..**.** These f
33390 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 unctions work ve
333a0 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 ry much like the
333b0 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 [parameter bind
333c0 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a ing] family of.*
333d0 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 * functions used
333e0 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 to bind values
333f0 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 to host paramete
33400 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 rs in prepared s
33410 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 tatements..** Re
33420 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 fer to the [SQL
33430 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d parameter] docum
33440 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 entation for add
33450 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 itional informat
33460 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ion..**.** The s
33470 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
33480 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 ob() interface s
33490 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 ets the result f
334a0 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 rom.** an applic
334b0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
334c0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 nction to be the
334d0 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 BLOB whose cont
334e0 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a ent is pointed.*
334f0 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f * to by the seco
33500 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 nd parameter and
33510 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 which is N byte
33520 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 s long where N i
33530 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 s the.** third p
33540 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 arameter..**.**
33550 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
33560 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e lt_zeroblob() in
33570 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65 terfaces set the
33580 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 result of.** th
33590 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
335a0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 fined function t
335b0 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 o be a BLOB cont
335c0 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a aining all zero.
335d0 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 ** bytes and N b
335e0 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 ytes in size, wh
335f0 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c ere N is the val
33600 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 ue of the 2nd pa
33610 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 rameter..**.** T
33620 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
33630 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 t_double() inter
33640 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 face sets the re
33650 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 sult from.** an
33660 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
33670 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 ned function to
33680 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f be a floating po
33690 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 int value specif
336a0 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e ied.** by its 2n
336b0 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a d argument..**.*
336c0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 * The sqlite3_re
336d0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 sult_error() and
336e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
336f0 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 error16() functi
33700 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 ons.** cause the
33710 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c implemented SQL
33720 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 function to thr
33730 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e ow an exception.
33740 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 .** SQLite uses
33750 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 the string point
33760 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 ed to by the.**
33770 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 2nd parameter of
33780 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
33790 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 error() or sqlit
337a0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 e3_result_error1
337b0 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 6().** as the te
337c0 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d xt of an error m
337d0 65 73 73 61 67 65 2e 20 20 53 51 4c 69 74 65 20 essage. SQLite
337e0 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 interprets the e
337f0 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 rror.** message
33800 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 string from sqli
33810 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
33820 28 29 20 61 73 20 55 54 46 2d 38 2e 20 53 51 4c () as UTF-8. SQL
33830 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 ite.** interpret
33840 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f s the string fro
33850 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 m sqlite3_result
33860 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 _error16() as UT
33870 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a F-16 in native.*
33880 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 49 * byte order. I
33890 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 f the third para
338a0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
338b0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a _result_error().
338c0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 ** or sqlite3_re
338d0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 sult_error16() i
338e0 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 s negative then
338f0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 SQLite takes as
33900 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 the error.** mes
33910 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 sage all text up
33920 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 through the fir
33930 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 st zero characte
33940 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 74 68 69 r..** If the thi
33950 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
33960 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
33970 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c rror() or.** sql
33980 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
33990 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 r16() is non-neg
339a0 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 ative then SQLit
339b0 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e e takes that man
339c0 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 y.** bytes (not
339d0 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d characters) from
339e0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
339f0 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 er as the error
33a00 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 54 68 65 20 message..** The
33a10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
33a20 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 rror() and sqlit
33a30 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 e3_result_error1
33a40 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6().** routines
33a50 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 make a private c
33a60 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 opy of the error
33a70 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65 message text be
33a80 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 fore.** they ret
33a90 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 urn. Hence, the
33aa0 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f calling functio
33ab0 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 n can deallocate
33ac0 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 or.** modify th
33ad0 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65 e text after the
33ae0 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 y return without
33af0 20 68 61 72 6d 2e 0a 2a 2a 20 54 68 65 20 73 71 harm..** The sq
33b00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
33b10 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 or_code() functi
33b20 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 on changes the e
33b30 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 rror code.** ret
33b40 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 urned by SQLite
33b50 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 as a result of a
33b60 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e n error in a fun
33b70 63 74 69 6f 6e 2e 20 20 42 79 20 64 65 66 61 75 ction. By defau
33b80 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 lt,.** the error
33b90 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f code is SQLITE_
33ba0 45 52 52 4f 52 2e 20 20 41 20 73 75 62 73 65 71 ERROR. A subseq
33bb0 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c uent call to sql
33bc0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
33bd0 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 r().** or sqlite
33be0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 3_result_error16
33bf0 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72 () resets the er
33c00 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 ror code to SQLI
33c10 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 TE_ERROR..**.**
33c20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
33c30 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 lt_toobig() inte
33c40 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c rface causes SQL
33c50 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 ite to throw an
33c60 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 error.** indicat
33c70 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e ing that a strin
33c80 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 20 g or BLOB is to
33c90 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e long to represen
33ca0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c t..**.** The sql
33cb0 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 ite3_result_nome
33cc0 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 m() interface ca
33cd0 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 uses SQLite to t
33ce0 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a hrow an error.**
33cf0 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 indicating that
33d00 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
33d10 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a tion failed..**.
33d20 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 ** The sqlite3_r
33d30 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 esult_int() inte
33d40 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 rface sets the r
33d50 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f eturn value.** o
33d60 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
33d70 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
33d80 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d on to be the 32-
33d90 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 bit signed integ
33da0 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 er.** value give
33db0 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 n in the 2nd arg
33dc0 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 71 ument..** The sq
33dd0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 lite3_result_int
33de0 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 64() interface s
33df0 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 ets the return v
33e00 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 alue.** of the a
33e10 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
33e20 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ed function to b
33e30 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 e the 64-bit sig
33e40 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 ned integer.** v
33e50 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 alue given in th
33e60 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a e 2nd argument..
33e70 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
33e80 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 3_result_null()
33e90 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 interface sets t
33ea0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a he return value.
33eb0 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 ** of the applic
33ec0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
33ed0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c nction to be NUL
33ee0 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c L..**.** The sql
33ef0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
33f00 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 (), sqlite3_resu
33f10 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 lt_text16(),.**
33f20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
33f30 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 ext16le(), and s
33f40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
33f50 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 xt16be() interfa
33f60 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 ces.** set the r
33f70 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 eturn value of t
33f80 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
33f90 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
33fa0 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 to be.** a text
33fb0 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 string which is
33fc0 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 represented as U
33fd0 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 TF-8, UTF-16 nat
33fe0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a ive byte order,.
33ff0 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 ** UTF-16 little
34000 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d endian, or UTF-
34010 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 16 big endian, r
34020 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 espectively..**
34030 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 SQLite takes the
34040 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f text result fro
34050 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f m the applicatio
34060 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e n from.** the 2n
34070 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 d parameter of t
34080 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
34090 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 t_text* interfac
340a0 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 es..** If the 3r
340b0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 d parameter to t
340c0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
340d0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 t_text* interfac
340e0 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 es.** is negativ
340f0 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 e, then SQLite t
34100 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 akes result text
34110 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 from the 2nd pa
34120 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 rameter.** throu
34130 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 gh the first zer
34140 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 o character..**
34150 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d If the 3rd param
34160 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 eter to the sqli
34170 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a te3_result_text*
34180 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 interfaces.** i
34190 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 s non-negative,
341a0 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 then as many byt
341b0 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 es (not characte
341c0 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a rs) of the text.
341d0 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 ** pointed to by
341e0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
341f0 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 er are taken as
34200 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
34210 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 defined.** funct
34220 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 ion result..** I
34230 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 f the 4th parame
34240 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ter to the sqlit
34250 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 e3_result_text*
34260 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 interfaces.** or
34270 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
34280 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 blob is a non-NU
34290 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e LL pointer, then
342a0 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 SQLite calls th
342b0 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 at.** function a
342c0 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 s the destructor
342d0 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 on the text or
342e0 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e BLOB result when
342f0 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 it has.** finis
34300 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 hed using that r
34310 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 esult..** If the
34320 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 4th parameter t
34330 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 o the sqlite3_re
34340 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 sult_text* inter
34350 66 61 63 65 73 20 6f 72 0a 2a 2a 20 73 71 6c 69 faces or.** sqli
34360 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 te3_result_blob
34370 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 is the special c
34380 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 onstant SQLITE_S
34390 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 TATIC, then SQLi
343a0 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 te.** assumes th
343b0 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 at the text or B
343c0 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e LOB result is in
343d0 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 constant space
343e0 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 and does not.**
343f0 63 6f 70 79 20 74 68 65 20 69 74 20 6f 72 20 63 copy the it or c
34400 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 all a destructor
34410 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e when it has fin
34420 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 ished using that
34430 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 result..** If t
34440 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 he 4th parameter
34450 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
34460 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 result_text* int
34470 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 erfaces.** or sq
34480 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f lite3_result_blo
34490 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c b is the special
344a0 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 constant SQLITE
344b0 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 _TRANSIENT.** th
344c0 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 en SQLite makes
344d0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 a copy of the re
344e0 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 sult into space
344f0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a obtained from.**
34500 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
34510 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 alloc()] before
34520 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a it returns..**.*
34530 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 * The sqlite3_re
34540 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 sult_value() int
34550 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 erface sets the
34560 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 result of.** the
34570 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
34580 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f ined function to
34590 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a be a copy the.*
345a0 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 * [unprotected s
345b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
345c0 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62 ject specified b
345d0 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 y the 2nd parame
345e0 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c ter. The.** sql
345f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 ite3_result_valu
34600 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 e() interface ma
34610 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 kes a copy of th
34620 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 e [sqlite3_value
34630 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 ].** so that the
34640 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d [sqlite3_value]
34650 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 specified in th
34660 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 e parameter may
34670 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 change or.** be
34680 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 deallocated afte
34690 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 r sqlite3_result
346a0 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 _value() returns
346b0 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a without harm..*
346c0 2a 20 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 * A [protected s
346d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
346e0 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 ject may always
346f0 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e be used where an
34700 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 .** [unprotected
34710 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
34720 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 object is requir
34730 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a ed, so either.**
34740 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 kind of [sqlite
34750 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
34760 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 can be used with
34770 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e this interface.
34780 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 .**.** If these
34790 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c routines are cal
347a0 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 led from within
347b0 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 the different th
347c0 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 read.** than the
347d0 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 one containing
347e0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
347f0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
34800 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a that received.*
34810 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 * the [sqlite3_c
34820 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c ontext] pointer,
34830 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 the results are
34840 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
34850 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
34860 0a 2a 2a 20 7b 48 31 36 34 30 33 7d 20 54 68 65 .** {H16403} The
34870 20 64 65 66 61 75 6c 74 20 72 65 74 75 72 6e 20 default return
34880 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 79 20 53 value from any S
34890 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 4e QL function is N
348a0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 ULL..**.** {H164
348b0 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 06} The [sqlite3
348c0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 _result_blob(C,V
348d0 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 ,N,D)] interface
348e0 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 changes the.**
348f0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 return
34900 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f value of functio
34910 6e 20 43 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 n C to be a BLOB
34920 20 74 68 61 74 20 69 73 20 4e 20 62 79 74 65 73 that is N bytes
34930 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 .** in
34940 6c 65 6e 67 74 68 20 61 6e 64 20 77 69 74 68 20 length and with
34950 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 64 20 content pointed
34960 74 6f 20 62 79 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b to by V..**.** {
34970 48 31 36 34 30 39 7d 20 54 68 65 20 5b 73 71 6c H16409} The [sql
34980 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 ite3_result_doub
34990 6c 65 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 le(C,V)] interfa
349a0 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a ce changes the.*
349b0 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 * retur
349c0 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 n value of funct
349d0 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 ion C to be the
349e0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 floating point v
349f0 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 alue V..**.** {H
34a00 31 36 34 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 16412} The [sqli
34a10 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
34a20 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61 (C,V,N)] interfa
34a30 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 ce changes the r
34a40 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 eturn.**
34a50 20 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 value of funct
34a60 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 ion C to be an e
34a70 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 xception with er
34a80 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 ror code.**
34a90 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 [SQLITE_ERR
34aa0 4f 52 5d 20 61 6e 64 20 61 20 55 54 46 2d 38 20 OR] and a UTF-8
34ab0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 63 6f error message co
34ac0 70 69 65 64 20 66 72 6f 6d 20 56 20 75 70 20 74 pied from V up t
34ad0 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 o the.**
34ae0 20 20 66 69 72 73 74 20 7a 65 72 6f 20 62 79 74 first zero byt
34af0 65 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 e or until N byt
34b00 65 73 20 61 72 65 20 72 65 61 64 20 69 66 20 4e es are read if N
34b10 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a is positive..**
34b20 0a 2a 2a 20 7b 48 31 36 34 31 35 7d 20 54 68 65 .** {H16415} The
34b30 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
34b40 5f 65 72 72 6f 72 31 36 28 43 2c 56 2c 4e 29 5d _error16(C,V,N)]
34b50 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 interface chang
34b60 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a es the return.**
34b70 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 value
34b80 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f of function C to
34b90 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e be an exception
34ba0 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 with error code
34bb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 .** [SQ
34bc0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20 LITE_ERROR] and
34bd0 61 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 a UTF-16 native
34be0 62 79 74 65 20 6f 72 64 65 72 20 65 72 72 6f 72 byte order error
34bf0 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 message.**
34c00 20 20 20 20 20 63 6f 70 69 65 64 20 66 72 6f 6d copied from
34c10 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 V up to the fir
34c20 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 st zero terminat
34c30 6f 72 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 or or until N by
34c40 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 tes.**
34c50 61 72 65 20 72 65 61 64 20 69 66 20 4e 20 69 73 are read if N is
34c60 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a positive..**.**
34c70 20 7b 48 31 36 34 31 38 7d 20 54 68 65 20 5b 73 {H16418} The [s
34c80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
34c90 72 6f 72 5f 74 6f 6f 62 69 67 28 43 29 5d 20 69 ror_toobig(C)] i
34ca0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 nterface changes
34cb0 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 the return.**
34cc0 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 value of
34cd0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 the function C
34ce0 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 to be an excepti
34cf0 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f on with error co
34d00 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b de.** [
34d10 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 61 SQLITE_TOOBIG] a
34d20 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 nd an appropriat
34d30 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e e error message.
34d40 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32 31 7d 20 .**.** {H16421}
34d50 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 The [sqlite3_res
34d60 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 ult_error_nomem(
34d70 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 C)] interface ch
34d80 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e anges the return
34d90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c .** val
34da0 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 ue of the functi
34db0 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 on C to be an ex
34dc0 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 ception with err
34dd0 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 or code.**
34de0 20 20 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 [SQLITE_NOME
34df0 4d 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 M] and an approp
34e00 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 riate error mess
34e10 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 age..**.** {H164
34e20 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 24} The [sqlite3
34e30 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f _result_error_co
34e40 64 65 28 43 2c 45 29 5d 20 69 6e 74 65 72 66 61 de(C,E)] interfa
34e50 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 ce changes the r
34e60 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 eturn.**
34e70 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 value of the f
34e80 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 unction C to be
34e90 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 an exception wit
34ea0 68 20 65 72 72 6f 72 20 63 6f 64 65 20 45 2e 0a h error code E..
34eb0 2a 2a 20 20 20 20 20 20 20 20 20 20 54 68 65 20 ** The
34ec0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 error message te
34ed0 78 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e xt is unchanged.
34ee0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32 37 7d 20 .**.** {H16427}
34ef0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 The [sqlite3_res
34f00 75 6c 74 5f 69 6e 74 28 43 2c 56 29 5d 20 69 6e ult_int(C,V)] in
34f10 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 terface changes
34f20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
34f30 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 return value of
34f40 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 function C to be
34f50 20 74 68 65 20 33 32 2d 62 69 74 20 69 6e 74 65 the 32-bit inte
34f60 67 65 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a ger value V..**.
34f70 2a 2a 20 7b 48 31 36 34 33 30 7d 20 54 68 65 20 ** {H16430} The
34f80 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
34f90 69 6e 74 36 34 28 43 2c 56 29 5d 20 69 6e 74 65 int64(C,V)] inte
34fa0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 rface changes th
34fb0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 e.** re
34fc0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 turn value of fu
34fd0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 nction C to be t
34fe0 68 65 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 he 64-bit intege
34ff0 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a r value V..**.**
35000 20 7b 48 31 36 34 33 33 7d 20 54 68 65 20 5b 73 {H16433} The [s
35010 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 qlite3_result_nu
35020 6c 6c 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 ll(C)] interface
35030 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 changes the.**
35040 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 return
35050 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f value of functio
35060 6e 20 43 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a n C to be NULL..
35070 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 36 7d 20 54 **.** {H16436} T
35080 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 he [sqlite3_resu
35090 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 lt_text(C,V,N,D)
350a0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e ] interface chan
350b0 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 ges the.**
350c0 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 return value
350d0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 of function C t
350e0 6f 20 62 65 20 74 68 65 20 55 54 46 2d 38 20 73 o be the UTF-8 s
350f0 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 tring.**
35100 20 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 V up to the fi
35110 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 rst zero if N is
35120 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 negative.**
35130 20 20 20 20 20 20 6f 72 20 74 68 65 20 66 69 72 or the fir
35140 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 st N bytes of V
35150 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 if N is non-nega
35160 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 tive..**.** {H16
35170 34 33 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 439} The [sqlite
35180 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 3_result_text16(
35190 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 C,V,N,D)] interf
351a0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a ace changes the.
351b0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 ** retu
351c0 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 rn value of func
351d0 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 tion C to be the
351e0 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 UTF-16 native b
351f0 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 yte order.**
35200 20 20 20 20 20 20 73 74 72 69 6e 67 20 56 20 75 string V u
35210 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a p to the first z
35220 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61 ero if N is nega
35230 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 tive.**
35240 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 or the first N
35250 62 79 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20 bytes of V if N
35260 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e is non-negative.
35270 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 32 7d 20 .**.** {H16442}
35280 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 The [sqlite3_res
35290 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 ult_text16be(C,V
352a0 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 ,N,D)] interface
352b0 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 changes the.**
352c0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 return
352d0 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f value of functio
352e0 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 n C to be the UT
352f0 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a F-16 big-endian.
35300 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 ** stri
35310 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 ng V up to the f
35320 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 irst zero if N i
35330 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 s negative.**
35340 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 66 69 or the fi
35350 72 73 74 20 4e 20 62 79 74 65 73 20 6f 72 20 56 rst N bytes or V
35360 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 if N is non-neg
35370 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ative..**.** {H1
35380 36 34 34 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 6445} The [sqlit
35390 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
353a0 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 le(C,V,N,D)] int
353b0 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 erface changes t
353c0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 he.** r
353d0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 eturn value of f
353e0 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 unction C to be
353f0 74 68 65 20 55 54 46 2d 31 36 20 6c 69 74 74 6c the UTF-16 littl
35400 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 e-endian.**
35410 20 20 20 20 20 73 74 72 69 6e 67 20 56 20 75 70 string V up
35420 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 to the first ze
35430 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 ro if N is negat
35440 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ive.**
35450 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 or the first N b
35460 79 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69 ytes of V if N i
35470 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a s non-negative..
35480 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 38 7d 20 54 **.** {H16448} T
35490 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 he [sqlite3_resu
354a0 6c 74 5f 76 61 6c 75 65 28 43 2c 56 29 5d 20 69 lt_value(C,V)] i
354b0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 nterface changes
354c0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
354d0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 return value of
354e0 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 function C to b
354f0 65 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 e the [unprotect
35500 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
35510 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 ].** ob
35520 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ject V..**.** {H
35530 31 36 34 35 31 7d 20 54 68 65 20 5b 73 71 6c 69 16451} The [sqli
35540 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 te3_result_zerob
35550 6c 6f 62 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66 lob(C,N)] interf
35560 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a ace changes the.
35570 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 ** retu
35580 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 rn value of func
35590 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 tion C to be an
355a0 4e 2d 62 79 74 65 20 42 4c 4f 42 20 6f 66 20 61 N-byte BLOB of a
355b0 6c 6c 20 7a 65 72 6f 73 2e 0a 2a 2a 0a 2a 2a 20 ll zeros..**.**
355c0 7b 48 31 36 34 35 34 7d 20 54 68 65 20 5b 73 71 {H16454} The [sq
355d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
355e0 6f 72 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 or()] and [sqlit
355f0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 e3_result_error1
35600 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 6()].**
35610 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b 65 interfaces make
35620 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 69 72 a copy of their
35630 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 error message s
35640 74 72 69 6e 67 73 20 62 65 66 6f 72 65 0a 2a 2a trings before.**
35650 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e return
35660 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 ing..**.** {H164
35670 35 37 7d 20 49 66 20 74 68 65 20 44 20 64 65 73 57} If the D des
35680 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65 tructor paramete
35690 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 r to [sqlite3_re
356a0 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c sult_blob(C,V,N,
356b0 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 D)],.**
356c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
356d0 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c _text(C,V,N,D)],
356e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
356f0 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 _text16(C,V,N,D)
35700 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b ],.** [
35710 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
35720 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 ext16be(C,V,N,D)
35730 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 ], or.**
35740 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c [sqlite3_resul
35750 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e t_text16le(C,V,N
35760 2c 44 29 5d 20 69 73 20 74 68 65 20 63 6f 6e 73 ,D)] is the cons
35770 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 41 tant [SQLITE_STA
35780 54 49 43 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 TIC].**
35790 20 74 68 65 6e 20 6e 6f 20 64 65 73 74 72 75 63 then no destruc
357a0 74 6f 72 20 69 73 20 65 76 65 72 20 63 61 6c 6c tor is ever call
357b0 65 64 20 6f 6e 20 74 68 65 20 70 6f 69 6e 74 65 ed on the pointe
357c0 72 20 56 20 61 6e 64 20 53 51 4c 69 74 65 0a 2a r V and SQLite.*
357d0 2a 20 20 20 20 20 20 20 20 20 20 61 73 73 75 6d * assum
357e0 65 73 20 74 68 61 74 20 56 20 69 73 20 69 6d 6d es that V is imm
357f0 75 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 utable..**.** {H
35800 31 36 34 36 30 7d 20 49 66 20 74 68 65 20 44 20 16460} If the D
35810 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d destructor param
35820 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 eter to [sqlite3
35830 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 _result_blob(C,V
35840 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 ,N,D)],.**
35850 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 [sqlite3_res
35860 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 ult_text(C,V,N,D
35870 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 )], [sqlite3_res
35880 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e ult_text16(C,V,N
35890 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 ,D)],.**
358a0 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c [sqlite3_resul
358b0 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e t_text16be(C,V,N
358c0 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 ,D)], or.**
358d0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 [sqlite3_re
358e0 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c sult_text16le(C,
358f0 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65 20 63 V,N,D)] is the c
35900 6f 6e 73 74 61 6e 74 0a 2a 2a 20 20 20 20 20 20 onstant.**
35910 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e [SQLITE_TRAN
35920 53 49 45 4e 54 5d 20 74 68 65 6e 20 74 68 65 20 SIENT] then the
35930 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b 65 73 interfaces makes
35940 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a a copy of the.*
35950 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 * conte
35960 6e 74 20 6f 66 20 56 20 61 6e 64 20 72 65 74 61 nt of V and reta
35970 69 6e 73 20 74 68 65 20 63 6f 70 79 2e 0a 2a 2a ins the copy..**
35980 0a 2a 2a 20 7b 48 31 36 34 36 33 7d 20 49 66 20 .** {H16463} If
35990 74 68 65 20 44 20 64 65 73 74 72 75 63 74 6f 72 the D destructor
359a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 parameter to [s
359b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
359c0 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a ob(C,V,N,D)],.**
359d0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
359e0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 e3_result_text(C
359f0 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 ,V,N,D)], [sqlit
35a00 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
35a10 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 (C,V,N,D)],.**
35a20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
35a30 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 _result_text16be
35a40 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a (C,V,N,D)], or.*
35a50 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
35a60 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 te3_result_text1
35a70 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 6le(C,V,N,D)] is
35a80 20 73 6f 6d 65 20 76 61 6c 75 65 20 6f 74 68 65 some value othe
35a90 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 r than.**
35aa0 20 20 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 the constants
35ab0 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d [SQLITE_STATIC]
35ac0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 54 52 41 and [SQLITE_TRA
35ad0 4e 53 49 45 4e 54 5d 20 74 68 65 6e 0a 2a 2a 20 NSIENT] then.**
35ae0 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 SQLite
35af0 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 will invoke the
35b00 64 65 73 74 72 75 63 74 6f 72 20 44 20 77 69 74 destructor D wit
35b10 68 20 56 20 61 73 20 69 74 73 20 6f 6e 6c 79 20 h V as its only
35b20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 argument.**
35b30 20 20 20 20 20 77 68 65 6e 20 69 74 20 68 61 73 when it has
35b40 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 finished with t
35b50 68 65 20 56 20 76 61 6c 75 65 2e 0a 2a 2f 0a 76 he V value..*/.v
35b60 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
35b70 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f lt_blob(sqlite3_
35b80 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
35b90 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 void*, int, void
35ba0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 (*)(void*));.voi
35bb0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
35bc0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f _double(sqlite3_
35bd0 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 context*, double
35be0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
35bf0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c result_error(sql
35c00 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 ite3_context*, c
35c10 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 onst char*, int)
35c20 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
35c30 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 esult_error16(sq
35c40 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
35c50 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
35c60 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
35c70 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f result_error_too
35c80 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 big(sqlite3_cont
35c90 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 ext*);.void sqli
35ca0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
35cb0 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 _nomem(sqlite3_c
35cc0 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 ontext*);.void s
35cd0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
35ce0 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 ror_code(sqlite3
35cf0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b _context*, int);
35d00 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
35d10 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 sult_int(sqlite3
35d20 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b _context*, int);
35d30 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
35d40 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 sult_int64(sqlit
35d50 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c e3_context*, sql
35d60 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 ite3_int64);.voi
35d70 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
35d80 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f _null(sqlite3_co
35d90 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 ntext*);.void sq
35da0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
35db0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 t(sqlite3_contex
35dc0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c t*, const char*,
35dd0 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f int, void(*)(vo
35de0 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 id*));.void sqli
35df0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 te3_result_text1
35e00 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 6(sqlite3_contex
35e10 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c t*, const void*,
35e20 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f int, void(*)(vo
35e30 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 id*));.void sqli
35e40 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 te3_result_text1
35e50 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 6le(sqlite3_cont
35e60 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 ext*, const void
35e70 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 *, int,void(*)(v
35e80 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c oid*));.void sql
35e90 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
35ea0 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 16be(sqlite3_con
35eb0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 text*, const voi
35ec0 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 d*, int,void(*)(
35ed0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 void*));.void sq
35ee0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c lite3_result_val
35ef0 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ue(sqlite3_conte
35f00 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c xt*, sqlite3_val
35f10 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 ue*);.void sqlit
35f20 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c e3_result_zerobl
35f30 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ob(sqlite3_conte
35f40 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a xt*, int n);../*
35f50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
35f60 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 fine New Collati
35f70 6e 67 20 53 65 71 75 65 6e 63 65 73 20 7b 48 31 ng Sequences {H1
35f80 36 36 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 6600} <S20300>.*
35f90 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 *.** These funct
35fa0 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f ions are used to
35fb0 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 add new collati
35fc0 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20 on sequences to
35fd0 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 the.** [database
35fe0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 connection] spe
35ff0 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 cified as the fi
36000 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a rst argument..**
36010 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 .** The name of
36020 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f the new collatio
36030 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 73 70 n sequence is sp
36040 65 63 69 66 69 65 64 20 61 73 20 61 20 55 54 46 ecified as a UTF
36050 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 -8 string.** for
36060 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
36070 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 collation() and
36080 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
36090 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a ollation_v2().**
360a0 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 and a UTF-16 st
360b0 72 69 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33 ring for sqlite3
360c0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
360d0 6e 31 36 28 29 2e 20 49 6e 20 61 6c 6c 20 63 61 n16(). In all ca
360e0 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 ses.** the name
360f0 69 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 is passed as the
36100 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e second function
36110 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a argument..**.**
36120 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d The third argum
36130 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f ent may be one o
36140 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 f the constants
36150 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a [SQLITE_UTF8],.*
36160 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c * [SQLITE_UTF16L
36170 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 E] or [SQLITE_UT
36180 46 31 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 F16BE], indicati
36190 6e 67 20 74 68 61 74 20 74 68 65 20 75 73 65 72 ng that the user
361a0 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 -supplied.** rou
361b0 74 69 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20 tine expects to
361c0 62 65 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65 be passed pointe
361d0 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e rs to strings en
361e0 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d coded using UTF-
361f0 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 8,.** UTF-16 lit
36200 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20 55 tle-endian, or U
36210 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e TF-16 big-endian
36220 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 , respectively.
36230 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67 The.** third arg
36240 75 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f ument might also
36250 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 be [SQLITE_UTF1
36260 36 5f 41 4c 49 47 4e 45 44 5d 20 74 6f 20 69 6e 6_ALIGNED] to in
36270 64 69 63 61 74 65 20 74 68 61 74 0a 2a 2a 20 74 dicate that.** t
36280 68 65 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 he routine expec
36290 74 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 ts pointers to 1
362a0 36 2d 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 6-bit word align
362b0 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 ed strings.** of
362c0 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e UTF-16 in the n
362d0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
362e0 20 6f 66 20 74 68 65 20 68 6f 73 74 20 63 6f 6d of the host com
362f0 70 75 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 puter..**.** A p
36300 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75 73 ointer to the us
36310 65 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75 74 er supplied rout
36320 69 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73 73 ine must be pass
36330 65 64 20 61 73 20 74 68 65 20 66 69 66 74 68 0a ed as the fifth.
36340 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 ** argument. If
36350 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 it is NULL, thi
36360 73 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 s is the same as
36370 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f deleting the co
36380 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 llation.** seque
36390 6e 63 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c nce (so that SQL
363a0 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 ite cannot call
363b0 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20 it anymore)..**
363c0 45 61 63 68 20 74 69 6d 65 20 74 68 65 20 61 70 Each time the ap
363d0 70 6c 69 63 61 74 69 6f 6e 20 73 75 70 70 6c 69 plication suppli
363e0 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 ed function is i
363f0 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61 nvoked, it is pa
36400 73 73 65 64 0a 2a 2a 20 61 73 20 69 74 73 20 66 ssed.** as its f
36410 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 61 irst parameter a
36420 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 copy of the voi
36430 64 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65 d* passed as the
36440 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 fourth argument
36450 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 .** to sqlite3_c
36460 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 reate_collation(
36470 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 ) or sqlite3_cre
36480 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 ate_collation16(
36490 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d )..**.** The rem
364a0 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 aining arguments
364b0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 to the applicat
364c0 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 ion-supplied rou
364d0 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74 72 tine are two str
364e0 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 ings,.** each re
364f0 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 28 presented by a (
36500 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 20 70 61 length, data) pa
36510 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 ir and encoded i
36520 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a n the encoding.*
36530 2a 20 74 68 61 74 20 77 61 73 20 70 61 73 73 65 * that was passe
36540 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 61 d as the third a
36550 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 rgument when the
36560 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 collation seque
36570 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 nce was.** regis
36580 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20 20 54 68 tered. {END} Th
36590 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 e application de
365a0 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 fined collation
365b0 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a 2a routine should.*
365c0 2a 20 72 65 74 75 72 6e 20 6e 65 67 61 74 69 76 * return negativ
365d0 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74 e, zero or posit
365e0 69 76 65 20 69 66 20 74 68 65 20 66 69 72 73 74 ive if the first
365f0 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 string is less
36600 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61 6c 20 74 than,.** equal t
36610 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 o, or greater th
36620 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 20 73 74 an the second st
36630 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52 49 ring. i.e. (STRI
36640 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a NG1 - STRING2)..
36650 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
36660 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
36670 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 on_v2() works li
36680 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 ke sqlite3_creat
36690 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a e_collation().**
366a0 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 except that it
366b0 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61 20 61 takes an extra a
366c0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
366d0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f a destructor fo
366e0 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 r.** the collati
366f0 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 on. The destruc
36700 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68 tor is called wh
36710 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e en the collation
36720 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64 is.** destroyed
36730 20 61 6e 64 20 69 73 20 70 61 73 73 65 64 20 61 and is passed a
36740 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75 copy of the fou
36750 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f rth parameter vo
36760 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f id* pointer.** o
36770 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 f the sqlite3_cr
36780 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 eate_collation_v
36790 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74 69 6f 2()..** Collatio
367a0 6e 73 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 ns are destroyed
367b0 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f when they are o
367c0 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 verridden by lat
367d0 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a er calls to the.
367e0 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 ** collation cre
367f0 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 ation functions
36800 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 64 61 74 or when the [dat
36810 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
36820 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20 75 ] is closed.** u
36830 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c sing [sqlite3_cl
36840 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e ose()]..**.** IN
36850 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
36860 7b 48 31 36 36 30 33 7d 20 41 20 73 75 63 63 65 {H16603} A succe
36870 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 74 68 ssful call to th
36880 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 e.** [s
36890 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
368a0 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 llation_v2(B,X,E
368b0 2c 50 2c 46 2c 44 29 5d 20 69 6e 74 65 72 66 61 ,P,F,D)] interfa
368c0 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 ce.** r
368d0 65 67 69 73 74 65 72 73 20 66 75 6e 63 74 69 6f egisters functio
368e0 6e 20 46 20 61 73 20 74 68 65 20 63 6f 6d 70 61 n F as the compa
368f0 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 75 rison function u
36900 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 sed to.**
36910 20 20 20 69 6d 70 6c 65 6d 65 6e 74 20 63 6f 6c implement col
36920 6c 61 74 69 6f 6e 20 58 20 6f 6e 20 74 68 65 20 lation X on the
36930 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
36940 74 69 6f 6e 5d 20 42 20 66 6f 72 0a 2a 2a 20 20 tion] B for.**
36950 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65 database
36960 73 20 68 61 76 69 6e 67 20 65 6e 63 6f 64 69 6e s having encodin
36970 67 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 g E..**.** {H166
36980 30 34 7d 20 53 51 4c 69 74 65 20 75 6e 64 65 72 04} SQLite under
36990 73 74 61 6e 64 73 20 74 68 65 20 58 20 70 61 72 stands the X par
369a0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 ameter to.**
369b0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 [sqlite3_c
369c0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f reate_collation_
369d0 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d v2(B,X,E,P,F,D)]
369e0 20 61 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 as a zero-termi
369f0 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 nated.**
36a00 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 69 UTF-8 string i
36a10 6e 20 77 68 69 63 68 20 63 61 73 65 20 69 73 20 n which case is
36a20 69 67 6e 6f 72 65 64 20 66 6f 72 20 41 53 43 49 ignored for ASCI
36a30 49 20 63 68 61 72 61 63 74 65 72 73 20 61 6e 64 I characters and
36a40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 .** is
36a50 73 69 67 6e 69 66 69 63 61 6e 74 20 66 6f 72 20 significant for
36a60 6e 6f 6e 2d 41 53 43 49 49 20 63 68 61 72 61 63 non-ASCII charac
36a70 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 ters..**.** {H16
36a80 36 30 36 7d 20 53 75 63 63 65 73 73 69 76 65 20 606} Successive
36a90 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
36aa0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
36ab0 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c on_v2(B,X,E,P,F,
36ac0 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 D)].**
36ad0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 76 61 with the same va
36ae0 6c 75 65 73 20 66 6f 72 20 42 2c 20 58 2c 20 61 lues for B, X, a
36af0 6e 64 20 45 2c 20 6f 76 65 72 72 69 64 65 20 70 nd E, override p
36b00 72 69 6f 72 20 76 61 6c 75 65 73 0a 2a 2a 20 20 rior values.**
36b10 20 20 20 20 20 20 20 20 6f 66 20 50 2c 20 46 2c of P, F,
36b20 20 61 6e 64 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 and D..**.** {H
36b30 31 36 36 30 39 7d 20 49 66 20 74 68 65 20 64 65 16609} If the de
36b40 73 74 72 75 63 74 6f 72 20 44 20 69 6e 20 5b 73 structor D in [s
36b50 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
36b60 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 llation_v2(B,X,E
36b70 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 ,P,F,D)].**
36b80 20 20 20 20 20 69 73 20 6e 6f 74 20 4e 55 4c 4c is not NULL
36b90 20 74 68 65 6e 20 69 74 20 69 73 20 63 61 6c 6c then it is call
36ba0 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 ed with argument
36bb0 20 50 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 20 P when the.**
36bc0 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e collatin
36bd0 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 g function is dr
36be0 6f 70 70 65 64 20 62 79 20 53 51 4c 69 74 65 2e opped by SQLite.
36bf0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31 32 7d 20 .**.** {H16612}
36c00 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 A collating func
36c10 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20 tion is dropped
36c20 77 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 6c when it is overl
36c30 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 oaded..**.** {H1
36c40 36 36 31 35 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 6615} A collatin
36c50 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 g function is dr
36c60 6f 70 70 65 64 20 77 68 65 6e 20 74 68 65 20 64 opped when the d
36c70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
36c80 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 on.** i
36c90 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b s closed using [
36ca0 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d sqlite3_close()]
36cb0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31 38 7d ..**.** {H16618}
36cc0 20 54 68 65 20 70 6f 69 6e 74 65 72 20 50 20 69 The pointer P i
36cd0 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 n [sqlite3_creat
36ce0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 e_collation_v2(B
36cf0 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 ,X,E,P,F,D)].**
36d00 20 20 20 20 20 20 20 20 20 69 73 20 70 61 73 73 is pass
36d10 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 ed through as th
36d20 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
36d30 72 20 74 6f 20 74 68 65 20 63 6f 6d 70 61 72 69 r to the compari
36d40 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 son.**
36d50 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20 61 function F for a
36d60 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e ll subsequent in
36d70 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 46 2e 0a vocations of F..
36d80 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 31 7d 20 41 **.** {H16621} A
36d90 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
36da0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
36db0 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 69 on(B,X,E,P,F)] i
36dc0 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20 s exactly.**
36dd0 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 61 the same a
36de0 73 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c s a call to [sql
36df0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
36e00 61 74 69 6f 6e 5f 76 32 28 29 5d 20 77 69 74 68 ation_v2()] with
36e10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
36e20 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65 72 73 same parameters
36e30 20 61 6e 64 20 61 20 4e 55 4c 4c 20 64 65 73 74 and a NULL dest
36e40 72 75 63 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ructor..**.** {H
36e50 31 36 36 32 34 7d 20 46 6f 6c 6c 6f 77 69 6e 67 16624} Following
36e60 20 61 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 a [sqlite3_crea
36e70 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 te_collation_v2(
36e80 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 2c 0a 2a B,X,E,P,F,D)],.*
36e90 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 * SQLit
36ea0 65 20 75 73 65 73 20 74 68 65 20 63 6f 6d 70 61 e uses the compa
36eb0 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 46 rison function F
36ec0 20 66 6f 72 20 61 6c 6c 20 74 65 78 74 20 63 6f for all text co
36ed0 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 mparison.**
36ee0 20 20 20 20 20 6f 70 65 72 61 74 69 6f 6e 73 20 operations
36ef0 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 on the [database
36f00 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20 6f connection] B o
36f10 6e 20 74 65 78 74 20 76 61 6c 75 65 73 20 74 68 n text values th
36f20 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 at.** u
36f30 73 65 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 se the collating
36f40 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 64 20 sequence named
36f50 58 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 37 X..**.** {H16627
36f60 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 } The [sqlite3_c
36f70 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 reate_collation1
36f80 36 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 77 6f 6(B,X,E,P,F)] wo
36f90 72 6b 73 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 rks the same.**
36fa0 20 20 20 20 20 20 20 20 20 61 73 20 5b 73 71 6c as [sql
36fb0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
36fc0 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29 ation(B,X,E,P,F)
36fd0 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 ] except that th
36fe0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f e.** co
36ff0 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69 llation name X i
37000 73 20 75 6e 64 65 72 73 74 6f 6f 64 20 61 73 20 s understood as
37010 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 UTF-16 in native
37020 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 byte order.**
37030 20 20 20 20 20 20 20 20 69 6e 73 74 65 61 64 20 instead
37040 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 of UTF-8..**.**
37050 7b 48 31 36 36 33 30 7d 20 57 68 65 6e 20 6d 75 {H16630} When mu
37060 6c 74 69 70 6c 65 20 63 6f 6d 70 61 72 69 73 6f ltiple compariso
37070 6e 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 n functions are
37080 61 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 74 68 available for th
37090 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 e same.**
370a0 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 collating seq
370b0 75 65 6e 63 65 2c 20 53 51 4c 69 74 65 20 63 68 uence, SQLite ch
370c0 6f 6f 73 65 73 20 74 68 65 20 6f 6e 65 20 77 68 ooses the one wh
370d0 6f 73 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e ose text encodin
370e0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 g.** re
370f0 71 75 69 72 65 73 20 74 68 65 20 6c 65 61 73 74 quires the least
37100 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 76 65 amount of conve
37110 72 73 69 6f 6e 20 66 72 6f 6d 20 74 68 65 20 64 rsion from the d
37120 65 66 61 75 6c 74 0a 2a 2a 20 20 20 20 20 20 20 efault.**
37130 20 20 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 text encoding
37140 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
37150 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
37160 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
37170 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a n(. sqlite3*, .
37180 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e const char *zN
37190 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 ame, . int eTex
371a0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a tRep, . void*,.
371b0 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 int(*xCompare)
371c0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 (void*,int,const
371d0 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 void*,int,const
371e0 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 void*).);.int s
371f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
37200 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 llation_v2(. sq
37210 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 lite3*, . const
37220 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 char *zName, .
37230 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a int eTextRep, .
37240 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a void*,. int(*
37250 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c xCompare)(void*,
37260 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c int,const void*,
37270 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 int,const void*)
37280 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 ,. void(*xDestr
37290 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e oy)(void*).);.in
372a0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
372b0 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 _collation16(.
372c0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e sqlite3*, . con
372d0 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a st void *zName,.
372e0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 int eTextRep,
372f0 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 . void*,. int(
37300 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a *xCompare)(void*
37310 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a ,int,const void*
37320 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a ,int,const void*
37330 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ).);../*.** CAPI
37340 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 3REF: Collation
37350 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 Needed Callbacks
37360 20 7b 48 31 36 37 30 30 7d 20 3c 53 32 30 33 30 {H16700} <S2030
37370 30 3e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 0>.**.** To avoi
37380 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 d having to regi
37390 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 ster all collati
373a0 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 on sequences bef
373b0 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a ore a database.*
373c0 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 * can be used, a
373d0 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b single callback
373e0 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 function may be
373f0 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 registered with
37400 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 the.** [databas
37410 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f e connection] to
37420 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 be called whene
37430 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 ver an undefined
37440 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 collation.** se
37450 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 quence is requir
37460 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 ed..**.** If the
37470 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 function is reg
37480 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 istered using th
37490 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 e sqlite3_collat
374a0 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 ion_needed() API
374b0 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 ,.** then it is
374c0 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 passed the names
374d0 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f of undefined co
374e0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 llation sequence
374f0 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 s as strings.**
37500 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 encoded in UTF-8
37510 2e 20 7b 48 31 36 37 30 33 7d 20 49 66 20 73 71 . {H16703} If sq
37520 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
37530 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73 needed16() is us
37540 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 ed,.** the names
37550 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55 are passed as U
37560 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 TF-16 in machine
37570 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
37580 65 72 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f er..** A call to
37590 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e either function
375a0 20 72 65 70 6c 61 63 65 73 20 61 6e 79 20 65 78 replaces any ex
375b0 69 73 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e isting callback.
375c0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 .**.** When the
375d0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
375e0 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 ked, the first a
375f0 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 rgument passed i
37600 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 s a copy.** of t
37610 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
37620 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f nt to sqlite3_co
37630 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 llation_needed()
37640 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 or.** sqlite3_c
37650 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 ollation_needed1
37660 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 6(). The second
37670 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
37680 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e database.** con
37690 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 nection. The th
376a0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ird argument is
376b0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 one of [SQLITE_U
376c0 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 TF8], [SQLITE_UT
376d0 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 F16BE],.** or [S
376e0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 QLITE_UTF16LE],
376f0 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d indicating the m
37700 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f ost desirable fo
37710 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 rm of the collat
37720 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 ion.** sequence
37730 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 function require
37740 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 d. The fourth p
37750 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 arameter is the
37760 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 name of the.** r
37770 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f equired collatio
37780 6e 20 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a n sequence..**.*
37790 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 * The callback f
377a0 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 unction should r
377b0 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69 egister the desi
377c0 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 red collation us
377d0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
377e0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
377f0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 ()], [sqlite3_cr
37800 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 eate_collation16
37810 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 ()], or.** [sqli
37820 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
37830 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a tion_v2()]..**.*
37840 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
37850 0a 2a 2a 20 7b 48 31 36 37 30 32 7d 20 41 20 73 .** {H16702} A s
37860 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 uccessful call t
37870 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 o [sqlite3_colla
37880 74 69 6f 6e 5f 6e 65 65 64 65 64 28 44 2c 50 2c tion_needed(D,P,
37890 46 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 F)].**
378a0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c or [sqlite3_coll
378b0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 44 ation_needed16(D
378c0 2c 50 2c 46 29 5d 20 63 61 75 73 65 73 0a 2a 2a ,P,F)] causes.**
378d0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 64 the [d
378e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
378f0 6f 6e 5d 20 44 20 74 6f 20 69 6e 76 6f 6b 65 20 on] D to invoke
37900 63 61 6c 6c 62 61 63 6b 20 46 20 77 69 74 68 20 callback F with
37910 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 first.**
37920 20 20 70 61 72 61 6d 65 74 65 72 20 50 20 77 68 parameter P wh
37930 65 6e 65 76 65 72 20 69 74 20 6e 65 65 64 73 20 enever it needs
37940 61 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e a comparison fun
37950 63 74 69 6f 6e 20 66 6f 72 20 61 0a 2a 2a 20 20 ction for a.**
37960 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e collatin
37970 67 20 73 65 71 75 65 6e 63 65 20 74 68 61 74 20 g sequence that
37980 69 74 20 64 6f 65 73 20 6e 6f 74 20 6b 6e 6f 77 it does not know
37990 20 61 62 6f 75 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 about..**.** {H
379a0 31 36 37 30 34 7d 20 45 61 63 68 20 73 75 63 63 16704} Each succ
379b0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b essful call to [
379c0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f sqlite3_collatio
379d0 6e 5f 6e 65 65 64 65 64 28 29 5d 20 6f 72 0a 2a n_needed()] or.*
379e0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
379f0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 te3_collation_ne
37a00 65 64 65 64 31 36 28 29 5d 20 6f 76 65 72 72 69 eded16()] overri
37a10 64 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b des the callback
37a20 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 registered.**
37a30 20 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73 on the s
37a40 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f ame [database co
37a50 6e 6e 65 63 74 69 6f 6e 5d 20 62 79 20 70 72 69 nnection] by pri
37a60 6f 72 20 63 61 6c 6c 73 20 74 6f 20 65 69 74 68 or calls to eith
37a70 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 er.** i
37a80 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 nterface..**.**
37a90 7b 48 31 36 37 30 36 7d 20 54 68 65 20 6e 61 6d {H16706} The nam
37aa0 65 20 6f 66 20 74 68 65 20 72 65 71 75 65 73 74 e of the request
37ab0 65 64 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e ed collating fun
37ac0 63 74 69 6f 6e 20 70 61 73 73 65 64 20 69 6e 20 ction passed in
37ad0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
37ae0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 4th parameter to
37af0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 the callback is
37b00 20 69 6e 20 55 54 46 2d 38 20 69 66 20 74 68 65 in UTF-8 if the
37b10 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 callback.**
37b20 20 20 20 20 20 20 77 61 73 20 72 65 67 69 73 74 was regist
37b30 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 ered using [sqli
37b40 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 te3_collation_ne
37b50 65 64 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 eded()] and.**
37b60 20 20 20 20 20 20 20 20 69 73 20 69 6e 20 55 54 is in UT
37b70 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 F-16 native byte
37b80 20 6f 72 64 65 72 20 69 66 20 74 68 65 20 63 61 order if the ca
37b90 6c 6c 62 61 63 6b 20 77 61 73 0a 2a 2a 20 20 20 llback was.**
37ba0 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65 registere
37bb0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
37bc0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 _collation_neede
37bd0 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 d16()]..*/.int s
37be0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
37bf0 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 _needed(. sqlit
37c00 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a e3*, . void*, .
37c10 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c void(*)(void*,
37c20 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 sqlite3*,int eTe
37c30 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 xtRep,const char
37c40 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 *).);.int sqlite
37c50 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 3_collation_need
37c60 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a ed16(. sqlite3*
37c70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f , . void*,. vo
37c80 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 id(*)(void*,sqli
37c90 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 te3*,int eTextRe
37ca0 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 p,const void*).)
37cb0 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 ;../*.** Specify
37cc0 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 the key for an
37cd0 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61 encrypted databa
37ce0 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e se. This routin
37cf0 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 e should be.** c
37d00 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 alled right afte
37d10 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 r sqlite3_open()
37d20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 ..**.** The code
37d30 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 to implement th
37d40 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 is API is not av
37d50 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 ailable in the p
37d60 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a ublic release.**
37d70 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 of SQLite..*/.i
37d80 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a nt sqlite3_key(.
37d90 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
37da0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
37db0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 /* Database to
37dc0 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 be rekeyed */.
37dd0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 const void *pKey
37de0 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f , int nKey /
37df0 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a * The key */.);.
37e00 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 ./*.** Change th
37e10 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e e key on an open
37e20 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 database. If t
37e30 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 he current datab
37e40 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e ase is not.** en
37e50 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f crypted, this ro
37e60 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 utine will encry
37e70 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d pt it. If pNew=
37e80 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 =0 or nNew==0, t
37e90 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 he.** database i
37ea0 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a s decrypted..**.
37eb0 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 ** The code to i
37ec0 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 mplement this AP
37ed0 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 I is not availab
37ee0 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 le in the public
37ef0 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 release.** of S
37f00 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 QLite..*/.int sq
37f10 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 lite3_rekey(. s
37f20 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
37f30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
37f40 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 Database to be
37f50 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e rekeyed */. con
37f60 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 st void *pKey, i
37f70 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 nt nKey /* T
37f80 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b he new key */.);
37f90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
37fa0 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 : Suspend Execut
37fb0 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 ion For A Short
37fc0 54 69 6d 65 20 7b 48 31 30 35 33 30 7d 20 3c 53 Time {H10530} <S
37fd0 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 40410>.**.** The
37fe0 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 sqlite3_sleep()
37ff0 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 function causes
38000 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 the current thr
38010 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 ead to suspend e
38020 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 xecution.** for
38030 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 at least a numbe
38040 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 r of millisecond
38050 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 s specified in i
38060 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a ts parameter..**
38070 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 .** If the opera
38080 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 ting system does
38090 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 not support sle
380a0 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68 ep requests with
380b0 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 .** millisecond
380c0 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c time resolution,
380d0 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 then the time w
380e0 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 ill be rounded u
380f0 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 p to.** the near
38100 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 est second. The
38110 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 number of millis
38120 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 econds of sleep
38130 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 actually.** requ
38140 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f ested from the o
38150 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 perating system
38160 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a is returned..**.
38170 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d ** SQLite implem
38180 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 ents this interf
38190 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 ace by calling t
381a0 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d he xSleep().** m
381b0 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 ethod of the def
381c0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 ault [sqlite3_vf
381d0 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a s] object..**.**
381e0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
381f0 2a 2a 20 7b 48 31 30 35 33 33 7d 20 54 68 65 20 ** {H10533} The
38200 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d [sqlite3_sleep(M
38210 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 6e 76 )] interface inv
38220 6f 6b 65 73 20 74 68 65 20 78 53 6c 65 65 70 0a okes the xSleep.
38230 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 74 68 ** meth
38240 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c od of the defaul
38250 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 7c 56 t [sqlite3_vfs|V
38260 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a FS] in order to.
38270 2a 2a 20 20 20 20 20 20 20 20 20 20 73 75 73 70 ** susp
38280 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 end execution of
38290 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 the current thr
382a0 65 61 64 20 66 6f 72 20 61 74 20 6c 65 61 73 74 ead for at least
382b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4d 20 6d .** M m
382c0 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2a 0a illiseconds..**.
382d0 2a 2a 20 7b 48 31 30 35 33 36 7d 20 54 68 65 20 ** {H10536} The
382e0 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d [sqlite3_sleep(M
382f0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
38300 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
38310 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d of.** m
38320 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 illiseconds of s
38330 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 20 72 65 leep actually re
38340 71 75 65 73 74 65 64 20 6f 66 20 74 68 65 20 6f quested of the o
38350 70 65 72 61 74 69 6e 67 0a 2a 2a 20 20 20 20 20 perating.**
38360 20 20 20 20 20 73 79 73 74 65 6d 2c 20 77 68 69 system, whi
38370 63 68 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67 ch might be larg
38380 65 72 20 74 68 61 6e 20 74 68 65 20 70 61 72 61 er than the para
38390 6d 65 74 65 72 20 4d 2e 0a 2a 2f 0a 69 6e 74 20 meter M..*/.int
383a0 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e sqlite3_sleep(in
383b0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
383c0 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 REF: Name Of The
383d0 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 Folder Holding
383e0 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 20 Temporary Files
383f0 7b 48 31 30 33 31 30 7d 20 3c 53 32 30 30 30 30 {H10310} <S20000
38400 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20 >.**.** If this
38410 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 global variable
38420 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 is made to point
38430 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 to a string whi
38440 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d ch is.** the nam
38450 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 e of a folder (a
38460 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 .k.a. directory)
38470 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f , then all tempo
38480 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 rary files.** cr
38490 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 eated by SQLite
384a0 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69 will be placed i
384b0 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 n that directory
384c0 2e 20 20 49 66 20 74 68 69 73 20 76 61 72 69 61 . If this varia
384d0 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c ble.** is a NULL
384e0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 pointer, then S
384f0 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61 QLite performs a
38500 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 search for an a
38510 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 ppropriate.** te
38520 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72 mporary file dir
38530 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 ectory..**.** It
38540 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 is not safe to
38550 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 modify this vari
38560 61 62 6c 65 20 6f 6e 63 65 20 61 20 5b 64 61 74 able once a [dat
38570 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
38580 5d 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 6f 70 ].** has been op
38590 65 6e 65 64 2e 20 20 49 74 20 69 73 20 69 6e 74 ened. It is int
385a0 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 ended that this
385b0 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 variable be set
385c0 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 once.** as part
385d0 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 of process initi
385e0 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 alization and be
385f0 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 fore any SQLite
38600 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 interface.** rou
38610 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 tines have been
38620 63 61 6c 6c 20 61 6e 64 20 72 65 6d 61 69 6e 20 call and remain
38630 75 6e 63 68 61 6e 67 65 64 20 74 68 65 72 65 61 unchanged therea
38640 66 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f fter..*/.SQLITE_
38650 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c EXTERN char *sql
38660 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 ite3_temp_direct
38670 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ory;../*.** CAPI
38680 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 3REF: Test For A
38690 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 20 uto-Commit Mode
386a0 7b 48 31 32 39 33 30 7d 20 3c 53 36 30 32 30 30 {H12930} <S60200
386b0 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b >.** KEYWORDS: {
386c0 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d autocommit mode}
386d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
386e0 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 e3_get_autocommi
386f0 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 t() interface re
38700 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f turns non-zero o
38710 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 r.** zero if the
38720 20 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 given database
38730 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 connection is or
38740 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 is not in autoc
38750 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 ommit mode,.** r
38760 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41 75 espectively. Au
38770 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 tocommit mode is
38780 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a on by default..
38790 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f ** Autocommit mo
387a0 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 de is disabled b
387b0 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 y a [BEGIN] stat
387c0 65 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f ement..** Autoco
387d0 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d mmit mode is re-
387e0 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f enabled by a [CO
387f0 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 MMIT] or [ROLLBA
38800 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 CK]..**.** If ce
38810 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 rtain kinds of e
38820 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 rrors occur on a
38830 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 statement withi
38840 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d n a multi-statem
38850 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 ent.** transacti
38860 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 on (errors inclu
38870 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c ding [SQLITE_FUL
38880 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 L], [SQLITE_IOER
38890 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e R],.** [SQLITE_N
388a0 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 OMEM], [SQLITE_B
388b0 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 USY], and [SQLIT
388c0 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68 E_INTERRUPT]) th
388d0 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 en the.** transa
388e0 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 ction might be r
388f0 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d olled back autom
38900 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f atically. The o
38910 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 nly way to.** fi
38920 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72 20 53 nd out whether S
38930 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 QLite automatica
38940 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 lly rolled back
38950 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 the transaction
38960 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f after.** an erro
38970 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69 73 r is to use this
38980 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a function..**.**
38990 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
389a0 2a 2a 20 7b 48 31 32 39 33 31 7d 20 54 68 65 20 ** {H12931} The
389b0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 [sqlite3_get_aut
389c0 6f 63 6f 6d 6d 69 74 28 44 29 5d 20 69 6e 74 65 ocommit(D)] inte
389d0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f rface returns no
389e0 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 20 20 20 n-zero or.**
389f0 20 20 20 20 20 20 7a 65 72 6f 20 69 66 20 74 68 zero if th
38a00 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
38a10 65 63 74 69 6f 6e 5d 20 44 20 69 73 20 6f 72 20 ection] D is or
38a20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f is not in autoco
38a30 6d 6d 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 mmit.**
38a40 20 6d 6f 64 65 2c 20 72 65 73 70 65 63 74 69 76 mode, respectiv
38a50 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 ely..**.** {H129
38a60 33 32 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 32} Autocommit m
38a70 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 ode is on by def
38a80 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 ault..**.** {H12
38a90 39 33 33 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 933} Autocommit
38aa0 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 mode is disabled
38ab0 20 62 79 20 61 20 73 75 63 63 65 73 73 66 75 6c by a successful
38ac0 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 [BEGIN] stateme
38ad0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33 nt..**.** {H1293
38ae0 34 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 4} Autocommit mo
38af0 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 de is enabled by
38b00 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 5b 43 a successful [C
38b10 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 OMMIT] or [ROLLB
38b20 41 43 4b 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 ACK].**
38b30 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a statement..**.*
38b40 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a * ASSUMPTIONS:.*
38b50 2a 0a 2a 2a 20 7b 41 31 32 39 33 36 7d 20 49 66 *.** {A12936} If
38b60 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 another thread
38b70 63 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f changes the auto
38b80 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 commit status of
38b90 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a the database.**
38ba0 20 20 20 20 20 20 20 20 20 20 63 6f 6e 6e 65 63 connec
38bb0 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 tion while this
38bc0 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 routine is runni
38bd0 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 ng, then the ret
38be0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 urn value.**
38bf0 20 20 20 20 20 20 69 73 20 75 6e 64 65 66 69 6e is undefin
38c00 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ed..*/.int sqlit
38c10 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 e3_get_autocommi
38c20 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a t(sqlite3*);../*
38c30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 .** CAPI3REF: Fi
38c40 6e 64 20 54 68 65 20 44 61 74 61 62 61 73 65 20 nd The Database
38c50 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70 Handle Of A Prep
38c60 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 7b ared Statement {
38c70 48 31 33 31 32 30 7d 20 3c 53 36 30 36 30 30 3e H13120} <S60600>
38c80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
38c90 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 e3_db_handle int
38ca0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 erface returns t
38cb0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
38cc0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a nection] handle.
38cd0 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b 70 ** to which a [p
38ce0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
38cf0 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 54 68 65 t] belongs. The
38d00 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 database handle
38d10 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 returned by.**
38d20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c sqlite3_db_handl
38d30 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 64 61 e is the same da
38d40 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74 68 tabase handle th
38d50 61 74 20 77 61 73 20 74 68 65 20 66 69 72 73 74 at was the first
38d60 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 argument.** to
38d70 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 the [sqlite3_pre
38d80 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 pare_v2()] call
38d90 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 (or its variants
38da0 29 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20 ) that was used
38db0 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 65 to.** create the
38dc0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 statement in th
38dd0 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a e first place..*
38de0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
38df0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 32 33 7d 20 .**.** {H13123}
38e00 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f The [sqlite3_db_
38e10 68 61 6e 64 6c 65 28 53 29 5d 20 69 6e 74 65 72 handle(S)] inter
38e20 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 face returns a p
38e30 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 ointer.**
38e40 20 20 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 to the [datab
38e50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
38e60 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
38e70 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
38e80 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
38e90 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 73 71 6c 69 74 ent] S..*/.sqlit
38ea0 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 e3 *sqlite3_db_h
38eb0 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 andle(sqlite3_st
38ec0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 mt*);../*.** CAP
38ed0 49 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 I3REF: Find the
38ee0 6e 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74 next prepared st
38ef0 61 74 65 6d 65 6e 74 20 7b 48 31 33 31 34 30 7d atement {H13140}
38f00 20 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S60600>.**.**
38f10 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 This interface r
38f20 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
38f30 20 74 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 to the next [pr
38f40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
38f50 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 ] after.** pStmt
38f60 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
38f70 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
38f80 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 onnection] pDb.
38f90 20 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c If pStmt is NUL
38fa0 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 L.** then this i
38fb0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
38fc0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
38fd0 65 20 66 69 72 73 74 20 70 72 65 70 61 72 65 64 e first prepared
38fe0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 statement.** as
38ff0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 sociated with th
39000 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
39010 63 74 69 6f 6e 20 70 44 62 2e 20 20 49 66 20 6e ction pDb. If n
39020 6f 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 o prepared state
39030 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 ment.** satisfie
39040 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 s the conditions
39050 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 of this routine
39060 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c , it returns NUL
39070 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 L..**.** INVARIA
39080 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 NTS:.**.** {H131
39090 34 33 7d 20 49 66 20 44 20 69 73 20 61 20 5b 64 43} If D is a [d
390a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
390b0 6f 6e 5d 20 74 68 61 74 20 68 6f 6c 64 73 20 6f on] that holds o
390c0 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20 20 ne or more.**
390d0 20 20 20 20 20 20 20 75 6e 66 69 6e 61 6c 69 7a unfinaliz
390e0 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ed [prepared sta
390f0 74 65 6d 65 6e 74 73 5d 20 61 6e 64 20 53 20 69 tements] and S i
39100 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
39110 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 ,.** th
39120 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 en [sqlite3_next
39130 5f 73 74 6d 74 28 44 2c 20 53 29 5d 20 72 6f 75 _stmt(D, S)] rou
39140 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72 tine shall retur
39150 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 n a pointer.**
39160 20 20 20 20 20 20 20 20 74 6f 20 6f 6e 65 20 6f to one o
39170 66 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 f the prepared s
39180 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 tatements associ
39190 61 74 65 64 20 77 69 74 68 20 44 2e 0a 2a 2a 0a ated with D..**.
391a0 2a 2a 20 7b 48 31 33 31 34 36 7d 20 49 66 20 44 ** {H13146} If D
391b0 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 is a [database
391c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 connection] that
391d0 20 68 6f 6c 64 73 20 6e 6f 20 75 6e 66 69 6e 61 holds no unfina
391e0 6c 69 7a 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 lized.**
391f0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 [prepared stat
39200 65 6d 65 6e 74 73 5d 20 61 6e 64 20 53 20 69 73 ements] and S is
39210 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
39220 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 then.**
39230 20 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f [sqlite3_next_
39240 73 74 6d 74 28 44 2c 20 53 29 5d 20 72 6f 75 74 stmt(D, S)] rout
39250 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e ine shall return
39260 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
39270 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 34 39 7d 20 .**.** {H13149}
39280 49 66 20 53 20 69 73 20 61 20 5b 70 72 65 70 61 If S is a [prepa
39290 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 red statement] i
392a0 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 n the [database
392b0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a connection] D.**
392c0 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 53 20 and S
392d0 69 73 20 6e 6f 74 20 74 68 65 20 6c 61 73 74 20 is not the last
392e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
392f0 6e 74 20 69 6e 20 44 2c 20 74 68 65 6e 0a 2a 2a nt in D, then.**
39300 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
39310 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20 e3_next_stmt(D,
39320 53 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c S)] routine shal
39330 6c 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 l return a point
39340 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 er.** t
39350 6f 20 74 68 65 20 6e 65 78 74 20 70 72 65 70 61 o the next prepa
39360 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 6e red statement in
39370 20 44 20 61 66 74 65 72 20 53 2e 0a 2a 2a 0a 2a D after S..**.*
39380 2a 20 7b 48 31 33 31 35 32 7d 20 49 66 20 53 20 * {H13152} If S
39390 69 73 20 74 68 65 20 6c 61 73 74 20 5b 70 72 65 is the last [pre
393a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
393b0 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 in the.**
393c0 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f [database co
393d0 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74 68 65 6e nnection] D then
393e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6e 65 the [sqlite3_ne
393f0 78 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d 0a 2a xt_stmt(D, S)].*
39400 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75 74 69 * routi
39410 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 ne shall return
39420 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a a NULL pointer..
39430 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e **.** ASSUMPTION
39440 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 31 35 34 S:.**.** {A13154
39450 7d 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 } The [database
39460 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e connection] poin
39470 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20 ter D in a call
39480 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b to.** [
39490 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d sqlite3_next_stm
394a0 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 t(D,S)] must ref
394b0 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 er to an open da
394c0 74 61 62 61 73 65 0a 2a 2a 20 20 20 20 20 20 20 tabase.**
394d0 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e connection an
394e0 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20 d in particular
394f0 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55 must not be a NU
39500 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 LL pointer..*/.s
39510 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c qlite3_stmt *sql
39520 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 ite3_next_stmt(s
39530 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c qlite3 *pDb, sql
39540 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
39550 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
39560 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 EF: Commit And R
39570 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 ollback Notifica
39580 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b tion Callbacks {
39590 48 31 32 39 35 30 7d 20 3c 53 36 30 34 30 30 3e H12950} <S60400>
395a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
395b0 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 e3_commit_hook()
395c0 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 interface regis
395d0 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a ters a callback.
395e0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ** function to b
395f0 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 e invoked whenev
39600 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e er a transaction
39610 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a is committed..*
39620 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 * Any callback s
39630 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 et by a previous
39640 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
39650 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a _commit_hook().*
39660 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 * for the same d
39670 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
39680 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e on is overridden
39690 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 ..** The sqlite3
396a0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 _rollback_hook()
396b0 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 interface regis
396c0 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a ters a callback.
396d0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ** function to b
396e0 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 e invoked whenev
396f0 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e er a transaction
39700 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a is committed..*
39710 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 * Any callback s
39720 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 et by a previous
39730 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
39740 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a _commit_hook().*
39750 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 * for the same d
39760 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
39770 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e on is overridden
39780 2e 0a 2a 2a 20 54 68 65 20 70 41 72 67 20 61 72 ..** The pArg ar
39790 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 gument is passed
397a0 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 through to the
397b0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 49 66 20 callback..** If
397c0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 the callback on
397d0 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 a commit hook fu
397e0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e nction returns n
397f0 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e on-zero,.** then
39800 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 the commit is c
39810 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 onverted into a
39820 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 rollback..**.**
39830 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 If another funct
39840 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73 ion was previous
39850 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69 ly registered, i
39860 74 73 0a 2a 2a 20 70 41 72 67 20 76 61 6c 75 65 ts.** pArg value
39870 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f is returned. O
39880 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 therwise NULL is
39890 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
398a0 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d The callback im
398b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 plementation mus
398c0 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e t not do anythin
398d0 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 g that will modi
398e0 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 fy.** the databa
398f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 se connection th
39900 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 at invoked the c
39910 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 allback. Any ac
39920 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 tions.** to modi
39930 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 fy the database
39940 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 connection must
39950 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 be deferred unti
39960 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 l after the.** c
39970 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 ompletion of the
39980 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
39990 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 ] call that trig
399a0 67 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 gered the commit
399b0 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 .** or rollback
399c0 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73 hook in the firs
399d0 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 t place..** Note
399e0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 that [sqlite3_p
399f0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 repare_v2()] and
39a00 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
39a10 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 ] both modify th
39a20 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 eir.** database
39a30 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 connections for
39a40 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 the meaning of "
39a50 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 modify" in this
39a60 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a paragraph..**.**
39a70 20 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e Registering a N
39a80 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 ULL function dis
39a90 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61 ables the callba
39aa0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 ck..**.** For th
39ab0 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 e purposes of th
39ac0 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 is API, a transa
39ad0 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f ction is said to
39ae0 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f have been.** ro
39af0 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 lled back if an
39b00 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 explicit "ROLLBA
39b10 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 CK" statement is
39b20 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a executed, or.**
39b30 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e an error or con
39b40 73 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 straint causes a
39b50 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 n implicit rollb
39b60 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a ack to occur..**
39b70 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 The rollback ca
39b80 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e llback is not in
39b90 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 voked if a trans
39ba0 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 action is.** aut
39bb0 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 omatically rolle
39bc0 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 74 d back because t
39bd0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
39be0 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 ection is closed
39bf0 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 ..** The rollbac
39c00 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f k callback is no
39c10 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 t invoked if a t
39c20 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a ransaction is.**
39c30 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 rolled back bec
39c40 61 75 73 65 20 61 20 63 6f 6d 6d 69 74 20 63 61 ause a commit ca
39c50 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 65 64 20 llback returned
39c60 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c 74 6f non-zero..** <to
39c70 64 6f 3e 20 43 68 65 63 6b 20 6f 6e 20 74 68 69 do> Check on thi
39c80 73 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 s </todo>.**.**
39c90 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
39ca0 2a 20 7b 48 31 32 39 35 31 7d 20 54 68 65 20 5b * {H12951} The [
39cb0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 sqlite3_commit_h
39cc0 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 ook(D,F,P)] inte
39cd0 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 rface registers
39ce0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
39cf0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
39d00 6e 20 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 n F to be invoke
39d10 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 d with argument
39d20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20 P whenever.**
39d30 20 20 20 20 20 20 20 61 20 74 72 61 6e 73 61 63 a transac
39d40 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 20 6f 6e 20 tion commits on
39d50 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
39d60 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a nnection] D..**.
39d70 2a 2a 20 7b 48 31 32 39 35 32 7d 20 54 68 65 20 ** {H12952} The
39d80 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f [sqlite3_commit_
39d90 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 hook(D,F,P)] int
39da0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 erface returns t
39db0 68 65 20 50 20 61 72 67 75 6d 65 6e 74 0a 2a 2a he P argument.**
39dc0 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 74 from t
39dd0 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c he previous call
39de0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 5b with the same [
39df0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
39e00 69 6f 6e 5d 20 44 2c 0a 2a 2a 20 20 20 20 20 20 ion] D,.**
39e10 20 20 20 20 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74 or NULL on t
39e20 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 66 6f he first call fo
39e30 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 r a particular d
39e40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
39e50 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 on D..**.** {H12
39e60 39 35 33 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 953} Each call t
39e70 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 o [sqlite3_commi
39e80 74 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 77 72 t_hook()] overwr
39e90 69 74 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 ites the callbac
39ea0 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 k.** re
39eb0 67 69 73 74 65 72 65 64 20 62 79 20 70 72 69 6f gistered by prio
39ec0 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b r calls..**.** {
39ed0 48 31 32 39 35 34 7d 20 49 66 20 74 68 65 20 46 H12954} If the F
39ee0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 argument to [sq
39ef0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f lite3_commit_hoo
39f00 6b 28 44 2c 46 2c 50 29 5d 20 69 73 20 4e 55 4c k(D,F,P)] is NUL
39f10 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 L.** th
39f20 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f en the commit ho
39f30 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 ok callback is c
39f40 61 6e 63 65 6c 65 64 20 61 6e 64 20 6e 6f 20 63 anceled and no c
39f50 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 allback.**
39f60 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 is invoked w
39f70 68 65 6e 20 61 20 74 72 61 6e 73 61 63 74 69 6f hen a transactio
39f80 6e 20 63 6f 6d 6d 69 74 73 2e 0a 2a 2a 0a 2a 2a n commits..**.**
39f90 20 7b 48 31 32 39 35 35 7d 20 49 66 20 74 68 65 {H12955} If the
39fa0 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b commit callback
39fb0 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 returns non-zer
39fc0 6f 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 o then the commi
39fd0 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 t is.**
39fe0 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 converted into
39ff0 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a a rollback..**.*
3a000 2a 20 7b 48 31 32 39 36 31 7d 20 54 68 65 20 5b * {H12961} The [
3a010 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b sqlite3_rollback
3a020 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e _hook(D,F,P)] in
3a030 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 terface register
3a040 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 s the.**
3a050 20 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 callback funct
3a060 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e 76 6f ion F to be invo
3a070 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e ked with argumen
3a080 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 t P whenever.**
3a090 20 20 20 20 20 20 20 20 20 61 20 74 72 61 6e 73 a trans
3a0a0 61 63 74 69 6f 6e 20 72 6f 6c 6c 73 20 62 61 63 action rolls bac
3a0b0 6b 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 k on the [databa
3a0c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
3a0d0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 36 32 7d ..**.** {H12962}
3a0e0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 6f The [sqlite3_ro
3a0f0 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c llback_hook(D,F,
3a100 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 P)] interface re
3a110 74 75 72 6e 73 20 74 68 65 20 50 0a 2a 2a 20 20 turns the P.**
3a120 20 20 20 20 20 20 20 20 61 72 67 75 6d 65 6e 74 argument
3a130 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f from the previo
3a140 75 73 20 63 61 6c 6c 20 77 69 74 68 20 74 68 65 us call with the
3a150 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 same.**
3a160 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e [database conn
3a170 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 ection] D, or NU
3a180 4c 4c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 LL on the first
3a190 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 call.**
3a1a0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 for a particula
3a1b0 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 r database conne
3a1c0 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b ction D..**.** {
3a1d0 48 31 32 39 36 33 7d 20 45 61 63 68 20 63 61 6c H12963} Each cal
3a1e0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 6f l to [sqlite3_ro
3a1f0 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 20 6f llback_hook()] o
3a200 76 65 72 77 72 69 74 65 73 20 74 68 65 20 63 61 verwrites the ca
3a210 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 llback.**
3a220 20 20 20 72 65 67 69 73 74 65 72 65 64 20 62 79 registered by
3a230 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a prior calls..**
3a240 0a 2a 2a 20 7b 48 31 32 39 36 34 7d 20 49 66 20 .** {H12964} If
3a250 74 68 65 20 46 20 61 72 67 75 6d 65 6e 74 20 74 the F argument t
3a260 6f 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 o [sqlite3_rollb
3a270 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d ack_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 72 6f then the ro
3a2a0 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 63 61 6c 6c llback hook call
3a2b0 62 61 63 6b 20 69 73 20 63 61 6e 63 65 6c 65 64 back is canceled
3a2c0 20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62 61 63 6b and no callback
3a2d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 .** is
3a2e0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 74 invoked when a t
3a2f0 72 61 6e 73 61 63 74 69 6f 6e 20 72 6f 6c 6c 73 ransaction rolls
3a300 20 62 61 63 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 2a back..*/.void *
3a310 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 sqlite3_commit_h
3a320 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e ook(sqlite3*, in
3a330 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 t(*)(void*), voi
3a340 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 d*);.void *sqlit
3a350 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b e3_rollback_hook
3a360 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 (sqlite3*, void(
3a370 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 *)(void *), void
3a380 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
3a390 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 REF: Data Change
3a3a0 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 Notification Ca
3a3b0 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 37 30 7d llbacks {H12970}
3a3c0 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S60400>.**.**
3a3d0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 The sqlite3_upda
3a3e0 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 te_hook() interf
3a3f0 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 ace registers a
3a400 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
3a410 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 n.** with the [d
3a420 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
3a430 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62 on] identified b
3a440 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 y the first argu
3a450 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e ment.** to be in
3a460 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 voked whenever a
3a470 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c row is updated,
3a480 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c inserted or del
3a490 65 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c eted..** Any cal
3a4a0 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 lback set by a p
3a4b0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 revious call to
3a4c0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a this function.**
3a4d0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 for the same da
3a4e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
3a4f0 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e n is overridden.
3a500 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e .**.** The secon
3a510 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 d argument is a
3a520 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 pointer to the f
3a530 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b unction to invok
3a540 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 e when a.** row
3a550 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 is updated, inse
3a560 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e rted or deleted.
3a570 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 .** The first ar
3a580 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61 gument to the ca
3a590 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 llback is a copy
3a5a0 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72 of the third ar
3a5b0 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c gument.** to sql
3a5c0 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b ite3_update_hook
3a5d0 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e ()..** The secon
3a5e0 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d d callback argum
3a5f0 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 ent is one of [S
3a600 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b QLITE_INSERT], [
3a610 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a SQLITE_DELETE],.
3a620 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 ** or [SQLITE_UP
3a630 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 DATE], depending
3a640 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f on the operatio
3a650 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 n that caused th
3a660 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f e callback.** to
3a670 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 be invoked..**
3a680 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f The third and fo
3a690 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 urth arguments t
3a6a0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 o the callback c
3a6b0 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 ontain pointers
3a6c0 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 to the.** databa
3a6d0 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d se and table nam
3a6e0 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 e containing the
3a6f0 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a affected row..*
3a700 2a 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c * The final call
3a710 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 back parameter i
3a720 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 s the rowid of t
3a730 68 65 20 72 6f 77 2e 20 49 6e 20 74 68 65 20 63 he row. In the c
3a740 61 73 65 20 6f 66 0a 2a 2a 20 61 6e 20 75 70 64 ase of.** an upd
3a750 61 74 65 2c 20 74 68 69 73 20 69 73 20 74 68 65 ate, this is the
3a760 20 72 6f 77 69 64 20 61 66 74 65 72 20 74 68 65 rowid after the
3a770 20 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c update takes pl
3a780 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 ace..**.** The u
3a790 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f pdate hook is no
3a7a0 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 t invoked when i
3a7b0 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 nternal system t
3a7c0 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 ables are.** mod
3a7d0 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 ified (i.e. sqli
3a7e0 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 te_master and sq
3a7f0 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 0a lite_sequence)..
3a800 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 **.** The update
3a810 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 hook implementa
3a820 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f tion must not do
3a830 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 anything that w
3a840 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 ill modify.** th
3a850 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
3a860 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b ction that invok
3a870 65 64 20 74 68 65 20 75 70 64 61 74 65 20 68 6f ed the update ho
3a880 6f 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 ok. Any actions
3a890 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 .** to modify th
3a8a0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
3a8b0 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 ction must be de
3a8c0 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 ferred until aft
3a8d0 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 er the.** comple
3a8e0 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c tion of the [sql
3a8f0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c ite3_step()] cal
3a900 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 l that triggered
3a910 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b the update hook
3a920 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b ..** Note that [
3a930 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
3a940 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 v2()] and [sqlit
3a950 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 e3_step()] both
3a960 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 modify their.**
3a970 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
3a980 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 ions for the mea
3a990 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 ning of "modify"
3a9a0 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 in this paragra
3a9b0 70 68 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f ph..**.** If ano
3a9c0 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 ther function wa
3a9d0 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 s previously reg
3a9e0 69 73 74 65 72 65 64 2c 20 69 74 73 20 70 41 72 istered, its pAr
3a9f0 67 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 72 65 g value.** is re
3aa00 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 turned. Otherwi
3aa10 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 se NULL is retur
3aa20 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 ned..**.** INVAR
3aa30 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 IANTS:.**.** {H1
3aa40 32 39 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 2971} The [sqlit
3aa50 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 e3_update_hook(D
3aa60 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 ,F,P)] interface
3aa70 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c causes the call
3aa80 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 back.**
3aa90 20 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 function F to b
3aaa0 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 e invoked with f
3aab0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 50 irst parameter P
3aac0 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 whenever.**
3aad0 20 20 20 20 20 20 61 20 74 61 62 6c 65 20 72 6f a table ro
3aae0 77 20 69 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 w is modified, i
3aaf0 6e 73 65 72 74 65 64 2c 20 6f 72 20 64 65 6c 65 nserted, or dele
3ab00 74 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 ted on.**
3ab10 20 20 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 the [database
3ab20 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a connection] D..
3ab30 2a 2a 0a 2a 2a 20 7b 48 31 32 39 37 33 7d 20 54 **.** {H12973} T
3ab40 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 he [sqlite3_upda
3ab50 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 te_hook(D,F,P)]
3ab60 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
3ab70 73 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 20 s the value.**
3ab80 20 20 20 20 20 20 20 20 6f 66 20 50 20 66 6f 72 of P for
3ab90 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 the previous ca
3aba0 6c 6c 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b ll on the same [
3abb0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
3abc0 69 6f 6e 5d 20 44 2c 0a 2a 2a 20 20 20 20 20 20 ion] D,.**
3abd0 20 20 20 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 20 or NULL for
3abe0 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 2e 0a the first call..
3abf0 2a 2a 0a 2a 2a 20 7b 48 31 32 39 37 35 7d 20 49 **.** {H12975} I
3ac00 66 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f f the update hoo
3ac10 6b 20 63 61 6c 6c 62 61 63 6b 20 46 20 69 6e 20 k callback F in
3ac20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f [sqlite3_update_
3ac30 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 0a 2a 2a 20 hook(D,F,P)].**
3ac40 20 20 20 20 20 20 20 20 20 69 73 20 4e 55 4c 4c is NULL
3ac50 20 74 68 65 6e 20 74 68 65 20 6e 6f 20 75 70 64 then the no upd
3ac60 61 74 65 20 63 61 6c 6c 62 61 63 6b 73 20 61 72 ate callbacks ar
3ac70 65 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 e made..**.** {H
3ac80 31 32 39 37 37 7d 20 45 61 63 68 20 63 61 6c 6c 12977} Each call
3ac90 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 to [sqlite3_upd
3aca0 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d ate_hook(D,F,P)]
3acb0 20 6f 76 65 72 72 69 64 65 73 20 70 72 69 6f 72 overrides prior
3acc0 20 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20 calls.**
3acd0 20 20 20 74 6f 20 74 68 65 20 73 61 6d 65 20 69 to the same i
3ace0 6e 74 65 72 66 61 63 65 20 6f 6e 20 74 68 65 20 nterface on the
3acf0 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 same [database c
3ad00 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a onnection] D..**
3ad10 0a 2a 2a 20 7b 48 31 32 39 37 39 7d 20 54 68 65 .** {H12979} The
3ad20 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 63 61 6c update hook cal
3ad30 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 lback is not inv
3ad40 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e oked when intern
3ad50 61 6c 20 73 79 73 74 65 6d 0a 2a 2a 20 20 20 20 al system.**
3ad60 20 20 20 20 20 20 74 61 62 6c 65 73 20 73 75 63 tables suc
3ad70 68 20 61 73 20 73 71 6c 69 74 65 5f 6d 61 73 74 h as sqlite_mast
3ad80 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 er and sqlite_se
3ad90 71 75 65 6e 63 65 20 61 72 65 20 6d 6f 64 69 66 quence are modif
3ada0 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 ied..**.** {H129
3adb0 38 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 81} The second p
3adc0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
3add0 75 70 64 61 74 65 20 63 61 6c 6c 62 61 63 6b 0a update callback.
3ade0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6f ** is o
3adf0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e ne of [SQLITE_IN
3ae00 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 SERT], [SQLITE_D
3ae10 45 4c 45 54 45 5d 20 6f 72 20 5b 53 51 4c 49 54 ELETE] or [SQLIT
3ae20 45 5f 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 20 20 E_UPDATE],.**
3ae30 20 20 20 20 20 20 20 64 65 70 65 6e 64 69 6e 67 depending
3ae40 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f on the operatio
3ae50 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 n that caused th
3ae60 65 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 e callback to be
3ae70 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 invoked..**.**
3ae80 7b 48 31 32 39 38 33 7d 20 54 68 65 20 74 68 69 {H12983} The thi
3ae90 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72 rd and fourth ar
3aea0 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 guments to the c
3aeb0 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 allback contain
3aec0 70 6f 69 6e 74 65 72 73 0a 2a 2a 20 20 20 20 20 pointers.**
3aed0 20 20 20 20 20 74 6f 20 7a 65 72 6f 2d 74 65 72 to zero-ter
3aee0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 minated UTF-8 st
3aef0 72 69 6e 67 73 20 77 68 69 63 68 20 61 72 65 20 rings which are
3af00 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 the names of the
3af10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 .** dat
3af20 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 abase and table
3af30 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 75 70 that is being up
3af40 64 61 74 65 64 2e 0a 0a 2a 2a 20 7b 48 31 32 39 dated...** {H129
3af50 38 35 7d 20 54 68 65 20 66 69 6e 61 6c 20 63 61 85} The final ca
3af60 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 llback parameter
3af70 20 69 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66 is the rowid of
3af80 20 74 68 65 20 72 6f 77 20 61 66 74 65 72 0a 2a the row after.*
3af90 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63 * the c
3afa0 68 61 6e 67 65 20 6f 63 63 75 72 73 2e 0a 2a 2f hange occurs..*/
3afb0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 .void *sqlite3_u
3afc0 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 pdate_hook(. sq
3afd0 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 lite3*, . void(
3afe0 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 *)(void *,int ,c
3aff0 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 har const *,char
3b000 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 const *,sqlite3
3b010 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a _int64),. void*
3b020 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
3b030 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 REF: Enable Or D
3b040 69 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61 isable Shared Pa
3b050 67 65 72 20 43 61 63 68 65 20 7b 48 31 30 33 33 ger Cache {H1033
3b060 30 7d 20 3c 53 33 30 39 30 30 3e 0a 2a 2a 20 4b 0} <S30900>.** K
3b070 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 EYWORDS: {shared
3b080 20 63 61 63 68 65 7d 20 7b 73 68 61 72 65 64 20 cache} {shared
3b090 63 61 63 68 65 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a cache mode}.**.*
3b0a0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 * This routine e
3b0b0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c nables or disabl
3b0c0 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f es the sharing o
3b0d0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 f the database c
3b0e0 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 ache.** and sche
3b0f0 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72 ma data structur
3b100 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 es between [data
3b110 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
3b120 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a | connections].*
3b130 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 * to the same da
3b140 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 tabase. Sharing
3b150 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 is enabled if th
3b160 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 e argument is tr
3b170 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c ue.** and disabl
3b180 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 ed if the argume
3b190 6e 74 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a nt is false..**.
3b1a0 2a 2a 20 43 61 63 68 65 20 73 68 61 72 69 6e 67 ** Cache sharing
3b1b0 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 is enabled and
3b1c0 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20 disabled for an
3b1d0 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 20 entire process.
3b1e0 7b 45 4e 44 7d 0a 2a 2a 20 54 68 69 73 20 69 73 {END}.** This is
3b1f0 20 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 a change as of
3b200 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 SQLite version 3
3b210 2e 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 .5.0. In prior v
3b220 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
3b230 65 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 e,.** sharing wa
3b240 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 s enabled or dis
3b250 61 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 abled for each t
3b260 68 72 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 hread separately
3b270 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68 ..**.** The cach
3b280 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 e sharing mode s
3b290 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 et by this inter
3b2a0 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c face effects all
3b2b0 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 subsequent.** c
3b2c0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
3b2d0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 _open()], [sqlit
3b2e0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 e3_open_v2()], a
3b2f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e nd [sqlite3_open
3b300 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 16()]..** Existi
3b310 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ng database conn
3b320 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 ections continue
3b330 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 use the sharing
3b340 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 mode.** that wa
3b350 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 s in effect at t
3b360 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 he time they wer
3b370 65 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 e opened..**.**
3b380 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 Virtual tables c
3b390 61 6e 6e 6f 74 20 62 65 20 75 73 65 64 20 77 69 annot be used wi
3b3a0 74 68 20 61 20 73 68 61 72 65 64 20 63 61 63 68 th a shared cach
3b3b0 65 2e 20 20 57 68 65 6e 20 73 68 61 72 65 64 0a e. When shared.
3b3c0 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 ** cache is enab
3b3d0 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 led, the [sqlite
3b3e0 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 3_create_module(
3b3f0 29 5d 20 41 50 49 20 75 73 65 64 20 74 6f 20 72 )] API used to r
3b400 65 67 69 73 74 65 72 0a 2a 2a 20 76 69 72 74 75 egister.** virtu
3b410 61 6c 20 74 61 62 6c 65 73 20 77 69 6c 6c 20 61 al tables will a
3b420 6c 77 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20 lways return an
3b430 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 error..**.** Thi
3b440 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e s routine return
3b450 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 s [SQLITE_OK] if
3b460 20 73 68 61 72 65 64 20 63 61 63 68 65 20 77 61 shared cache wa
3b470 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 s enabled or dis
3b480 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65 73 73 abled.** success
3b490 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f fully. An [erro
3b4a0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 r code] is retur
3b4b0 6e 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a ned otherwise..*
3b4c0 2a 0a 2a 2a 20 53 68 61 72 65 64 20 63 61 63 68 *.** Shared cach
3b4d0 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 e is disabled by
3b4e0 20 64 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68 default. But th
3b4f0 69 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 is might change
3b500 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c in.** future rel
3b510 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e eases of SQLite.
3b520 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 Applications t
3b530 68 61 74 20 63 61 72 65 20 61 62 6f 75 74 20 73 hat care about s
3b540 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 hared.** cache s
3b550 65 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 etting should se
3b560 74 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e t it explicitly.
3b570 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
3b580 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 33 33 31 S:.**.** {H10331
3b590 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 } A successful i
3b5a0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 nvocation of [sq
3b5b0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 lite3_enable_sha
3b5c0 72 65 64 5f 63 61 63 68 65 28 42 29 5d 0a 2a 2a red_cache(B)].**
3b5d0 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20 65 will e
3b5e0 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 nable or disable
3b5f0 20 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f shared cache mo
3b600 64 65 20 66 6f 72 20 61 6e 79 20 73 75 62 73 65 de for any subse
3b610 71 75 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20 quently.**
3b620 20 20 20 20 63 72 65 61 74 65 64 20 5b 64 61 74 created [dat
3b630 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
3b640 5d 20 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 ] in the same pr
3b650 6f 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ocess..**.** {H1
3b660 30 33 33 36 7d 20 57 68 65 6e 20 73 68 61 72 65 0336} When share
3b670 64 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c d cache is enabl
3b680 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 ed, the [sqlite3
3b690 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 _create_module()
3b6a0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e ].** in
3b6b0 74 65 72 66 61 63 65 20 77 69 6c 6c 20 61 6c 77 terface will alw
3b6c0 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72 ays return an er
3b6d0 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 33 ror..**.** {H103
3b6e0 33 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 37} The [sqlite3
3b6f0 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 _enable_shared_c
3b700 61 63 68 65 28 42 29 5d 20 69 6e 74 65 72 66 61 ache(B)] interfa
3b710 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 ce returns.**
3b720 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f [SQLITE_O
3b730 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63 K] if shared cac
3b740 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f he was enabled o
3b750 72 20 64 69 73 61 62 6c 65 64 20 73 75 63 63 65 r disabled succe
3b760 73 73 66 75 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b ssfully..**.** {
3b770 48 31 30 33 33 39 7d 20 53 68 61 72 65 64 20 63 H10339} Shared c
3b780 61 63 68 65 20 69 73 20 64 69 73 61 62 6c 65 64 ache is disabled
3b790 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2f 0a by default..*/.
3b7a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 int sqlite3_enab
3b7b0 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 le_shared_cache(
3b7c0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 int);../*.** CAP
3b7d0 49 33 52 45 46 3a 20 41 74 74 65 6d 70 74 20 54 I3REF: Attempt T
3b7e0 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f o Free Heap Memo
3b7f0 72 79 20 7b 48 31 37 33 34 30 7d 20 3c 53 33 30 ry {H17340} <S30
3b800 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 220>.**.** The s
3b810 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d qlite3_release_m
3b820 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 61 63 emory() interfac
3b830 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66 72 e attempts to fr
3b840 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20 6f 66 ee N bytes.** of
3b850 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 heap memory by
3b860 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e deallocating non
3b870 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 -essential memor
3b880 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a y allocations.**
3b890 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 61 74 held by the dat
3b8a0 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e 20 7b abase library. {
3b8b0 45 4e 44 7d 20 20 4d 65 6d 6f 72 79 20 75 73 65 END} Memory use
3b8c0 64 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 d to cache datab
3b8d0 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 ase.** pages to
3b8e0 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 improve performa
3b8f0 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c nce is an exampl
3b900 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 e of non-essenti
3b910 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 73 71 al memory..** sq
3b920 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 lite3_release_me
3b930 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20 74 mory() returns t
3b940 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
3b950 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65 es actually free
3b960 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67 68 d,.** which migh
3b970 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 t be more or les
3b980 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e s than the amoun
3b990 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a 0a t requested..**.
3b9a0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
3b9b0 2a 0a 2a 2a 20 7b 48 31 37 33 34 31 7d 20 54 68 *.** {H17341} Th
3b9c0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 e [sqlite3_relea
3b9d0 73 65 5f 6d 65 6d 6f 72 79 28 4e 29 5d 20 69 6e se_memory(N)] in
3b9e0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 terface attempts
3b9f0 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 to.**
3ba00 66 72 65 65 20 4e 20 62 79 74 65 73 20 6f 66 20 free N bytes of
3ba10 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 heap memory by d
3ba20 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d eallocating non-
3ba30 65 73 73 65 6e 74 69 61 6c 0a 2a 2a 20 20 20 20 essential.**
3ba40 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 61 6c 6c memory all
3ba50 6f 63 61 74 69 6f 6e 73 20 68 65 6c 64 20 62 79 ocations held by
3ba60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 the database li
3ba70 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 brary..**.** {H1
3ba80 36 33 34 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 6342} The [sqlit
3ba90 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 e3_release_memor
3baa0 79 28 4e 29 5d 20 72 65 74 75 72 6e 73 20 74 68 y(N)] returns th
3bab0 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 e number.**
3bac0 20 20 20 20 20 6f 66 20 62 79 74 65 73 20 61 63 of bytes ac
3bad0 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 20 77 68 tually freed, wh
3bae0 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 ich might be mor
3baf0 65 20 6f 72 20 6c 65 73 73 0a 2a 2a 20 20 20 20 e or less.**
3bb00 20 20 20 20 20 20 74 68 61 6e 20 74 68 65 20 61 than the a
3bb10 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e mount requested.
3bb20 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
3bb30 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 release_memory(i
3bb40 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 nt);../*.** CAPI
3bb50 33 52 45 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 3REF: Impose A L
3bb60 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a imit On Heap Siz
3bb70 65 20 7b 48 31 37 33 35 30 7d 20 3c 53 33 30 32 e {H17350} <S302
3bb80 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 20>.**.** The sq
3bb90 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f lite3_soft_heap_
3bba0 6c 69 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 limit() interfac
3bbb0 65 20 70 6c 61 63 65 73 20 61 20 22 73 6f 66 74 e places a "soft
3bbc0 22 20 6c 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68 " limit.** on th
3bbd0 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 e amount of heap
3bbe0 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 memory that may
3bbf0 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 be allocated by
3bc00 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 49 66 20 61 SQLite..** If a
3bc10 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 n internal alloc
3bc20 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 ation is request
3bc30 65 64 20 74 68 61 74 20 77 6f 75 6c 64 20 65 78 ed that would ex
3bc40 63 65 65 64 20 74 68 65 0a 2a 2a 20 73 6f 66 74 ceed the.** soft
3bc50 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71 heap limit, [sq
3bc60 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 lite3_release_me
3bc70 6d 6f 72 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b mory()] is invok
3bc80 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f 72 ed one or.** mor
3bc90 65 20 74 69 6d 65 73 20 74 6f 20 66 72 65 65 20 e times to free
3bca0 75 70 20 73 6f 6d 65 20 73 70 61 63 65 20 62 65 up some space be
3bcb0 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 fore the allocat
3bcc0 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 ion is performed
3bcd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 6d 69 ..**.** The limi
3bce0 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73 6f 66 t is called "sof
3bcf0 74 22 2c 20 62 65 63 61 75 73 65 20 69 66 20 5b t", because if [
3bd00 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f sqlite3_release_
3bd10 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63 61 6e memory()].** can
3bd20 6e 6f 74 20 66 72 65 65 20 73 75 66 66 69 63 69 not free suffici
3bd30 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72 ent memory to pr
3bd40 65 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 74 20 event the limit
3bd50 66 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 65 65 from being excee
3bd60 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f ded,.** the memo
3bd70 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 ry is allocated
3bd80 61 6e 79 77 61 79 20 61 6e 64 20 74 68 65 20 63 anyway and the c
3bd90 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e urrent operation
3bda0 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a proceeds..**.**
3bdb0 20 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a A negative or z
3bdc0 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 ero value for N
3bdd0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 72 65 means that there
3bde0 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 65 61 70 is no soft heap
3bdf0 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 limit and.** [s
3be00 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d qlite3_release_m
3be10 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e emory()] will on
3be20 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 ly be called whe
3be30 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 78 68 61 n memory is exha
3be40 75 73 74 65 64 2e 0a 2a 2a 20 54 68 65 20 64 65 usted..** The de
3be50 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 fault value for
3be60 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 the soft heap li
3be70 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a mit is zero..**.
3be80 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 ** SQLite makes
3be90 61 20 62 65 73 74 20 65 66 66 6f 72 74 20 74 6f a best effort to
3bea0 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f 66 74 20 honor the soft
3beb0 68 65 61 70 20 6c 69 6d 69 74 2e 0a 2a 2a 20 42 heap limit..** B
3bec0 75 74 20 69 66 20 74 68 65 20 73 6f 66 74 20 68 ut if the soft h
3bed0 65 61 70 20 6c 69 6d 69 74 20 63 61 6e 6e 6f 74 eap limit cannot
3bee0 20 62 65 20 68 6f 6e 6f 72 65 64 2c 20 65 78 65 be honored, exe
3bef0 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 cution will.** c
3bf00 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f 75 74 20 ontinue without
3bf10 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69 66 69 63 error or notific
3bf20 61 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 73 20 ation. This is
3bf30 77 68 79 20 74 68 65 20 6c 69 6d 69 74 20 69 73 why the limit is
3bf40 0a 2a 2a 20 63 61 6c 6c 65 64 20 61 20 22 73 6f .** called a "so
3bf50 66 74 22 20 6c 69 6d 69 74 2e 20 20 49 74 20 69 ft" limit. It i
3bf60 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e s advisory only.
3bf70 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 .**.** Prior to
3bf80 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 SQLite version 3
3bf90 2e 35 2e 30 2c 20 74 68 69 73 20 72 6f 75 74 69 .5.0, this routi
3bfa0 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73 74 72 61 69 ne only constrai
3bfb0 6e 65 64 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a ned the memory.*
3bfc0 2a 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 61 * allocated by a
3bfd0 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 20 2d single thread -
3bfe0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 the same thread
3bff0 20 69 6e 20 77 68 69 63 68 20 74 68 69 73 20 72 in which this r
3c000 6f 75 74 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 outine.** runs.
3c010 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 Beginning with
3c020 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 SQLite version 3
3c030 2e 35 2e 30 2c 20 74 68 65 20 73 6f 66 74 20 68 .5.0, the soft h
3c040 65 61 70 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 eap limit is.**
3c050 61 70 70 6c 69 65 64 20 74 6f 20 61 6c 6c 20 74 applied to all t
3c060 68 72 65 61 64 73 2e 20 54 68 65 20 76 61 6c 75 hreads. The valu
3c070 65 20 73 70 65 63 69 66 69 65 64 20 66 6f 72 20 e specified for
3c080 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 the soft heap li
3c090 6d 69 74 0a 2a 2a 20 69 73 20 61 6e 20 75 70 70 mit.** is an upp
3c0a0 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 er bound on the
3c0b0 74 6f 74 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c total memory all
3c0c0 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 6c 6c 20 ocation for all
3c0d0 74 68 72 65 61 64 73 2e 20 49 6e 0a 2a 2a 20 76 threads. In.** v
3c0e0 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 74 68 65 ersion 3.5.0 the
3c0f0 72 65 20 69 73 20 6e 6f 20 6d 65 63 68 61 6e 69 re is no mechani
3c100 73 6d 20 66 6f 72 20 6c 69 6d 69 74 69 6e 67 20 sm for limiting
3c110 74 68 65 20 68 65 61 70 20 75 73 61 67 65 20 66 the heap usage f
3c120 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 64 75 61 6c or.** individual
3c130 20 74 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 threads..**.**
3c140 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
3c150 2a 20 7b 48 31 36 33 35 31 7d 20 54 68 65 20 5b * {H16351} The [
3c160 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 sqlite3_soft_hea
3c170 70 5f 6c 69 6d 69 74 28 4e 29 5d 20 69 6e 74 65 p_limit(N)] inte
3c180 72 66 61 63 65 20 70 6c 61 63 65 73 20 61 20 73 rface places a s
3c190 6f 66 74 20 6c 69 6d 69 74 0a 2a 2a 20 20 20 20 oft limit.**
3c1a0 20 20 20 20 20 20 6f 66 20 4e 20 62 79 74 65 73 of N bytes
3c1b0 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f on the amount o
3c1c0 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 f heap memory th
3c1d0 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 at may be alloca
3c1e0 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ted.**
3c1f0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d using [sqlite3_m
3c200 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c alloc()] or [sql
3c210 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 ite3_realloc()]
3c220 61 74 20 61 6e 79 20 70 6f 69 6e 74 0a 2a 2a 20 at any point.**
3c230 20 20 20 20 20 20 20 20 20 69 6e 20 74 69 6d 65 in time
3c240 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 33 35 32 7d ..**.** {H16352}
3c250 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 If a call to [s
3c260 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
3c270 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 or [sqlite3_rea
3c280 6c 6c 6f 63 28 29 5d 20 77 6f 75 6c 64 0a 2a 2a lloc()] would.**
3c290 20 20 20 20 20 20 20 20 20 20 63 61 75 73 65 20 cause
3c2a0 74 68 65 20 74 6f 74 61 6c 20 61 6d 6f 75 6e 74 the total amount
3c2b0 20 6f 66 20 61 6c 6c 6f 63 61 74 65 64 20 6d 65 of allocated me
3c2c0 6d 6f 72 79 20 74 6f 20 65 78 63 65 65 64 20 74 mory to exceed t
3c2d0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 he.** s
3c2e0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 oft heap limit,
3c2f0 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 then [sqlite3_re
3c300 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 lease_memory()]
3c310 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 is invoked.**
3c320 20 20 20 20 20 20 20 69 6e 20 61 6e 20 61 74 74 in an att
3c330 65 6d 70 74 20 74 6f 20 72 65 64 75 63 65 20 74 empt to reduce t
3c340 68 65 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 20 he memory usage
3c350 70 72 69 6f 72 20 74 6f 20 70 72 6f 63 65 65 64 prior to proceed
3c360 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ing.**
3c370 77 69 74 68 20 74 68 65 20 6d 65 6d 6f 72 79 20 with the memory
3c380 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 74 74 65 6d allocation attem
3c390 70 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 33 35 pt..**.** {H1635
3c3a0 33 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 3} Calls to [sql
3c3b0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f ite3_malloc()] o
3c3c0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c r [sqlite3_reall
3c3d0 6f 63 28 29 5d 20 74 68 61 74 20 74 72 69 67 67 oc()] that trigg
3c3e0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 er.** a
3c3f0 74 74 65 6d 70 74 73 20 74 6f 20 72 65 64 75 63 ttempts to reduc
3c400 65 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 20 74 e memory usage t
3c410 68 72 6f 75 67 68 20 74 68 65 20 73 6f 66 74 20 hrough the soft
3c420 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 20 20 heap limit.**
3c430 20 20 20 20 20 20 20 6d 65 63 68 61 6e 69 73 6d mechanism
3c440 20 63 6f 6e 74 69 6e 75 65 20 65 76 65 6e 20 69 continue even i
3c450 66 20 74 68 65 20 61 74 74 65 6d 70 74 20 74 6f f the attempt to
3c460 20 72 65 64 75 63 65 20 6d 65 6d 6f 72 79 0a 2a reduce memory.*
3c470 2a 20 20 20 20 20 20 20 20 20 20 75 73 61 67 65 * usage
3c480 20 69 73 20 75 6e 73 75 63 63 65 73 73 66 75 6c is unsuccessful
3c490 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 33 35 34 7d ..**.** {H16354}
3c4a0 20 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a A negative or z
3c4b0 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 ero value for N
3c4c0 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 in a call to.**
3c4d0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
3c4e0 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 3_soft_heap_limi
3c4f0 74 28 4e 29 5d 20 6d 65 61 6e 73 20 74 68 61 74 t(N)] means that
3c500 20 74 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 there is no sof
3c510 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 65 t.** he
3c520 61 70 20 6c 69 6d 69 74 20 61 6e 64 20 5b 73 71 ap limit and [sq
3c530 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 lite3_release_me
3c540 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c mory()] will onl
3c550 79 20 62 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 y be.**
3c560 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d called when mem
3c570 6f 72 79 20 69 73 20 63 6f 6d 70 6c 65 74 65 6c ory is completel
3c580 79 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 0a y exhausted..**.
3c590 2a 2a 20 7b 48 31 36 33 35 35 7d 20 54 68 65 20 ** {H16355} The
3c5a0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f default value fo
3c5b0 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 r the soft heap
3c5c0 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a limit is zero..*
3c5d0 2a 0a 2a 2a 20 7b 48 31 36 33 35 38 7d 20 45 61 *.** {H16358} Ea
3c5e0 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 ch call to [sqli
3c5f0 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 te3_soft_heap_li
3c600 6d 69 74 28 4e 29 5d 20 6f 76 65 72 72 69 64 65 mit(N)] override
3c610 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 s the.**
3c620 20 20 76 61 6c 75 65 73 20 73 65 74 20 62 79 20 values set by
3c630 61 6c 6c 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e all prior calls.
3c640 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 .*/.void sqlite3
3c650 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 _soft_heap_limit
3c660 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 (int);../*.** CA
3c670 50 49 33 52 45 46 3a 20 45 78 74 72 61 63 74 20 PI3REF: Extract
3c680 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74 20 41 Metadata About A
3c690 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 Column Of A Tab
3c6a0 6c 65 20 7b 48 31 32 38 35 30 7d 20 3c 53 36 30 le {H12850} <S60
3c6b0 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 300>.**.** This
3c6c0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
3c6d0 6d 65 74 61 64 61 74 61 20 61 62 6f 75 74 20 61 metadata about a
3c6e0 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e specific column
3c6f0 20 6f 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a of a specific.*
3c700 2a 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 * database table
3c710 20 61 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e accessible usin
3c720 67 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 g the [database
3c730 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 connection] hand
3c740 6c 65 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 le.** passed as
3c750 74 68 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 the first functi
3c760 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a on argument..**.
3c770 2a 2a 20 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 ** The column is
3c780 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 identified by t
3c790 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 he second, third
3c7a0 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 and fourth para
3c7b0 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69 meters to.** thi
3c7c0 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 s function. The
3c7d0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
3c7e0 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 6e is either the n
3c7f0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 ame of the datab
3c800 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 ase.** (i.e. "ma
3c810 69 6e 22 2c 20 22 74 65 6d 70 22 20 6f 72 20 61 in", "temp" or a
3c820 6e 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 n attached datab
3c830 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 ase) containing
3c840 74 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a the specified.**
3c850 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 table or NULL.
3c860 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 If it is NULL, t
3c870 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64 hen all attached
3c880 20 64 61 74 61 62 61 73 65 73 20 61 72 65 20 73 databases are s
3c890 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 earched.** for t
3c8a0 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74 he table using t
3c8b0 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 he same algorith
3c8c0 6d 20 75 73 65 64 20 62 79 20 74 68 65 20 64 61 m used by the da
3c8d0 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 74 6f tabase engine to
3c8e0 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 .** resolve unqu
3c8f0 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72 65 alified table re
3c900 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 ferences..**.**
3c910 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f The third and fo
3c920 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 urth parameters
3c930 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e to this function
3c940 20 61 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 are the table a
3c950 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d nd column.** nam
3c960 65 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 e of the desired
3c970 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 column, respect
3c980 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f ively. Neither o
3c990 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 f these paramete
3c9a0 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c rs.** may be NUL
3c9b0 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74 61 64 61 74 L..**.** Metadat
3c9c0 61 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 a is returned by
3c9d0 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20 writing to the
3c9e0 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 memory locations
3c9f0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 35 passed as the 5
3ca00 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65 71 th.** and subseq
3ca10 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20 uent parameters
3ca20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e to this function
3ca30 2e 20 41 6e 79 20 6f 66 20 74 68 65 73 65 20 61 . Any of these a
3ca40 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 0a rguments may be.
3ca50 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 ** NULL, in whic
3ca60 68 20 63 61 73 65 20 74 68 65 20 63 6f 72 72 65 h case the corre
3ca70 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 sponding element
3ca80 20 6f 66 20 6d 65 74 61 64 61 74 61 20 69 73 20 of metadata is
3ca90 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c omitted..**.** <
3caa0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c blockquote>.** <
3cab0 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 table border="1"
3cac0 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 50 61 >.** <tr><th> Pa
3cad0 72 61 6d 65 74 65 72 20 3c 74 68 3e 20 4f 75 74 rameter <th> Out
3cae0 70 75 74 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e put<br>Type <th>
3caf0 20 20 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a Description.**
3cb00 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 35 74 68 .** <tr><td> 5th
3cb10 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 <td> const char
3cb20 2a 20 3c 74 64 3e 20 44 61 74 61 20 74 79 70 65 * <td> Data type
3cb30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 36 74 68 .** <tr><td> 6th
3cb40 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 <td> const char
3cb50 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 6f 66 20 64 * <td> Name of d
3cb60 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e efault collation
3cb70 20 73 65 71 75 65 6e 63 65 0a 2a 2a 20 3c 74 72 sequence.** <tr
3cb80 3e 3c 74 64 3e 20 37 74 68 20 3c 74 64 3e 20 69 ><td> 7th <td> i
3cb90 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 nt <td>
3cba0 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 68 True if column h
3cbb0 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f as a NOT NULL co
3cbc0 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e nstraint.** <tr>
3cbd0 3c 74 64 3e 20 38 74 68 20 3c 74 64 3e 20 69 6e <td> 8th <td> in
3cbe0 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 t <td> T
3cbf0 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 rue if column is
3cc00 20 70 61 72 74 20 6f 66 20 74 68 65 20 50 52 49 part of the PRI
3cc10 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e MARY KEY.** <tr>
3cc20 3c 74 64 3e 20 39 74 68 20 3c 74 64 3e 20 69 6e <td> 9th <td> in
3cc30 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 t <td> T
3cc40 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 rue if column is
3cc50 20 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 0a 2a AUTOINCREMENT.*
3cc60 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f * </table>.** </
3cc70 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
3cc80 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 * The memory poi
3cc90 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 63 nted to by the c
3cca0 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72 haracter pointer
3ccb0 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74 s returned for t
3ccc0 68 65 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f he.** declaratio
3ccd0 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 n type and colla
3cce0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 tion sequence is
3ccf0 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 valid only unti
3cd00 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61 l the next.** ca
3cd10 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c 69 74 65 ll to any SQLite
3cd20 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a API function..*
3cd30 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63 *.** If the spec
3cd40 69 66 69 65 64 20 74 61 62 6c 65 20 69 73 20 61 ified table is a
3cd50 63 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 ctually a view,
3cd60 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 an [error code]
3cd70 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a is returned..**.
3cd80 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63 69 66 ** If the specif
3cd90 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 ied column is "r
3cda0 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 owid", "oid" or
3cdb0 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e "_rowid_" and an
3cdc0 0a 2a 2a 20 49 4e 54 45 47 45 52 20 50 52 49 4d .** INTEGER PRIM
3cdd0 41 52 59 20 4b 45 59 20 63 6f 6c 75 6d 6e 20 68 ARY KEY column h
3cde0 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74 as been explicit
3cdf0 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65 ly declared, the
3ce00 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 n the output.**
3ce10 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 parameters are s
3ce20 65 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69 et for the expli
3ce30 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 citly declared c
3ce40 6f 6c 75 6d 6e 2e 20 49 66 20 74 68 65 72 65 20 olumn. If there
3ce50 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 is no.** explici
3ce60 74 6c 79 20 64 65 63 6c 61 72 65 64 20 49 4e 54 tly declared INT
3ce70 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 EGER PRIMARY KEY
3ce80 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68 column, then th
3ce90 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 e output.** para
3cea0 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61 meters are set a
3ceb0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a s follows:.**.**
3cec0 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 <pre>.** da
3ced0 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45 ta type: "INTEGE
3cee0 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 R".** collat
3cef0 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42 ion sequence: "B
3cf00 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f INARY".** no
3cf10 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 t null: 0.**
3cf20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a primary key: 1.
3cf30 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72 ** auto incr
3cf40 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 ement: 0.** </pr
3cf50 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 e>.**.** This fu
3cf60 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 nction may load
3cf70 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 one or more sche
3cf80 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73 mas from databas
3cf90 65 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a e files. If an.*
3cfa0 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 * error occurs d
3cfb0 75 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65 uring this proce
3cfc0 73 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 ss, or if the re
3cfd0 71 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72 quested table or
3cfe0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f column.** canno
3cff0 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 5b t be found, an [
3d000 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 error code] is r
3d010 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 eturned and an e
3d020 72 72 6f 72 20 6d 65 73 73 61 67 65 20 6c 65 66 rror message lef
3d030 74 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61 74 t.** in the [dat
3d040 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
3d050 5d 20 28 74 6f 20 62 65 20 72 65 74 72 69 65 76 ] (to be retriev
3d060 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 ed using sqlite3
3d070 5f 65 72 72 6d 73 67 28 29 29 2e 0a 2a 2a 0a 2a _errmsg())..**.*
3d080 2a 20 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e * This API is on
3d090 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 ly available if
3d0a0 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 the library was
3d0b0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 compiled with th
3d0c0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 e.** [SQLITE_ENA
3d0d0 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 BLE_COLUMN_METAD
3d0e0 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 ATA] C-preproces
3d0f0 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e sor symbol defin
3d100 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ed..*/.int sqlit
3d110 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f e3_table_column_
3d120 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69 metadata(. sqli
3d130 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
3d140 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 /* Conne
3d150 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a ction handle */.
3d160 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 const char *zD
3d170 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a bName, /*
3d180 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f Database name o
3d190 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 r NULL */. cons
3d1a0 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 t char *zTableNa
3d1b0 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 me, /* Table
3d1c0 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 name */. const
3d1d0 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 char *zColumnNa
3d1e0 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e me, /* Column
3d1f0 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 name */. char
3d200 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 const **pzDataTy
3d210 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 pe, /* OUTPUT
3d220 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74 61 20 : Declared data
3d230 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 type */. char c
3d240 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 onst **pzCollSeq
3d250 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a , /* OUTPUT:
3d260 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 Collation seque
3d270 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e nce name */. in
3d280 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 t *pNotNull,
3d290 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 /* OUT
3d2a0 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 PUT: True if NOT
3d2b0 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 NULL constraint
3d2c0 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 exists */. int
3d2d0 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 *pPrimaryKey,
3d2e0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 /* OUTP
3d2f0 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 UT: True if colu
3d300 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f mn part of PK */
3d310 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 . int *pAutoinc
3d320 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
3d330 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 * OUTPUT: True i
3d340 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f f column is auto
3d350 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b -increment */.);
3d360 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
3d370 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 : Load An Extens
3d380 69 6f 6e 20 7b 48 31 32 36 30 30 7d 20 3c 53 32 ion {H12600} <S2
3d390 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 0500>.**.** This
3d3a0 20 69 6e 74 65 72 66 61 63 65 20 6c 6f 61 64 73 interface loads
3d3b0 20 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e an SQLite exten
3d3c0 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 66 72 6f sion library fro
3d3d0 6d 20 74 68 65 20 6e 61 6d 65 64 20 66 69 6c 65 m the named file
3d3e0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 31 7d ..**.** {H12601}
3d3f0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 The sqlite3_loa
3d400 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e d_extension() in
3d410 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 terface attempts
3d420 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 20 to load an.**
3d430 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 65 SQLite e
3d440 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 xtension library
3d450 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 contained in th
3d460 65 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a e file zFile..**
3d470 0a 2a 2a 20 7b 48 31 32 36 30 32 7d 20 54 68 65 .** {H12602} The
3d480 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20 entry point is
3d490 7a 50 72 6f 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 zProc..**.** {H1
3d4a0 32 36 30 33 7d 20 7a 50 72 6f 63 20 6d 61 79 20 2603} zProc may
3d4b0 62 65 20 30 2c 20 69 6e 20 77 68 69 63 68 20 63 be 0, in which c
3d4c0 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 ase the name of
3d4d0 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a the entry point.
3d4e0 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 ** defa
3d4f0 75 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33 ults to "sqlite3
3d500 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 _extension_init"
3d510 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 34 7d ..**.** {H12604}
3d520 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 The sqlite3_loa
3d530 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e d_extension() in
3d540 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 terface shall re
3d550 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 turn.**
3d560 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 [SQLITE_OK] on
3d570 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c success and [SQL
3d580 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f ITE_ERROR] if so
3d590 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f mething goes wro
3d5a0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 ng..**.** {H1260
3d5b0 35 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 5} If an error o
3d5c0 63 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72 4d ccurs and pzErrM
3d5d0 73 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68 65 sg is not 0, the
3d5e0 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 n the.**
3d5f0 20 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f [sqlite3_load_
3d600 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 extension()] int
3d610 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74 erface shall att
3d620 65 6d 70 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 empt to.**
3d630 20 20 20 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d fill *pzErrM
3d640 73 67 20 77 69 74 68 20 65 72 72 6f 72 20 6d 65 sg with error me
3d650 73 73 61 67 65 20 74 65 78 74 20 73 74 6f 72 65 ssage text store
3d660 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 d in memory.**
3d670 20 20 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64 obtained
3d680 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
3d690 61 6c 6c 6f 63 28 29 5d 2e 20 7b 45 4e 44 7d 20 alloc()]. {END}
3d6a0 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e The calling fun
3d6b0 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 ction.**
3d6c0 20 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68 should free th
3d6d0 69 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c is memory by cal
3d6e0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 ling [sqlite3_fr
3d6f0 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ee()]..**.** {H1
3d700 32 36 30 36 7d 20 45 78 74 65 6e 73 69 6f 6e 20 2606} Extension
3d710 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65 20 loading must be
3d720 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a 2a 2a enabled using.**
3d730 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
3d740 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 e3_enable_load_e
3d750 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f xtension()] prio
3d760 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 r to calling thi
3d770 73 20 41 50 49 2c 0a 2a 2a 20 20 20 20 20 20 20 s API,.**
3d780 20 20 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 otherwise an
3d790 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 error will be re
3d7a0 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 turned..*/.int s
3d7b0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 qlite3_load_exte
3d7c0 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 nsion(. sqlite3
3d7d0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f *db, /
3d7e0 2a 20 4c 6f 61 64 20 74 68 65 20 65 78 74 65 6e * Load the exten
3d7f0 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20 64 sion into this d
3d800 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
3d810 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 on */. const ch
3d820 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a ar *zFile, /*
3d830 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 68 61 Name of the sha
3d840 72 65 64 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 red library cont
3d850 61 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e aining extension
3d860 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
3d870 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45 *zProc, /* E
3d880 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 65 72 ntry point. Der
3d890 69 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20 ived from zFile
3d8a0 69 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a if 0 */. char *
3d8b0 2a 70 7a 45 72 72 4d 73 67 20 20 20 20 20 20 20 *pzErrMsg
3d8c0 2f 2a 20 50 75 74 20 65 72 72 6f 72 20 6d 65 73 /* Put error mes
3d8d0 73 61 67 65 20 68 65 72 65 20 69 66 20 6e 6f 74 sage here if not
3d8e0 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 0 */.);../*.**
3d8f0 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 CAPI3REF: Enable
3d900 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 Or Disable Exte
3d910 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b 48 nsion Loading {H
3d920 31 32 36 32 30 7d 20 3c 53 32 30 35 30 30 3e 0a 12620} <S20500>.
3d930 2a 2a 0a 2a 2a 20 53 6f 20 61 73 20 6e 6f 74 20 **.** So as not
3d940 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 74 79 to open security
3d950 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 holes in older
3d960 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 applications tha
3d970 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 t are.** unprepa
3d980 72 65 64 20 74 6f 20 64 65 61 6c 20 77 69 74 68 red to deal with
3d990 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 extension loadi
3d9a0 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 6d 65 61 ng, and as a mea
3d9b0 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a ns of disabling.
3d9c0 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 ** extension loa
3d9d0 64 69 6e 67 20 77 68 69 6c 65 20 65 76 61 6c 75 ding while evalu
3d9e0 61 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 ating user-enter
3d9f0 65 64 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c ed SQL, the foll
3da00 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 69 73 20 owing API.** is
3da10 70 72 6f 76 69 64 65 64 20 74 6f 20 74 75 72 6e provided to turn
3da20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f the [sqlite3_lo
3da30 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 ad_extension()]
3da40 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 mechanism on and
3da50 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 45 78 74 65 off..**.** Exte
3da60 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 nsion loading is
3da70 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e off by default.
3da80 20 53 65 65 20 74 69 63 6b 65 74 20 23 31 38 36 See ticket #186
3da90 33 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 32 31 3..**.** {H12621
3daa0 7d 20 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 74 } Call the sqlit
3dab0 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 e3_enable_load_e
3dac0 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69 xtension() routi
3dad0 6e 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 ne with onoff==1
3dae0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 .** to
3daf0 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c turn extension l
3db00 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61 oading on and ca
3db10 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66 ll it with onoff
3db20 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 20 ==0 to turn.**
3db30 20 20 20 20 20 20 20 20 69 74 20 62 61 63 6b 20 it back
3db40 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2a 0a 2a 2a off again..**.**
3db50 20 7b 48 31 32 36 32 32 7d 20 45 78 74 65 6e 73 {H12622} Extens
3db60 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20 6f ion loading is o
3db70 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a ff by default..*
3db80 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e /.int sqlite3_en
3db90 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 able_load_extens
3dba0 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 2c ion(sqlite3 *db,
3dbb0 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a int onoff);../*
3dbc0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 .** CAPI3REF: Au
3dbd0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64 tomatically Load
3dbe0 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 73 20 7b An Extensions {
3dbf0 48 31 32 36 34 30 7d 20 3c 53 32 30 35 30 30 3e H12640} <S20500>
3dc00 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 .**.** This API
3dc10 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64 20 61 can be invoked a
3dc20 74 20 70 72 6f 67 72 61 6d 20 73 74 61 72 74 75 t program startu
3dc30 70 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 72 65 p in order to re
3dc40 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 gister.** one or
3dc50 20 6d 6f 72 65 20 73 74 61 74 69 63 61 6c 6c 79 more statically
3dc60 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73 69 6f linked extensio
3dc70 6e 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 ns that will be
3dc80 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20 available.** to
3dc90 61 6c 6c 20 6e 65 77 20 5b 64 61 74 61 62 61 73 all new [databas
3dca0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 2e 20 e connections].
3dcb0 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 {END}.**.** This
3dcc0 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 routine stores
3dcd0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
3dce0 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e extension in an
3dcf0 20 61 72 72 61 79 20 74 68 61 74 20 69 73 0a 2a array that is.*
3dd00 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 * obtained from
3dd10 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
3dd20 29 5d 2e 20 20 49 66 20 79 6f 75 20 72 75 6e 20 )]. If you run
3dd30 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 20 63 68 a memory leak ch
3dd40 65 63 6b 65 72 0a 2a 2a 20 6f 6e 20 79 6f 75 72 ecker.** on your
3dd50 20 70 72 6f 67 72 61 6d 20 61 6e 64 20 69 74 20 program and it
3dd60 72 65 70 6f 72 74 73 20 61 20 6c 65 61 6b 20 62 reports a leak b
3dd70 65 63 61 75 73 65 20 6f 66 20 74 68 69 73 20 61 ecause of this a
3dd80 72 72 61 79 2c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 rray, invoke.**
3dd90 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 [sqlite3_reset_a
3dda0 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d uto_extension()]
3ddb0 20 70 72 69 6f 72 20 74 6f 20 73 68 75 74 64 6f prior to shutdo
3ddc0 77 6e 20 74 6f 20 66 72 65 65 20 74 68 65 20 6d wn to free the m
3ddd0 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 emory..**.** {H1
3dde0 32 36 34 31 7d 20 54 68 69 73 20 66 75 6e 63 74 2641} This funct
3ddf0 69 6f 6e 20 72 65 67 69 73 74 65 72 73 20 61 6e ion registers an
3de00 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79 extension entry
3de10 20 70 6f 69 6e 74 20 74 68 61 74 20 69 73 0a 2a point that is.*
3de20 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 6f 6d * autom
3de30 61 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 atically invoked
3de40 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77 20 whenever a new
3de50 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
3de60 74 69 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20 20 20 tion].**
3de70 20 20 69 73 20 6f 70 65 6e 65 64 20 75 73 69 6e is opened usin
3de80 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 g [sqlite3_open(
3de90 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 )], [sqlite3_ope
3dea0 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 n16()],.**
3deb0 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f or [sqlite3_
3dec0 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a open_v2()]..**.*
3ded0 2a 20 7b 48 31 32 36 34 32 7d 20 44 75 70 6c 69 * {H12642} Dupli
3dee0 63 61 74 65 20 65 78 74 65 6e 73 69 6f 6e 73 20 cate extensions
3def0 61 72 65 20 64 65 74 65 63 74 65 64 20 73 6f 20 are detected so
3df00 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 calling this rou
3df10 74 69 6e 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 tine.**
3df20 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 multiple times
3df30 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 65 78 with the same ex
3df40 74 65 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c tension is harml
3df50 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 ess..**.** {H126
3df60 34 33 7d 20 54 68 69 73 20 72 6f 75 74 69 6e 65 43} This routine
3df70 20 73 74 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 stores a pointe
3df80 72 20 74 6f 20 74 68 65 20 65 78 74 65 6e 73 69 r to the extensi
3df90 6f 6e 20 69 6e 20 61 6e 20 61 72 72 61 79 0a 2a on in an array.*
3dfa0 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 * that
3dfb0 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d is obtained from
3dfc0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
3dfd0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 ()]..**.** {H126
3dfe0 34 34 7d 20 41 75 74 6f 6d 61 74 69 63 20 65 78 44} Automatic ex
3dff0 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61 tensions apply a
3e000 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64 cross all thread
3e010 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 s..*/.int sqlite
3e020 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 3_auto_extension
3e030 28 76 6f 69 64 20 2a 78 45 6e 74 72 79 50 6f 69 (void *xEntryPoi
3e040 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 nt);../*.** CAPI
3e050 33 52 45 46 3a 20 52 65 73 65 74 20 41 75 74 6f 3REF: Reset Auto
3e060 6d 61 74 69 63 20 45 78 74 65 6e 73 69 6f 6e 20 matic Extension
3e070 4c 6f 61 64 69 6e 67 20 7b 48 31 32 36 36 30 7d Loading {H12660}
3e080 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S20500>.**.**
3e090 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 This function di
3e0a0 73 61 62 6c 65 73 20 61 6c 6c 20 70 72 65 76 69 sables all previ
3e0b0 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 ously registered
3e0c0 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 65 78 automatic.** ex
3e0d0 74 65 6e 73 69 6f 6e 73 2e 20 7b 45 4e 44 7d 20 tensions. {END}
3e0e0 20 49 74 20 75 6e 64 6f 65 73 20 74 68 65 20 65 It undoes the e
3e0f0 66 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 ffect of all pri
3e100 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 or.** [sqlite3_a
3e110 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d uto_extension()]
3e120 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 calls..**.** {H
3e130 31 32 36 36 31 7d 20 54 68 69 73 20 66 75 6e 63 12661} This func
3e140 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 6c tion disables al
3e150 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 l previously reg
3e160 69 73 74 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 istered.**
3e170 20 20 20 20 61 75 74 6f 6d 61 74 69 63 20 65 78 automatic ex
3e180 74 65 6e 73 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 tensions..**.**
3e190 7b 48 31 32 36 36 32 7d 20 54 68 69 73 20 66 75 {H12662} This fu
3e1a0 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 nction disables
3e1b0 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 automatic extens
3e1c0 69 6f 6e 73 20 69 6e 20 61 6c 6c 20 74 68 72 65 ions in all thre
3e1d0 61 64 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c ads..*/.void sql
3e1e0 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f ite3_reset_auto_
3e1f0 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b extension(void);
3e200 0a 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 ../*.****** EXPE
3e210 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 RIMENTAL - subje
3e220 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 ct to change wit
3e230 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a hout notice ****
3e240 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a **********.**.**
3e250 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 The interface t
3e260 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 o the virtual-ta
3e270 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69 73 ble mechanism is
3e280 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 currently consi
3e290 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 dered.** to be e
3e2a0 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 xperimental. Th
3e2b0 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 e interface migh
3e2c0 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f t change in inco
3e2d0 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a mpatible ways..*
3e2e0 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70 * If this is a p
3e2f0 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 roblem for you,
3e300 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 do not use the i
3e310 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73 nterface at this
3e320 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 time..**.** Whe
3e330 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 n the virtual-ta
3e340 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 ble mechanism st
3e350 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c abilizes, we wil
3e360 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a l declare the.**
3e370 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 interface fixed
3e380 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 , support it ind
3e390 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 efinitely, and r
3e3a0 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 emove this comme
3e3b0 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 nt..*/../*.** St
3e3c0 72 75 63 74 75 72 65 73 20 75 73 65 64 20 62 79 ructures used by
3e3d0 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 the virtual tab
3e3e0 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a le interface.*/.
3e3f0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
3e400 71 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c 69 qlite3_vtab sqli
3e410 74 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 65 te3_vtab;.typede
3e420 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
3e430 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69 _index_info sqli
3e440 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a te3_index_info;.
3e450 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
3e460 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 qlite3_vtab_curs
3e470 6f 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f or sqlite3_vtab_
3e480 63 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 20 cursor;.typedef
3e490 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d struct sqlite3_m
3e4a0 6f 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f odule sqlite3_mo
3e4b0 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 dule;../*.** CAP
3e4c0 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 I3REF: Virtual T
3e4d0 61 62 6c 65 20 4f 62 6a 65 63 74 20 7b 48 31 38 able Object {H18
3e4e0 30 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 000} <S20400>.**
3e4f0 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 KEYWORDS: sqlit
3e500 65 33 5f 6d 6f 64 75 6c 65 0a 2a 2a 20 45 58 50 e3_module.** EXP
3e510 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 ERIMENTAL.**.**
3e520 41 20 6d 6f 64 75 6c 65 20 69 73 20 61 20 63 6c A module is a cl
3e530 61 73 73 20 6f 66 20 76 69 72 74 75 61 6c 20 74 ass of virtual t
3e540 61 62 6c 65 73 2e 20 20 45 61 63 68 20 6d 6f 64 ables. Each mod
3e550 75 6c 65 20 69 73 20 64 65 66 69 6e 65 64 0a 2a ule is defined.*
3e560 2a 20 62 79 20 61 6e 20 69 6e 73 74 61 6e 63 65 * by an instance
3e570 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e of the followin
3e580 67 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 g structure. Th
3e590 69 73 20 73 74 72 75 63 74 75 72 65 20 63 6f 6e is structure con
3e5a0 73 69 73 74 73 0a 2a 2a 20 6d 6f 73 74 6c 79 20 sists.** mostly
3e5b0 6f 66 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 74 of methods for t
3e5c0 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a he module..**.**
3e5d0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 This interface
3e5e0 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 is experimental
3e5f0 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 and is subject t
3e600 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 o change or.** r
3e610 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 emoval in future
3e620 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c releases of SQL
3e630 69 74 65 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 ite..*/.struct s
3e640 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a qlite3_module {.
3e650 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a int iVersion;.
3e660 20 20 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29 int (*xCreate)
3e670 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 (sqlite3*, void
3e680 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 *pAux,.
3e690 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 int argc,
3e6a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 const char *cons
3e6b0 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 t*argv,.
3e6c0 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 sqlite3_v
3e6d0 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 tab **ppVTab, ch
3e6e0 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 ar**);. int (*x
3e6f0 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 Connect)(sqlite3
3e700 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 *, void *pAux,.
3e710 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e in
3e720 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 t argc, const ch
3e730 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a ar *const*argv,.
3e740 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73 s
3e750 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 qlite3_vtab **pp
3e760 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 VTab, char**);.
3e770 20 69 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65 int (*xBestInde
3e780 78 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 x)(sqlite3_vtab
3e790 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f *pVTab, sqlite3_
3e7a0 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 index_info*);.
3e7b0 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 int (*xDisconnec
3e7c0 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 t)(sqlite3_vtab
3e7d0 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 *pVTab);. int (
3e7e0 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74 *xDestroy)(sqlit
3e7f0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b e3_vtab *pVTab);
3e800 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 . int (*xOpen)(
3e810 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 sqlite3_vtab *pV
3e820 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 Tab, sqlite3_vta
3e830 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 b_cursor **ppCur
3e840 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 sor);. int (*xC
3e850 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74 lose)(sqlite3_vt
3e860 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 ab_cursor*);. i
3e870 6e 74 20 28 2a 78 46 69 6c 74 65 72 29 28 73 71 nt (*xFilter)(sq
3e880 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f lite3_vtab_curso
3e890 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 r*, int idxNum,
3e8a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 69 64 78 53 const char *idxS
3e8b0 74 72 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 tr,.
3e8c0 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 73 71 int argc, sq
3e8d0 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 lite3_value **ar
3e8e0 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65 gv);. int (*xNe
3e8f0 78 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 xt)(sqlite3_vtab
3e900 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 _cursor*);. int
3e910 20 28 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33 (*xEof)(sqlite3
3e920 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a _vtab_cursor*);.
3e930 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 int (*xColumn)
3e940 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 (sqlite3_vtab_cu
3e950 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 rsor*, sqlite3_c
3e960 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 ontext*, int);.
3e970 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29 28 73 int (*xRowid)(s
3e980 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 qlite3_vtab_curs
3e990 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 or*, sqlite3_int
3e9a0 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69 64 *pRowid);. i
3e9b0 6e 74 20 28 2a 78 55 70 64 61 74 65 29 28 73 71 nt (*xUpdate)(sq
3e9c0 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e lite3_vtab *, in
3e9d0 74 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 t, sqlite3_value
3e9e0 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 **, sqlite3_int
3e9f0 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 64 *);. int (*x
3ea00 42 65 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 Begin)(sqlite3_v
3ea10 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 tab *pVTab);. i
3ea20 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 nt (*xSync)(sqli
3ea30 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 te3_vtab *pVTab)
3ea40 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 ;. int (*xCommi
3ea50 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 t)(sqlite3_vtab
3ea60 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 *pVTab);. int (
3ea70 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 *xRollback)(sqli
3ea80 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 te3_vtab *pVTab)
3ea90 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 ;. int (*xFindF
3eaa0 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74 65 33 unction)(sqlite3
3eab0 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e _vtab *pVtab, in
3eac0 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63 68 t nArg, const ch
3ead0 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 ar *zName,.
3eae0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3eaf0 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 void (**pxFunc
3eb00 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 )(sqlite3_contex
3eb10 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 t*,int,sqlite3_v
3eb20 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20 alue**),.
3eb30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3eb40 76 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a 20 void **ppArg);.
3eb50 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 int (*xRename)(
3eb60 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 sqlite3_vtab *pV
3eb70 74 61 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 tab, const char
3eb80 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a *zNew);.};../*.*
3eb90 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 * CAPI3REF: Virt
3eba0 75 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 69 ual Table Indexi
3ebb0 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 7b ng Information {
3ebc0 48 31 38 31 30 30 7d 20 3c 53 32 30 34 30 30 3e H18100} <S20400>
3ebd0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 .** KEYWORDS: sq
3ebe0 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f lite3_index_info
3ebf0 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c .** EXPERIMENTAL
3ec00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
3ec10 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 e3_index_info st
3ec20 72 75 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 ructure and its
3ec30 73 75 62 73 74 72 75 63 74 75 72 65 73 20 69 73 substructures is
3ec40 20 75 73 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73 used to.** pass
3ec50 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 information int
3ec60 6f 20 61 6e 64 20 72 65 63 65 69 76 65 20 74 68 o and receive th
3ec70 65 20 72 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 e reply from the
3ec80 20 78 42 65 73 74 49 6e 64 65 78 0a 2a 2a 20 6d xBestIndex.** m
3ec90 65 74 68 6f 64 20 6f 66 20 61 6e 20 73 71 6c 69 ethod of an sqli
3eca0 74 65 33 5f 6d 6f 64 75 6c 65 2e 20 20 54 68 65 te3_module. The
3ecb0 20 66 69 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a fields under **
3ecc0 49 6e 70 75 74 73 2a 2a 20 61 72 65 20 74 68 65 Inputs** are the
3ecd0 0a 2a 2a 20 69 6e 70 75 74 73 20 74 6f 20 78 42 .** inputs to xB
3ece0 65 73 74 49 6e 64 65 78 20 61 6e 64 20 61 72 65 estIndex and are
3ecf0 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 read-only. xBe
3ed00 73 74 49 6e 64 65 78 20 69 6e 73 65 72 74 73 20 stIndex inserts
3ed10 69 74 73 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 its.** results i
3ed20 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 nto the **Output
3ed30 73 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a s** fields..**.*
3ed40 2a 20 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e * The aConstrain
3ed50 74 5b 5d 20 61 72 72 61 79 20 72 65 63 6f 72 64 t[] array record
3ed60 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 s WHERE clause c
3ed70 6f 6e 73 74 72 61 69 6e 74 73 20 6f 66 20 74 68 onstraints of th
3ed80 65 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 70 e form:.**.** <p
3ed90 72 65 3e 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 re>column OP exp
3eda0 72 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 r</pre>.**.** wh
3edb0 65 72 65 20 4f 50 20 69 73 20 3d 2c 20 26 6c 74 ere OP is =, <
3edc0 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 ;, <=, >,
3edd0 6f 72 20 26 67 74 3b 3d 2e 20 20 54 68 65 20 70 or >=. The p
3ede0 61 72 74 69 63 75 6c 61 72 20 6f 70 65 72 61 74 articular operat
3edf0 6f 72 20 69 73 0a 2a 2a 20 73 74 6f 72 65 64 20 or is.** stored
3ee00 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d in aConstraint[]
3ee10 2e 6f 70 2e 20 20 54 68 65 20 69 6e 64 65 78 20 .op. The index
3ee20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 of the column is
3ee30 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61 43 stored in.** aC
3ee40 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c onstraint[].iCol
3ee50 75 6d 6e 2e 20 20 61 43 6f 6e 73 74 72 61 69 6e umn. aConstrain
3ee60 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73 20 54 52 t[].usable is TR
3ee70 55 45 20 69 66 20 74 68 65 0a 2a 2a 20 65 78 70 UE if the.** exp
3ee80 72 20 6f 6e 20 74 68 65 20 72 69 67 68 74 2d 68 r on the right-h
3ee90 61 6e 64 20 73 69 64 65 20 63 61 6e 20 62 65 20 and side can be
3eea0 65 76 61 6c 75 61 74 65 64 20 28 61 6e 64 20 74 evaluated (and t
3eeb0 68 75 73 20 74 68 65 20 63 6f 6e 73 74 72 61 69 hus the constrai
3eec0 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62 6c 65 29 nt.** is usable)
3eed0 20 61 6e 64 20 66 61 6c 73 65 20 69 66 20 69 74 and false if it
3eee0 20 63 61 6e 6e 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54 cannot..**.** T
3eef0 68 65 20 6f 70 74 69 6d 69 7a 65 72 20 61 75 74 he optimizer aut
3ef00 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 65 72 omatically inver
3ef10 74 73 20 74 65 72 6d 73 20 6f 66 20 74 68 65 20 ts terms of the
3ef20 66 6f 72 6d 20 22 65 78 70 72 20 4f 50 20 63 6f form "expr OP co
3ef30 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b lumn".** and mak
3ef40 65 73 20 6f 74 68 65 72 20 73 69 6d 70 6c 69 66 es other simplif
3ef50 69 63 61 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 ications to the
3ef60 57 48 45 52 45 20 63 6c 61 75 73 65 20 69 6e 20 WHERE clause in
3ef70 61 6e 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a an attempt to.**
3ef80 20 67 65 74 20 61 73 20 6d 61 6e 79 20 57 48 45 get as many WHE
3ef90 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 RE clause terms
3efa0 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d 20 73 68 into the form sh
3efb0 6f 77 6e 20 61 62 6f 76 65 20 61 73 20 70 6f 73 own above as pos
3efc0 73 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 20 61 43 sible..** The aC
3efd0 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 onstraint[] arra
3efe0 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 57 y only reports W
3eff0 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d HERE clause term
3f000 73 20 69 6e 20 74 68 65 20 63 6f 72 72 65 63 74 s in the correct
3f010 0a 2a 2a 20 66 6f 72 6d 20 74 68 61 74 20 72 65 .** form that re
3f020 66 65 72 20 74 6f 20 74 68 65 20 70 61 72 74 69 fer to the parti
3f030 63 75 6c 61 72 20 76 69 72 74 75 61 6c 20 74 61 cular virtual ta
3f040 62 6c 65 20 62 65 69 6e 67 20 71 75 65 72 69 65 ble being querie
3f050 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 66 6f 72 6d 61 d..**.** Informa
3f060 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4f tion about the O
3f070 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 69 RDER BY clause i
3f080 73 20 73 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 s stored in aOrd
3f090 65 72 42 79 5b 5d 2e 0a 2a 2a 20 45 61 63 68 20 erBy[]..** Each
3f0a0 74 65 72 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 term of aOrderBy
3f0b0 20 72 65 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d records a colum
3f0c0 6e 20 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42 n of the ORDER B
3f0d0 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 Y clause..**.**
3f0e0 54 68 65 20 78 42 65 73 74 49 6e 64 65 78 20 6d The xBestIndex m
3f0f0 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 ethod must fill
3f100 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 aConstraintUsage
3f110 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 [] with informat
3f120 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 ion.** about wha
3f130 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 t parameters to
3f140 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e pass to xFilter.
3f150 20 20 49 66 20 61 72 67 76 49 6e 64 65 78 3e 30 If argvIndex>0
3f160 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67 then.** the rig
3f170 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 ht-hand side of
3f180 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e the correspondin
3f190 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 g aConstraint[]
3f1a0 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 is evaluated.**
3f1b0 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 and becomes the
3f1c0 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65 6e 74 argvIndex-th ent
3f1d0 72 79 20 69 6e 20 61 72 67 76 2e 20 20 49 66 20 ry in argv. If
3f1e0 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 aConstraintUsage
3f1f0 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72 [].omit.** is tr
3f200 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6e ue, then the con
3f210 73 74 72 61 69 6e 74 20 69 73 20 61 73 73 75 6d straint is assum
3f220 65 64 20 74 6f 20 62 65 20 66 75 6c 6c 79 20 68 ed to be fully h
3f230 61 6e 64 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a andled by the.**
3f240 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 virtual table a
3f250 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 63 6b 65 nd is not checke
3f260 64 20 61 67 61 69 6e 20 62 79 20 53 51 4c 69 74 d again by SQLit
3f270 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 64 78 e..**.** The idx
3f280 4e 75 6d 20 61 6e 64 20 69 64 78 50 74 72 20 76 Num and idxPtr v
3f290 61 6c 75 65 73 20 61 72 65 20 72 65 63 6f 72 64 alues are record
3f2a0 65 64 20 61 6e 64 20 70 61 73 73 65 64 20 69 6e ed and passed in
3f2b0 74 6f 20 78 46 69 6c 74 65 72 2e 0a 2a 2a 20 73 to xFilter..** s
3f2c0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 qlite3_free() is
3f2d0 20 75 73 65 64 20 74 6f 20 66 72 65 65 20 69 64 used to free id
3f2e0 78 50 74 72 20 69 66 20 6e 65 65 64 54 6f 46 72 xPtr if needToFr
3f2f0 65 65 49 64 78 50 74 72 20 69 73 20 74 72 75 65 eeIdxPtr is true
3f300 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 72 64 65 ..**.** The orde
3f310 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d 65 61 6e rByConsumed mean
3f320 73 20 74 68 61 74 20 6f 75 74 70 75 74 20 66 72 s that output fr
3f330 6f 6d 20 78 46 69 6c 74 65 72 20 77 69 6c 6c 20 om xFilter will
3f340 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65 20 occur in.** the
3f350 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20 74 6f correct order to
3f360 20 73 61 74 69 73 66 79 20 74 68 65 20 4f 52 44 satisfy the ORD
3f370 45 52 20 42 59 20 63 6c 61 75 73 65 20 73 6f 20 ER BY clause so
3f380 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61 74 65 that no separate
3f390 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74 65 70 .** sorting step
3f3a0 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a is required..**
3f3b0 0a 2a 2a 20 54 68 65 20 65 73 74 69 6d 61 74 65 .** The estimate
3f3c0 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73 20 61 dCost value is a
3f3d0 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 74 68 n estimate of th
3f3e0 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e 67 20 e cost of doing
3f3f0 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 the.** particula
3f400 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66 75 6c r lookup. A ful
3f410 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61 62 6c l scan of a tabl
3f420 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69 65 73 e with N entries
3f430 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 should have.**
3f440 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20 41 20 a cost of N. A
3f450 62 69 6e 61 72 79 20 73 65 61 72 63 68 20 6f 66 binary search of
3f460 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20 65 6e a table of N en
3f470 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 tries should hav
3f480 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 61 e a.** cost of a
3f490 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c 6f 67 pproximately log
3f4a0 28 4e 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 (N)..**.** This
3f4b0 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 70 interface is exp
3f4c0 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 erimental and is
3f4d0 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e subject to chan
3f4e0 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c ge or.** removal
3f4f0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 in future relea
3f500 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a ses of SQLite..*
3f510 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 /.struct sqlite3
3f520 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a 20 20 _index_info {.
3f530 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20 20 69 /* Inputs */. i
3f540 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b 20 nt nConstraint;
3f550 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d /* Num
3f560 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20 69 ber of entries i
3f570 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a 2f n aConstraint */
3f580 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 . struct sqlite
3f590 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 3_index_constrai
3f5a0 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 nt {. int iC
3f5b0 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 olumn;
3f5c0 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e /* Column on
3f5d0 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 left-hand side
3f5e0 6f 66 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f of constraint */
3f5f0 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 . unsigned c
3f600 68 61 72 20 6f 70 3b 20 20 20 20 20 20 20 20 20 har op;
3f610 2f 2a 20 43 6f 6e 73 74 72 61 69 6e 74 20 6f 70 /* Constraint op
3f620 65 72 61 74 6f 72 20 2a 2f 0a 20 20 20 20 20 75 erator */. u
3f630 6e 73 69 67 6e 65 64 20 63 68 61 72 20 75 73 61 nsigned char usa
3f640 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54 72 75 65 ble; /* True
3f650 20 69 66 20 74 68 69 73 20 63 6f 6e 73 74 72 61 if this constra
3f660 69 6e 74 20 69 73 20 75 73 61 62 6c 65 20 2a 2f int is usable */
3f670 0a 20 20 20 20 20 69 6e 74 20 69 54 65 72 6d 4f . int iTermO
3f680 66 66 73 65 74 3b 20 20 20 20 20 20 20 20 20 20 ffset;
3f690 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c /* Used internal
3f6a0 6c 79 20 2d 20 78 42 65 73 74 49 6e 64 65 78 20 ly - xBestIndex
3f6b0 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65 20 2a 2f should ignore */
3f6c0 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e . } *aConstrain
3f6d0 74 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a t; /*
3f6e0 20 54 61 62 6c 65 20 6f 66 20 57 48 45 52 45 20 Table of WHERE
3f6f0 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e clause constrain
3f700 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72 64 ts */. int nOrd
3f710 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 20 20 erBy;
3f720 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 /* Number of
3f730 74 65 72 6d 73 20 69 6e 20 74 68 65 20 4f 52 44 terms in the ORD
3f740 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a ER BY clause */.
3f750 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 struct sqlite3
3f760 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62 79 20 7b _index_orderby {
3f770 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d . int iColum
3f780 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 n;
3f790 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 /* Column number
3f7a0 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 */. unsigne
3f7b0 64 20 63 68 61 72 20 64 65 73 63 3b 20 20 20 20 d char desc;
3f7c0 20 20 20 2f 2a 20 54 72 75 65 20 66 6f 72 20 44 /* True for D
3f7d0 45 53 43 2e 20 20 46 61 6c 73 65 20 66 6f 72 20 ESC. False for
3f7e0 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72 ASC. */. } *aOr
3f7f0 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 20 derBy;
3f800 20 20 20 20 20 2f 2a 20 54 68 65 20 4f 52 44 45 /* The ORDE
3f810 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 R BY clause */.
3f820 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f 0a 20 /* Outputs */.
3f830 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
3f840 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 index_constraint
3f850 5f 75 73 61 67 65 20 7b 0a 20 20 20 20 69 6e 74 _usage {. int
3f860 20 61 72 67 76 49 6e 64 65 78 3b 20 20 20 20 20 argvIndex;
3f870 20 20 20 20 20 20 2f 2a 20 69 66 20 3e 30 2c 20 /* if >0,
3f880 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 70 61 constraint is pa
3f890 72 74 20 6f 66 20 61 72 67 76 20 74 6f 20 78 46 rt of argv to xF
3f8a0 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75 6e 73 ilter */. uns
3f8b0 69 67 6e 65 64 20 63 68 61 72 20 6f 6d 69 74 3b igned char omit;
3f8c0 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 /* Do not
3f8d0 63 6f 64 65 20 61 20 74 65 73 74 20 66 6f 72 20 code a test for
3f8e0 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 this constraint
3f8f0 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 */. } *aConstra
3f900 69 6e 74 55 73 61 67 65 3b 0a 20 20 69 6e 74 20 intUsage;. int
3f910 69 64 78 4e 75 6d 3b 20 20 20 20 20 20 20 20 20 idxNum;
3f920 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 /* Number
3f930 20 75 73 65 64 20 74 6f 20 69 64 65 6e 74 69 66 used to identif
3f940 79 20 74 68 65 20 69 6e 64 65 78 20 2a 2f 0a 20 y the index */.
3f950 20 63 68 61 72 20 2a 69 64 78 53 74 72 3b 20 20 char *idxStr;
3f960 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 /* S
3f970 74 72 69 6e 67 2c 20 70 6f 73 73 69 62 6c 79 20 tring, possibly
3f980 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 obtained from sq
3f990 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a lite3_malloc */.
3f9a0 20 20 69 6e 74 20 6e 65 65 64 54 6f 46 72 65 65 int needToFree
3f9b0 49 64 78 53 74 72 3b 20 20 20 20 20 20 2f 2a 20 IdxStr; /*
3f9c0 46 72 65 65 20 69 64 78 53 74 72 20 75 73 69 6e Free idxStr usin
3f9d0 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 g sqlite3_free()
3f9e0 20 69 66 20 74 72 75 65 20 2a 2f 0a 20 20 69 6e if true */. in
3f9f0 74 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 t orderByConsume
3fa00 64 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65 d; /* True
3fa10 20 69 66 20 6f 75 74 70 75 74 20 69 73 20 61 6c if output is al
3fa20 72 65 61 64 79 20 6f 72 64 65 72 65 64 20 2a 2f ready ordered */
3fa30 0a 20 20 64 6f 75 62 6c 65 20 65 73 74 69 6d 61 . double estima
3fa40 74 65 64 43 6f 73 74 3b 20 20 20 20 20 20 2f 2a tedCost; /*
3fa50 20 45 73 74 69 6d 61 74 65 64 20 63 6f 73 74 20 Estimated cost
3fa60 6f 66 20 75 73 69 6e 67 20 74 68 69 73 20 69 6e of using this in
3fa70 64 65 78 20 2a 2f 0a 7d 3b 0a 23 64 65 66 69 6e dex */.};.#defin
3fa80 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 e SQLITE_INDEX_C
3fa90 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 20 20 20 ONSTRAINT_EQ
3faa0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
3fab0 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e _INDEX_CONSTRAIN
3fac0 54 5f 47 54 20 20 20 20 34 0a 23 64 65 66 69 6e T_GT 4.#defin
3fad0 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 e SQLITE_INDEX_C
3fae0 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20 20 20 20 ONSTRAINT_LE
3faf0 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 8.#define SQLITE
3fb00 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e _INDEX_CONSTRAIN
3fb10 54 5f 4c 54 20 20 20 20 31 36 0a 23 64 65 66 69 T_LT 16.#defi
3fb20 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f ne SQLITE_INDEX_
3fb30 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45 20 20 20 CONSTRAINT_GE
3fb40 20 33 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 32.#define SQLI
3fb50 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 TE_INDEX_CONSTRA
3fb60 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a 0a 2f 2a INT_MATCH 64../*
3fb70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
3fb80 67 69 73 74 65 72 20 41 20 56 69 72 74 75 61 6c gister A Virtual
3fb90 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 Table Implement
3fba0 61 74 69 6f 6e 20 7b 48 31 38 32 30 30 7d 20 3c ation {H18200} <
3fbb0 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 S20400>.** EXPER
3fbc0 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 IMENTAL.**.** Th
3fbd0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 is routine is us
3fbe0 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 ed to register a
3fbf0 20 6e 65 77 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 new module name
3fc00 20 77 69 74 68 20 61 0a 2a 2a 20 5b 64 61 74 61 with a.** [data
3fc10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
3fc20 2e 20 20 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 . Module names
3fc30 6d 75 73 74 20 62 65 20 72 65 67 69 73 74 65 72 must be register
3fc40 65 64 20 62 65 66 6f 72 65 0a 2a 2a 20 63 72 65 ed before.** cre
3fc50 61 74 69 6e 67 20 6e 65 77 20 76 69 72 74 75 61 ating new virtua
3fc60 6c 20 74 61 62 6c 65 73 20 6f 6e 20 74 68 65 20 l tables on the
3fc70 6d 6f 64 75 6c 65 2c 20 6f 72 20 62 65 66 6f 72 module, or befor
3fc80 65 20 75 73 69 6e 67 0a 2a 2a 20 70 72 65 65 78 e using.** preex
3fc90 69 73 74 69 6e 67 20 76 69 72 74 75 61 6c 20 74 isting virtual t
3fca0 61 62 6c 65 73 20 6f 66 20 74 68 65 20 6d 6f 64 ables of the mod
3fcb0 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ule..**.** This
3fcc0 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 70 interface is exp
3fcd0 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 erimental and is
3fce0 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e subject to chan
3fcf0 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c ge or.** removal
3fd00 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 in future relea
3fd10 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a ses of SQLite..*
3fd20 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d /.SQLITE_EXPERIM
3fd30 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 ENTAL int sqlite
3fd40 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 3_create_module(
3fd50 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
3fd60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
3fd70 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 SQLite connecti
3fd80 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d on to register m
3fd90 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 odule with */.
3fda0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
3fdb0 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 e, /* Na
3fdc0 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 me of the module
3fdd0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 */. const sqli
3fde0 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20 20 te3_module *,
3fdf0 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 /* Methods for
3fe00 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 the module */.
3fe10 76 6f 69 64 20 2a 20 20 20 20 20 20 20 20 20 20 void *
3fe20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c /* Cl
3fe30 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 ient data for xC
3fe40 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a reate/xConnect *
3fe50 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.);../*.** CAPI
3fe60 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 3REF: Register A
3fe70 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 Virtual Table I
3fe80 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 7b 48 mplementation {H
3fe90 31 38 32 31 30 7d 20 3c 53 32 30 34 30 30 3e 0a 18210} <S20400>.
3fea0 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a ** EXPERIMENTAL.
3feb0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
3fec0 6e 65 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 ne is identical
3fed0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
3fee0 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d create_module()]
3fef0 20 6d 65 74 68 6f 64 20 61 62 6f 76 65 2c 0a 2a method above,.*
3ff00 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 * except that it
3ff10 20 61 6c 6c 6f 77 73 20 61 20 64 65 73 74 72 75 allows a destru
3ff20 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 74 6f ctor function to
3ff30 20 62 65 20 73 70 65 63 69 66 69 65 64 2e 20 49 be specified. I
3ff40 74 20 69 73 0a 2a 2a 20 65 76 65 6e 20 6d 6f 72 t is.** even mor
3ff50 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 74 e experimental t
3ff60 68 61 6e 20 74 68 65 20 72 65 73 74 20 6f 66 20 han the rest of
3ff70 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c the virtual tabl
3ff80 65 73 20 41 50 49 2e 0a 2a 2f 0a 53 51 4c 49 54 es API..*/.SQLIT
3ff90 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 E_EXPERIMENTAL i
3ffa0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 nt sqlite3_creat
3ffb0 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73 e_module_v2(. s
3ffc0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
3ffd0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c /* SQL
3ffe0 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 ite connection t
3fff0 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c o register modul
40000 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 e with */. cons
40010 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 t char *zName,
40020 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f /* Name o
40030 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a f the module */.
40040 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f const sqlite3_
40050 6d 6f 64 75 6c 65 20 2a 2c 20 20 20 20 2f 2a 20 module *, /*
40060 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 Methods for the
40070 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 module */. void
40080 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 *,
40090 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 /* Client
400a0 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 data for xCreat
400b0 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20 e/xConnect */.
400c0 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 void(*xDestroy)(
400d0 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f void*) /* Mo
400e0 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72 20 dule destructor
400f0 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a function */.);..
40100 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
40110 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e Virtual Table In
40120 73 74 61 6e 63 65 20 4f 62 6a 65 63 74 20 7b 48 stance Object {H
40130 31 38 30 31 30 7d 20 3c 53 32 30 34 30 30 3e 0a 18010} <S20400>.
40140 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c ** KEYWORDS: sql
40150 69 74 65 33 5f 76 74 61 62 0a 2a 2a 20 45 58 50 ite3_vtab.** EXP
40160 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 ERIMENTAL.**.**
40170 45 76 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70 Every module imp
40180 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 lementation uses
40190 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 a subclass of t
401a0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 he following str
401b0 75 63 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73 ucture.** to des
401c0 63 72 69 62 65 20 61 20 70 61 72 74 69 63 75 6c cribe a particul
401d0 61 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 ar instance of t
401e0 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 he module. Each
401f0 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a subclass will.*
40200 2a 20 62 65 20 74 61 69 6c 6f 72 65 64 20 74 6f * be tailored to
40210 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 the specific ne
40220 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c eds of the modul
40230 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
40240 2e 0a 2a 2a 20 54 68 65 20 70 75 72 70 6f 73 65 ..** The purpose
40250 20 6f 66 20 74 68 69 73 20 73 75 70 65 72 63 6c of this supercl
40260 61 73 73 20 69 73 20 74 6f 20 64 65 66 69 6e 65 ass is to define
40270 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64 73 20 certain fields
40280 74 68 61 74 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d that are.** comm
40290 6f 6e 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 on to all module
402a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
402b0 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 ..**.** Virtual
402c0 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73 20 63 tables methods c
402d0 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f 72 20 an set an error
402e0 6d 65 73 73 61 67 65 20 62 79 20 61 73 73 69 67 message by assig
402f0 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e 67 ning a.** string
40300 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
40310 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
40320 29 5d 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 )] to zErrMsg.
40330 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c The method shoul
40340 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20 74 d.** take care t
40350 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73 74 hat any prior st
40360 72 69 6e 67 20 69 73 20 66 72 65 65 64 20 62 79 ring is freed by
40370 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 a call to [sqli
40380 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 70 te3_free()].** p
40390 72 69 6f 72 20 74 6f 20 61 73 73 69 67 6e 69 6e rior to assignin
403a0 67 20 61 20 6e 65 77 20 73 74 72 69 6e 67 20 74 g a new string t
403b0 6f 20 7a 45 72 72 4d 73 67 2e 20 20 41 66 74 65 o zErrMsg. Afte
403c0 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 r the error mess
403d0 61 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 age.** is delive
403e0 72 65 64 20 75 70 20 74 6f 20 74 68 65 20 63 6c red up to the cl
403f0 69 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e ient application
40400 2c 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c , the string wil
40410 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c l be automatical
40420 6c 79 0a 2a 2a 20 66 72 65 65 64 20 62 79 20 73 ly.** freed by s
40430 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61 6e qlite3_free() an
40440 64 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 d the zErrMsg fi
40450 65 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f eld will be zero
40460 65 64 2e 20 20 4e 6f 74 65 0a 2a 2a 20 74 68 61 ed. Note.** tha
40470 74 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 t sqlite3_mprint
40480 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f f() and sqlite3_
40490 66 72 65 65 28 29 20 61 72 65 20 75 73 65 64 20 free() are used
404a0 6f 6e 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66 on the zErrMsg f
404b0 69 65 6c 64 0a 2a 2a 20 73 69 6e 63 65 20 76 69 ield.** since vi
404c0 72 74 75 61 6c 20 74 61 62 6c 65 73 20 61 72 65 rtual tables are
404d0 20 63 6f 6d 6d 6f 6e 6c 79 20 69 6d 70 6c 65 6d commonly implem
404e0 65 6e 74 65 64 20 69 6e 20 6c 6f 61 64 61 62 6c ented in loadabl
404f0 65 20 65 78 74 65 6e 73 69 6f 6e 73 20 77 68 69 e extensions whi
40500 63 68 0a 2a 2a 20 64 6f 20 6e 6f 74 20 68 61 76 ch.** do not hav
40510 65 20 61 63 63 65 73 73 20 74 6f 20 73 71 6c 69 e access to sqli
40520 74 65 33 4d 50 72 69 6e 74 66 28 29 20 6f 72 20 te3MPrintf() or
40530 73 71 6c 69 74 65 33 46 72 65 65 28 29 2e 0a 2a sqlite3Free()..*
40540 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 *.** This interf
40550 61 63 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e ace is experimen
40560 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 tal and is subje
40570 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a ct to change or.
40580 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 ** removal in fu
40590 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 ture releases of
405a0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 73 74 72 75 SQLite..*/.stru
405b0 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 ct sqlite3_vtab
405c0 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 {. const sqlite
405d0 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 3_module *pModul
405e0 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c e; /* The modul
405f0 65 20 66 6f 72 20 74 68 69 73 20 76 69 72 74 75 e for this virtu
40600 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e al table */. in
40610 74 20 6e 52 65 66 3b 20 20 20 20 20 20 20 20 20 t nRef;
40620 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
40630 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 Used internally
40640 20 2a 2f 0a 20 20 63 68 61 72 20 2a 7a 45 72 72 */. char *zErr
40650 4d 73 67 3b 20 20 20 20 20 20 20 20 20 20 20 20 Msg;
40660 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d /* Error m
40670 65 73 73 61 67 65 20 66 72 6f 6d 20 73 71 6c 69 essage from sqli
40680 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 2a 2f te3_mprintf() */
40690 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 . /* Virtual ta
406a0 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ble implementati
406b0 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c ons will typical
406c0 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 ly add additiona
406d0 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a l fields */.};..
406e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
406f0 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 43 75 Virtual Table Cu
40700 72 73 6f 72 20 4f 62 6a 65 63 74 20 20 7b 48 31 rsor Object {H1
40710 38 30 32 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 8020} <S20400>.*
40720 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 * KEYWORDS: sqli
40730 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 0a te3_vtab_cursor.
40740 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a ** EXPERIMENTAL.
40750 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 6d 6f 64 75 **.** Every modu
40760 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
40770 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 n uses a subclas
40780 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 s of the followi
40790 6e 67 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 ng structure.**
407a0 74 6f 20 64 65 73 63 72 69 62 65 20 63 75 72 73 to describe curs
407b0 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74 20 69 ors that point i
407c0 6e 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 20 nto the virtual
407d0 74 61 62 6c 65 20 61 6e 64 20 61 72 65 20 75 73 table and are us
407e0 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74 68 ed.** to loop th
407f0 72 6f 75 67 68 20 74 68 65 20 76 69 72 74 75 61 rough the virtua
40800 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 73 6f 72 l table. Cursor
40810 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 s are created us
40820 69 6e 67 20 74 68 65 0a 2a 2a 20 78 4f 70 65 6e ing the.** xOpen
40830 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 6d method of the m
40840 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64 odule. Each mod
40850 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ule implementati
40860 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a on will define.*
40870 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 * the content of
40880 20 61 20 63 75 72 73 6f 72 20 73 74 72 75 63 74 a cursor struct
40890 75 72 65 20 74 6f 20 73 75 69 74 20 69 74 73 20 ure to suit its
408a0 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a own needs..**.**
408b0 20 54 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 This superclass
408c0 20 65 78 69 73 74 73 20 69 6e 20 6f 72 64 65 72 exists in order
408d0 20 74 6f 20 64 65 66 69 6e 65 20 66 69 65 6c 64 to define field
408e0 73 20 6f 66 20 74 68 65 20 63 75 72 73 6f 72 20 s of the cursor
408f0 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d that.** are comm
40900 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d on to all implem
40910 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a entations..**.**
40920 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 This interface
40930 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 is experimental
40940 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 and is subject t
40950 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 o change or.** r
40960 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 emoval in future
40970 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c releases of SQL
40980 69 74 65 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 ite..*/.struct s
40990 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 qlite3_vtab_curs
409a0 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76 or {. sqlite3_v
409b0 74 61 62 20 2a 70 56 74 61 62 3b 20 20 20 20 20 tab *pVtab;
409c0 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c /* Virtual tabl
409d0 65 20 6f 66 20 74 68 69 73 20 63 75 72 73 6f 72 e of this cursor
409e0 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c */. /* Virtual
409f0 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 table implement
40a00 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 ations will typi
40a10 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 cally add additi
40a20 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d onal fields */.}
40a30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
40a40 46 3a 20 44 65 63 6c 61 72 65 20 54 68 65 20 53 F: Declare The S
40a50 63 68 65 6d 61 20 4f 66 20 41 20 56 69 72 74 75 chema Of A Virtu
40a60 61 6c 20 54 61 62 6c 65 20 7b 48 31 38 32 38 30 al Table {H18280
40a70 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58 } <S20400>.** EX
40a80 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a PERIMENTAL.**.**
40a90 20 54 68 65 20 78 43 72 65 61 74 65 20 61 6e 64 The xCreate and
40aa0 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 xConnect method
40ab0 73 20 6f 66 20 61 20 6d 6f 64 75 6c 65 20 75 73 s of a module us
40ac0 65 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 e the following
40ad0 41 50 49 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72 API.** to declar
40ae0 65 20 74 68 65 20 66 6f 72 6d 61 74 20 28 74 68 e the format (th
40af0 65 20 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 61 e names and data
40b00 74 79 70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c types of the col
40b10 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20 umns) of.** the
40b20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 74 virtual tables t
40b30 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a hey implement..*
40b40 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 *.** This interf
40b50 61 63 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e ace is experimen
40b60 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 tal and is subje
40b70 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a ct to change or.
40b80 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 ** removal in fu
40b90 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 ture releases of
40ba0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 SQLite..*/.SQLI
40bb0 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 TE_EXPERIMENTAL
40bc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 65 63 6c int sqlite3_decl
40bd0 61 72 65 5f 76 74 61 62 28 73 71 6c 69 74 65 33 are_vtab(sqlite3
40be0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
40bf0 43 72 65 61 74 65 54 61 62 6c 65 29 3b 0a 0a 2f CreateTable);../
40c00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
40c10 76 65 72 6c 6f 61 64 20 41 20 46 75 6e 63 74 69 verload A Functi
40c20 6f 6e 20 46 6f 72 20 41 20 56 69 72 74 75 61 6c on For A Virtual
40c30 20 54 61 62 6c 65 20 7b 48 31 38 33 30 30 7d 20 Table {H18300}
40c40 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 <S20400>.** EXPE
40c50 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 56 RIMENTAL.**.** V
40c60 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 irtual tables ca
40c70 6e 20 70 72 6f 76 69 64 65 20 61 6c 74 65 72 6e n provide altern
40c80 61 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 ative implementa
40c90 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f tions of functio
40ca0 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 ns.** using the
40cb0 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 20 6d 65 xFindFunction me
40cc0 74 68 6f 64 2e 20 20 42 75 74 20 67 6c 6f 62 61 thod. But globa
40cd0 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 l versions of th
40ce0 6f 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a ose functions.**
40cf0 20 6d 75 73 74 20 65 78 69 73 74 20 69 6e 20 6f must exist in o
40d00 72 64 65 72 20 74 6f 20 62 65 20 6f 76 65 72 6c rder to be overl
40d10 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 oaded..**.** Thi
40d20 73 20 41 50 49 20 6d 61 6b 65 73 20 73 75 72 65 s API makes sure
40d30 20 61 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f a global versio
40d40 6e 20 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e 20 n of a function
40d50 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 with a particula
40d60 72 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75 r.** name and nu
40d70 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 mber of paramete
40d80 72 73 20 65 78 69 73 74 73 2e 20 20 49 66 20 6e rs exists. If n
40d90 6f 20 73 75 63 68 20 66 75 6e 63 74 69 6f 6e 20 o such function
40da0 65 78 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65 exists.** before
40db0 20 74 68 69 73 20 41 50 49 20 69 73 20 63 61 6c this API is cal
40dc0 6c 65 64 2c 20 61 20 6e 65 77 20 66 75 6e 63 74 led, a new funct
40dd0 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64 2e 20 ion is created.
40de0 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 The implementat
40df0 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 65 ion.** of the ne
40e00 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61 79 w function alway
40e10 73 20 63 61 75 73 65 73 20 61 6e 20 65 78 63 65 s causes an exce
40e20 70 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 72 6f ption to be thro
40e30 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20 6e wn. So.** the n
40e40 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e ew function is n
40e50 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79 74 ot good for anyt
40e60 68 69 6e 67 20 62 79 20 69 74 73 65 6c 66 2e 20 hing by itself.
40e70 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72 Its only.** pur
40e80 70 6f 73 65 20 69 73 20 74 6f 20 62 65 20 61 20 pose is to be a
40e90 70 6c 61 63 65 68 6f 6c 64 65 72 20 66 75 6e 63 placeholder func
40ea0 74 69 6f 6e 20 74 68 61 74 20 63 61 6e 20 62 65 tion that can be
40eb0 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 overloaded.** b
40ec0 79 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 y virtual tables
40ed0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 ..**.** This API
40ee0 20 73 68 6f 75 6c 64 20 62 65 20 63 6f 6e 73 69 should be consi
40ef0 64 65 72 65 64 20 70 61 72 74 20 6f 66 20 74 68 dered part of th
40f00 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 e virtual table
40f10 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 77 68 interface,.** wh
40f20 69 63 68 20 69 73 20 65 78 70 65 72 69 6d 65 6e ich is experimen
40f30 74 61 6c 20 61 6e 64 20 73 75 62 6a 65 63 74 20 tal and subject
40f40 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 to change..*/.SQ
40f50 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 LITE_EXPERIMENTA
40f60 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76 L int sqlite3_ov
40f70 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28 erload_function(
40f80 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 sqlite3*, const
40f90 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c char *zFuncName,
40fa0 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a int nArg);../*.
40fb0 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 ** The interface
40fc0 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d to the virtual-
40fd0 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 table mechanism
40fe0 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20 28 62 defined above (b
40ff0 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63 ack up.** to a c
41000 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c omment remarkabl
41010 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 69 y similar to thi
41020 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72 65 6e s one) is curren
41030 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a tly considered.*
41040 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 * to be experime
41050 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 ntal. The inter
41060 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 face might chang
41070 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c e in incompatibl
41080 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 e ways..** If th
41090 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 is is a problem
410a0 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 for you, do not
410b0 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 use the interfac
410c0 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a e at this time..
410d0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 **.** When the v
410e0 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 irtual-table mec
410f0 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 hanism stabilize
41100 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 s, we will decla
41110 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 re the.** interf
41120 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f ace fixed, suppo
41130 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 rt it indefinite
41140 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 ly, and remove t
41150 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a 0a his comment..**.
41160 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e ****** EXPERIMEN
41170 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f TAL - subject to
41180 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 change without
41190 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a notice *********
411a0 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 *****.*/../*.**
411b0 43 41 50 49 33 52 45 46 3a 20 41 20 48 61 6e 64 CAPI3REF: A Hand
411c0 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20 42 4c le To An Open BL
411d0 4f 42 20 7b 48 31 37 38 30 30 7d 20 3c 53 33 30 OB {H17800} <S30
411e0 32 33 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 230>.** KEYWORDS
411f0 3a 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 7d 20 : {BLOB handle}
41200 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 7d 0a 2a {BLOB handles}.*
41210 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 *.** An instance
41220 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 of this object
41230 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 represents an op
41240 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 68 69 63 68 en BLOB on which
41250 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f .** [sqlite3_blo
41260 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 b_open | increme
41270 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 63 ntal BLOB I/O] c
41280 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 2e an be performed.
41290 0a 2a 2a 20 4f 62 6a 65 63 74 73 20 6f 66 20 74 .** Objects of t
412a0 68 69 73 20 74 79 70 65 20 61 72 65 20 63 72 65 his type are cre
412b0 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 ated by [sqlite3
412c0 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a _blob_open()].**
412d0 20 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20 62 and destroyed b
412e0 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f y [sqlite3_blob_
412f0 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 close()]..** The
41300 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 [sqlite3_blob_r
41310 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 ead()] and [sqli
41320 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 te3_blob_write()
41330 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 ] interfaces.**
41340 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 can be used to r
41350 65 61 64 20 6f 72 20 77 72 69 74 65 20 73 6d 61 ead or write sma
41360 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 20 6f ll subsections o
41370 66 20 74 68 65 20 42 4c 4f 42 2e 0a 2a 2a 20 54 f the BLOB..** T
41380 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 he [sqlite3_blob
41390 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 _bytes()] interf
413a0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ace returns the
413b0 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 size of the BLOB
413c0 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a 74 79 in bytes..*/.ty
413d0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
413e0 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69 74 65 ite3_blob sqlite
413f0 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 3_blob;../*.** C
41400 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 20 41 20 API3REF: Open A
41410 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65 6d 65 BLOB For Increme
41420 6e 74 61 6c 20 49 2f 4f 20 7b 48 31 37 38 31 30 ntal I/O {H17810
41430 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a } <S30230>.**.**
41440 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 73 This interfaces
41450 20 6f 70 65 6e 73 20 61 20 5b 42 4c 4f 42 20 68 opens a [BLOB h
41460 61 6e 64 6c 65 20 7c 20 68 61 6e 64 6c 65 5d 20 andle | handle]
41470 74 6f 20 74 68 65 20 42 4c 4f 42 20 6c 6f 63 61 to the BLOB loca
41480 74 65 64 0a 2a 2a 20 69 6e 20 72 6f 77 20 69 52 ted.** in row iR
41490 6f 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 ow, column zColu
414a0 6d 6e 2c 20 74 61 62 6c 65 20 7a 54 61 62 6c 65 mn, table zTable
414b0 20 69 6e 20 64 61 74 61 62 61 73 65 20 7a 44 62 in database zDb
414c0 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65 72 20 77 6f ;.** in other wo
414d0 72 64 73 2c 20 74 68 65 20 73 61 6d 65 20 42 4c rds, the same BL
414e0 4f 42 20 74 68 61 74 20 77 6f 75 6c 64 20 62 65 OB that would be
414f0 20 73 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a selected by:.**
41500 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 .** <pre>.**
41510 20 53 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 SELECT zColumn
41520 46 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20 FROM zDb.zTable
41530 57 48 45 52 45 20 72 6f 77 69 64 20 3d 20 69 52 WHERE rowid = iR
41540 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 20 7b 45 ow;.** </pre> {E
41550 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 ND}.**.** If the
41560 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 flags parameter
41570 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 is non-zero, th
41580 65 20 74 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 e the BLOB is op
41590 65 6e 65 64 20 66 6f 72 20 72 65 61 64 0a 2a 2a ened for read.**
415a0 20 61 6e 64 20 77 72 69 74 65 20 61 63 63 65 73 and write acces
415b0 73 2e 20 49 66 20 69 74 20 69 73 20 7a 65 72 6f s. If it is zero
415c0 2c 20 74 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 , the BLOB is op
415d0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 20 61 63 ened for read ac
415e0 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 cess..**.** Note
415f0 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 that the databa
41600 73 65 20 6e 61 6d 65 20 69 73 20 6e 6f 74 20 74 se name is not t
41610 68 65 20 66 69 6c 65 6e 61 6d 65 20 74 68 61 74 he filename that
41620 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 contains.** the
41630 20 64 61 74 61 62 61 73 65 20 62 75 74 20 72 61 database but ra
41640 74 68 65 72 20 74 68 65 20 73 79 6d 62 6f 6c 69 ther the symboli
41650 63 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 c name of the da
41660 74 61 62 61 73 65 20 74 68 61 74 0a 2a 2a 20 69 tabase that.** i
41670 73 20 61 73 73 69 67 6e 65 64 20 77 68 65 6e 20 s assigned when
41680 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 the database is
41690 63 6f 6e 6e 65 63 74 65 64 20 75 73 69 6e 67 20 connected using
416a0 5b 41 54 54 41 43 48 5d 2e 0a 2a 2a 20 46 6f 72 [ATTACH]..** For
416b0 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 the main databa
416c0 73 65 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 se file, the dat
416d0 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22 6d abase name is "m
416e0 61 69 6e 22 2e 0a 2a 2a 20 46 6f 72 20 54 45 4d ain"..** For TEM
416f0 50 20 74 61 62 6c 65 73 2c 20 74 68 65 20 64 61 P tables, the da
41700 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22 tabase name is "
41710 74 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 temp"..**.** On
41720 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 success, [SQLITE
41730 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 _OK] is returned
41740 20 61 6e 64 20 74 68 65 20 6e 65 77 20 5b 42 4c and the new [BL
41750 4f 42 20 68 61 6e 64 6c 65 5d 20 69 73 20 77 72 OB handle] is wr
41760 69 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42 itten.** to *ppB
41770 6c 6f 62 2e 20 4f 74 68 65 72 77 69 73 65 20 61 lob. Otherwise a
41780 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 n [error code] i
41790 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61 s returned and a
417a0 6e 79 20 76 61 6c 75 65 20 77 72 69 74 74 65 6e ny value written
417b0 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c 6f 62 20 73 .** to *ppBlob s
417c0 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 hould not be use
417d0 64 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72 2e d by the caller.
417e0 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f .** This functio
417f0 6e 20 73 65 74 73 20 74 68 65 20 5b 64 61 74 61 n sets the [data
41800 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
41810 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 error code and
41820 6d 65 73 73 61 67 65 0a 2a 2a 20 61 63 63 65 73 message.** acces
41830 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 sible via [sqlit
41840 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 61 6e e3_errcode()] an
41850 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 d [sqlite3_errms
41860 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 g()]..**.** If t
41870 68 65 20 72 6f 77 20 74 68 61 74 20 61 20 42 4c he row that a BL
41880 4f 42 20 68 61 6e 64 6c 65 20 70 6f 69 6e 74 73 OB handle points
41890 20 74 6f 20 69 73 20 6d 6f 64 69 66 69 65 64 20 to is modified
418a0 62 79 20 61 6e 0a 2a 2a 20 5b 55 50 44 41 54 45 by an.** [UPDATE
418b0 5d 2c 20 5b 44 45 4c 45 54 45 5d 2c 20 6f 72 20 ], [DELETE], or
418c0 62 79 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d by [ON CONFLICT]
418d0 20 73 69 64 65 2d 65 66 66 65 63 74 73 0a 2a 2a side-effects.**
418e0 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 68 then the BLOB h
418f0 61 6e 64 6c 65 20 69 73 20 6d 61 72 6b 65 64 20 andle is marked
41900 61 73 20 22 65 78 70 69 72 65 64 22 2e 0a 2a 2a as "expired"..**
41910 20 54 68 69 73 20 69 73 20 74 72 75 65 20 69 66 This is true if
41920 20 61 6e 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 any column of t
41930 68 65 20 72 6f 77 20 69 73 20 63 68 61 6e 67 65 he row is change
41940 64 2c 20 65 76 65 6e 20 61 20 63 6f 6c 75 6d 6e d, even a column
41950 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 74 .** other than t
41960 68 65 20 6f 6e 65 20 74 68 65 20 42 4c 4f 42 20 he one the BLOB
41970 68 61 6e 64 6c 65 20 69 73 20 6f 70 65 6e 20 6f handle is open o
41980 6e 2e 0a 2a 2a 20 43 61 6c 6c 73 20 74 6f 20 5b n..** Calls to [
41990 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 sqlite3_blob_rea
419a0 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 d()] and [sqlite
419b0 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 3_blob_write()]
419c0 66 6f 72 0a 2a 2a 20 61 20 65 78 70 69 72 65 64 for.** a expired
419d0 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 66 61 69 BLOB handle fai
419e0 6c 20 77 69 74 68 20 61 6e 20 72 65 74 75 72 6e l with an return
419f0 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 code of [SQLITE
41a00 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20 43 68 61 6e _ABORT]..** Chan
41a10 67 65 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f ges written into
41a20 20 61 20 42 4c 4f 42 20 70 72 69 6f 72 20 74 6f a BLOB prior to
41a30 20 74 68 65 20 42 4c 4f 42 20 65 78 70 69 72 69 the BLOB expiri
41a40 6e 67 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f ng are not.** ro
41a50 6c 6c 62 61 63 6b 20 62 79 20 74 68 65 20 65 78 llback by the ex
41a60 70 69 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 piration of the
41a70 42 4c 4f 42 2e 20 20 53 75 63 68 20 63 68 61 6e BLOB. Such chan
41a80 67 65 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 ges will eventua
41a90 6c 6c 79 0a 2a 2a 20 63 6f 6d 6d 69 74 20 69 66 lly.** commit if
41aa0 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e the transaction
41ab0 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f continues to co
41ac0 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 mpletion..**.**
41ad0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
41ae0 2a 20 7b 48 31 37 38 31 33 7d 20 41 20 73 75 63 * {H17813} A suc
41af0 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 cessful invocati
41b00 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 on of the [sqlit
41b10 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 44 2c 42 e3_blob_open(D,B
41b20 2c 54 2c 43 2c 52 2c 46 2c 50 29 5d 0a 2a 2a 20 ,T,C,R,F,P)].**
41b30 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 interfa
41b40 63 65 20 73 68 61 6c 6c 20 6f 70 65 6e 20 61 6e ce shall open an
41b50 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 [sqlite3_blob]
41b60 6f 62 6a 65 63 74 20 50 20 6f 6e 20 74 68 65 20 object P on the
41b70 42 4c 4f 42 0a 2a 2a 20 20 20 20 20 20 20 20 20 BLOB.**
41b80 20 69 6e 20 63 6f 6c 75 6d 6e 20 43 20 6f 66 20 in column C of
41b90 74 68 65 20 74 61 62 6c 65 20 54 20 69 6e 20 74 the table T in t
41ba0 68 65 20 64 61 74 61 62 61 73 65 20 42 20 6f 6e he database B on
41bb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
41bc0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
41bd0 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 ction] D..**.**
41be0 7b 48 31 37 38 31 34 7d 20 41 20 73 75 63 63 65 {H17814} A succe
41bf0 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e ssful invocation
41c00 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f of [sqlite3_blo
41c10 62 5f 6f 70 65 6e 28 44 2c 2e 2e 2e 29 5d 20 73 b_open(D,...)] s
41c20 68 61 6c 6c 20 73 74 61 72 74 0a 2a 2a 20 20 20 hall start.**
41c30 20 20 20 20 20 20 20 61 20 6e 65 77 20 74 72 61 a new tra
41c40 6e 73 61 63 74 69 6f 6e 20 6f 6e 20 74 68 65 20 nsaction on the
41c50 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
41c60 74 69 6f 6e 5d 20 44 20 69 66 20 74 68 61 74 0a tion] D if that.
41c70 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 6e ** conn
41c80 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 6c ection is not al
41c90 72 65 61 64 79 20 69 6e 20 61 20 74 72 61 6e 73 ready in a trans
41ca0 61 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 action..**.** {H
41cb0 31 37 38 31 36 7d 20 54 68 65 20 5b 73 71 6c 69 17816} The [sqli
41cc0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 44 2c te3_blob_open(D,
41cd0 42 2c 54 2c 43 2c 52 2c 46 2c 50 29 5d 20 69 6e B,T,C,R,F,P)] in
41ce0 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 6f 70 terface shall op
41cf0 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 en.** t
41d00 68 65 20 42 4c 4f 42 20 66 6f 72 20 72 65 61 64 he BLOB for read
41d10 20 61 6e 64 20 77 72 69 74 65 20 61 63 63 65 73 and write acces
41d20 73 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 s if and only if
41d30 20 74 68 65 20 46 0a 2a 2a 20 20 20 20 20 20 20 the F.**
41d40 20 20 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 parameter is
41d50 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 non-zero..**.**
41d60 7b 48 31 37 38 31 39 7d 20 54 68 65 20 5b 73 71 {H17819} The [sq
41d70 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 lite3_blob_open(
41d80 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 )] interface sha
41d90 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 ll return [SQLIT
41da0 45 5f 4f 4b 5d 20 6f 6e 0a 2a 2a 20 20 20 20 20 E_OK] on.**
41db0 20 20 20 20 20 73 75 63 63 65 73 73 20 61 6e 64 success and
41dc0 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 an appropriate
41dd0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e 20 [error code] on
41de0 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b failure..**.** {
41df0 48 31 37 38 32 31 7d 20 49 66 20 61 6e 20 65 72 H17821} If an er
41e00 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e ror occurs durin
41e10 67 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 g evaluation of
41e20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 [sqlite3_blob_op
41e30 65 6e 28 44 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 en(D,...)].**
41e40 20 20 20 20 20 20 20 74 68 65 6e 20 73 75 62 73 then subs
41e50 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 equent calls to
41e60 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 [sqlite3_errcode
41e70 28 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 (D)],.**
41e80 20 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e [sqlite3_exten
41e90 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 ded_errcode()],
41ea0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
41eb0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 44 29 5d lite3_errmsg(D)]
41ec0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 , and [sqlite3_e
41ed0 72 72 6d 73 67 31 36 28 44 29 5d 20 73 68 61 6c rrmsg16(D)] shal
41ee0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 l return.**
41ef0 20 20 20 20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e information
41f00 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 appropriate for
41f10 20 74 68 61 74 20 65 72 72 6f 72 2e 0a 2a 2a 0a that error..**.
41f20 2a 2a 20 7b 48 31 37 38 32 34 7d 20 49 66 20 61 ** {H17824} If a
41f30 6e 79 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 ny column in the
41f40 20 72 6f 77 20 74 68 61 74 20 61 20 5b 73 71 6c row that a [sql
41f50 69 74 65 33 5f 62 6c 6f 62 5d 20 68 61 73 20 6f ite3_blob] has o
41f60 70 65 6e 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 pen is.**
41f70 20 20 20 63 68 61 6e 67 65 64 20 62 79 20 61 20 changed by a
41f80 73 65 70 61 72 61 74 65 20 5b 55 50 44 41 54 45 separate [UPDATE
41f90 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 ] or [DELETE] st
41fa0 61 74 65 6d 65 6e 74 20 6f 72 20 62 79 0a 2a 2a atement or by.**
41fb0 20 20 20 20 20 20 20 20 20 20 61 6e 20 5b 4f 4e an [ON
41fc0 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69 64 65 20 CONFLICT] side
41fd0 65 66 66 65 63 74 2c 20 74 68 65 6e 20 74 68 65 effect, then the
41fe0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 [sqlite3_blob]
41ff0 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 shall.**
42000 20 20 62 65 20 6d 61 72 6b 65 64 20 61 73 20 69 be marked as i
42010 6e 76 61 6c 69 64 2e 0a 2a 2f 0a 69 6e 74 20 73 nvalid..*/.int s
42020 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e qlite3_blob_open
42030 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 (. sqlite3*,.
42040 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 2c const char *zDb,
42050 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
42060 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 63 Table,. const c
42070 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 har *zColumn,.
42080 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 52 sqlite3_int64 iR
42090 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c ow,. int flags,
420a0 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 . sqlite3_blob
420b0 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a **ppBlob.);../*.
420c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f ** CAPI3REF: Clo
420d0 73 65 20 41 20 42 4c 4f 42 20 48 61 6e 64 6c 65 se A BLOB Handle
420e0 20 7b 48 31 37 38 33 30 7d 20 3c 53 33 30 32 33 {H17830} <S3023
420f0 30 3e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 65 73 20 0>.**.** Closes
42100 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 an open [BLOB ha
42110 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f ndle]..**.** Clo
42120 73 69 6e 67 20 61 20 42 4c 4f 42 20 73 68 61 6c sing a BLOB shal
42130 6c 20 63 61 75 73 65 20 74 68 65 20 63 75 72 72 l cause the curr
42140 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 ent transaction
42150 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66 20 to commit.** if
42160 74 68 65 72 65 20 61 72 65 20 6e 6f 20 6f 74 68 there are no oth
42170 65 72 20 42 4c 4f 42 73 2c 20 6e 6f 20 70 65 6e er BLOBs, no pen
42180 64 69 6e 67 20 70 72 65 70 61 72 65 64 20 73 74 ding prepared st
42190 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 74 68 atements, and th
421a0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f e.** database co
421b0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e 20 5b nnection is in [
421c0 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 5d autocommit mode]
421d0 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 77 72 69 74 ..** If any writ
421e0 65 73 20 77 65 72 65 20 6d 61 64 65 20 74 6f 20 es were made to
421f0 74 68 65 20 42 4c 4f 42 2c 20 74 68 65 79 20 6d the BLOB, they m
42200 69 67 68 74 20 62 65 20 68 65 6c 64 20 69 6e 20 ight be held in
42210 63 61 63 68 65 0a 2a 2a 20 75 6e 74 69 6c 20 74 cache.** until t
42220 68 65 20 63 6c 6f 73 65 20 6f 70 65 72 61 74 69 he close operati
42230 6f 6e 20 69 66 20 74 68 65 79 20 77 69 6c 6c 20 on if they will
42240 66 69 74 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a fit. {END}.**.**
42250 20 43 6c 6f 73 69 6e 67 20 74 68 65 20 42 4c 4f Closing the BLO
42260 42 20 6f 66 74 65 6e 20 66 6f 72 63 65 73 20 74 B often forces t
42270 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 75 he changes.** ou
42280 74 20 74 6f 20 64 69 73 6b 20 61 6e 64 20 73 6f t to disk and so
42290 20 69 66 20 61 6e 79 20 49 2f 4f 20 65 72 72 6f if any I/O erro
422a0 72 73 20 6f 63 63 75 72 2c 20 74 68 65 79 20 77 rs occur, they w
422b0 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63 75 72 ill likely occur
422c0 0a 2a 2a 20 61 74 20 74 68 65 20 74 69 6d 65 20 .** at the time
422d0 77 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 73 when the BLOB is
422e0 20 63 6c 6f 73 65 64 2e 20 20 7b 48 31 37 38 33 closed. {H1783
422f0 33 7d 20 41 6e 79 20 65 72 72 6f 72 73 20 74 68 3} Any errors th
42300 61 74 20 6f 63 63 75 72 20 64 75 72 69 6e 67 0a at occur during.
42310 2a 2a 20 63 6c 6f 73 69 6e 67 20 61 72 65 20 72 ** closing are r
42320 65 70 6f 72 74 65 64 20 61 73 20 61 20 6e 6f 6e eported as a non
42330 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20 76 61 6c -zero return val
42340 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 42 4c ue..**.** The BL
42350 4f 42 20 69 73 20 63 6c 6f 73 65 64 20 75 6e 63 OB is closed unc
42360 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79 2e 20 20 45 onditionally. E
42370 76 65 6e 20 69 66 20 74 68 69 73 20 72 6f 75 74 ven if this rout
42380 69 6e 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 ine returns.** a
42390 6e 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 74 68 n error code, th
423a0 65 20 42 4c 4f 42 20 69 73 20 73 74 69 6c 6c 20 e BLOB is still
423b0 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e closed..**.** IN
423c0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
423d0 7b 48 31 37 38 33 33 7d 20 54 68 65 20 5b 73 71 {H17833} The [sq
423e0 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 lite3_blob_close
423f0 28 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 (P)] interface c
42400 6c 6f 73 65 73 20 61 6e 20 5b 73 71 6c 69 74 65 loses an [sqlite
42410 33 5f 62 6c 6f 62 5d 0a 2a 2a 20 20 20 20 20 20 3_blob].**
42420 20 20 20 20 6f 62 6a 65 63 74 20 50 20 70 72 65 object P pre
42430 76 69 6f 75 73 6c 79 20 6f 70 65 6e 65 64 20 75 viously opened u
42440 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 6c sing [sqlite3_bl
42450 6f 62 5f 6f 70 65 6e 28 29 5d 2e 0a 2a 2a 0a 2a ob_open()]..**.*
42460 2a 20 7b 48 31 37 38 33 36 7d 20 43 6c 6f 73 69 * {H17836} Closi
42470 6e 67 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 62 ng an [sqlite3_b
42480 6c 6f 62 5d 20 6f 62 6a 65 63 74 20 75 73 69 6e lob] object usin
42490 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 g.** [s
424a0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 qlite3_blob_clos
424b0 65 28 29 5d 20 73 68 61 6c 6c 20 63 61 75 73 65 e()] shall cause
424c0 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 72 61 the current tra
424d0 6e 73 61 63 74 69 6f 6e 20 74 6f 0a 2a 2a 20 20 nsaction to.**
424e0 20 20 20 20 20 20 20 20 63 6f 6d 6d 69 74 20 69 commit i
424f0 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 6f f there are no o
42500 74 68 65 72 20 6f 70 65 6e 20 5b 73 71 6c 69 74 ther open [sqlit
42510 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63 74 73 e3_blob] objects
42520 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 .** or
42530 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
42540 65 6e 74 73 5d 20 6f 6e 20 74 68 65 20 73 61 6d ents] on the sam
42550 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
42560 65 63 74 69 6f 6e 5d 20 61 6e 64 0a 2a 2a 20 20 ection] and.**
42570 20 20 20 20 20 20 20 20 74 68 65 20 64 61 74 61 the data
42580 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
42590 69 73 20 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69 is in [autocommi
425a0 74 20 6d 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b t mode]..**.** {
425b0 48 31 37 38 33 39 7d 20 54 68 65 20 5b 73 71 6c H17839} The [sql
425c0 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 ite3_blob_close(
425d0 50 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 73 P)] interfaces s
425e0 68 61 6c 6c 20 63 6c 6f 73 65 20 74 68 65 0a 2a hall close the.*
425f0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
42600 74 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63 74 te3_blob] object
42610 20 50 20 75 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c P unconditional
42620 6c 79 2c 20 65 76 65 6e 20 69 66 0a 2a 2a 20 20 ly, even if.**
42630 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
42640 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 50 29 5d 20 _blob_close(P)]
42650 72 65 74 75 72 6e 73 20 73 6f 6d 65 74 68 69 6e returns somethin
42660 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 g other than [SQ
42670 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2f 0a 69 6e 74 LITE_OK]..*/.int
42680 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c sqlite3_blob_cl
42690 6f 73 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 ose(sqlite3_blob
426a0 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 *);../*.** CAPI
426b0 33 52 45 46 3a 20 52 65 74 75 72 6e 20 54 68 65 3REF: Return The
426c0 20 53 69 7a 65 20 4f 66 20 41 6e 20 4f 70 65 6e Size Of An Open
426d0 20 42 4c 4f 42 20 7b 48 31 37 38 34 30 7d 20 3c BLOB {H17840} <
426e0 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 S30230>.**.** Re
426f0 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 69 turns the size i
42700 6e 20 62 79 74 65 73 20 6f 66 20 74 68 65 20 42 n bytes of the B
42710 4c 4f 42 20 61 63 63 65 73 73 69 62 6c 65 20 76 LOB accessible v
42720 69 61 20 74 68 65 20 6f 70 65 6e 0a 2a 2a 20 5b ia the open.** [
42730 5d 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e ]BLOB handle] in
42740 20 69 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 its only argume
42750 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 nt..**.** INVARI
42760 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 ANTS:.**.** {H17
42770 38 34 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 843} The [sqlite
42780 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 50 29 5d 3_blob_bytes(P)]
42790 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
427a0 6e 73 20 74 68 65 20 73 69 7a 65 0a 2a 2a 20 20 ns the size.**
427b0 20 20 20 20 20 20 20 20 69 6e 20 62 79 74 65 73 in bytes
427c0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 74 68 61 of the BLOB tha
427d0 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 t the [sqlite3_b
427e0 6c 6f 62 5d 20 6f 62 6a 65 63 74 20 50 0a 2a 2a lob] object P.**
427f0 20 20 20 20 20 20 20 20 20 20 72 65 66 65 72 73 refers
42800 20 74 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 to..*/.int sqli
42810 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 73 te3_blob_bytes(s
42820 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a qlite3_blob *);.
42830 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
42840 20 52 65 61 64 20 44 61 74 61 20 46 72 6f 6d 20 Read Data From
42850 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 A BLOB Increment
42860 61 6c 6c 79 20 7b 48 31 37 38 35 30 7d 20 3c 53 ally {H17850} <S
42870 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 30230>.**.** Thi
42880 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 s function is us
42890 65 64 20 74 6f 20 72 65 61 64 20 64 61 74 61 20 ed to read data
428a0 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 5b 42 4c from an open [BL
428b0 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 74 6f 20 OB handle] into
428c0 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70 a.** caller-supp
428d0 6c 69 65 64 20 62 75 66 66 65 72 2e 20 4e 20 62 lied buffer. N b
428e0 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72 65 ytes of data are
428f0 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 62 75 66 copied into buf
42900 66 65 72 20 5a 0a 2a 2a 20 66 72 6f 6d 20 74 68 fer Z.** from th
42910 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61 e open BLOB, sta
42920 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20 rting at offset
42930 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 iOffset..**.** I
42940 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 f offset iOffset
42950 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 4e 20 is less than N
42960 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20 65 bytes from the e
42970 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f 42 2c 0a nd of the BLOB,.
42980 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 ** [SQLITE_ERROR
42990 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e ] is returned an
429a0 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61 d no data is rea
429b0 64 2e 20 20 49 66 20 4e 20 6f 72 20 69 4f 66 66 d. If N or iOff
429c0 73 65 74 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 set is.** less t
429d0 68 61 6e 20 7a 65 72 6f 2c 20 5b 53 51 4c 49 54 han zero, [SQLIT
429e0 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 E_ERROR] is retu
429f0 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 rned and no data
42a00 20 69 73 20 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 is read..**.**
42a10 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 An attempt to re
42a20 61 64 20 66 72 6f 6d 20 61 6e 20 65 78 70 69 72 ad from an expir
42a30 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d ed [BLOB handle]
42a40 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a fails with an.*
42a50 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 * error code of
42a60 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a [SQLITE_ABORT]..
42a70 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 **.** On success
42a80 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 , SQLITE_OK is r
42a90 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 eturned..** Othe
42aa0 72 77 69 73 65 2c 20 61 6e 20 5b 65 72 72 6f 72 rwise, an [error
42ab0 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78 code] or an [ex
42ac0 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 tended error cod
42ad0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a e] is returned..
42ae0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
42af0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 35 33 7d :.**.** {H17853}
42b00 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e A successful in
42b10 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c vocation of [sql
42b20 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 50 ite3_blob_read(P
42b30 2c 5a 2c 4e 2c 58 29 5d 20 0a 2a 2a 20 20 20 20 ,Z,N,X)] .**
42b40 20 20 20 20 20 20 73 68 61 6c 6c 20 72 65 61 64 shall read
42b50 73 20 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 s N bytes of dat
42b60 61 20 6f 75 74 20 6f 66 20 74 68 65 20 42 4c 4f a out of the BLO
42b70 42 20 72 65 66 65 72 65 6e 63 65 64 20 62 79 0a B referenced by.
42b80 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 42 4c 4f ** [BLO
42b90 42 20 68 61 6e 64 6c 65 5d 20 50 20 62 65 67 69 B handle] P begi
42ba0 6e 6e 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20 nning at offset
42bb0 58 20 61 6e 64 20 73 74 6f 72 65 20 74 68 6f 73 X and store thos
42bc0 65 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 e bytes.**
42bd0 20 20 20 20 69 6e 74 6f 20 62 75 66 66 65 72 20 into buffer
42be0 5a 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 35 36 Z..**.** {H17856
42bf0 7d 20 49 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c } In [sqlite3_bl
42c00 6f 62 5f 72 65 61 64 28 50 2c 5a 2c 4e 2c 58 29 ob_read(P,Z,N,X)
42c10 5d 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66 ] if the size of
42c20 20 74 68 65 20 42 4c 4f 42 0a 2a 2a 20 20 20 20 the BLOB.**
42c30 20 20 20 20 20 20 69 73 20 6c 65 73 73 20 74 68 is less th
42c40 61 6e 20 4e 2b 58 20 62 79 74 65 73 2c 20 74 68 an N+X bytes, th
42c50 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 en the function
42c60 73 68 61 6c 6c 20 6c 65 61 76 65 20 74 68 65 0a shall leave the.
42c70 2a 2a 20 20 20 20 20 20 20 20 20 20 5a 20 62 75 ** Z bu
42c80 66 66 65 72 20 75 6e 63 68 61 6e 67 65 64 20 61 ffer unchanged a
42c90 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 nd return [SQLIT
42ca0 45 5f 45 52 52 4f 52 5d 2e 0a 2a 2a 0a 2a 2a 20 E_ERROR]..**.**
42cb0 7b 48 31 37 38 35 39 7d 20 49 6e 20 5b 73 71 6c {H17859} In [sql
42cc0 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 50 ite3_blob_read(P
42cd0 2c 5a 2c 4e 2c 58 29 5d 20 69 66 20 58 20 6f 72 ,Z,N,X)] if X or
42ce0 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 N is less than
42cf0 7a 65 72 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 zero.**
42d00 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 then the functi
42d10 6f 6e 20 73 68 61 6c 6c 20 6c 65 61 76 65 20 74 on shall leave t
42d20 68 65 20 5a 20 62 75 66 66 65 72 20 75 6e 63 68 he Z buffer unch
42d30 61 6e 67 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 anged.**
42d40 20 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 and return [SQ
42d50 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 0a 2a 2a 0a LITE_ERROR]..**.
42d60 2a 2a 20 7b 48 31 37 38 36 32 7d 20 54 68 65 20 ** {H17862} The
42d70 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 [sqlite3_blob_re
42d80 61 64 28 50 2c 5a 2c 4e 2c 58 29 5d 20 69 6e 74 ad(P,Z,N,X)] int
42d90 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 74 erface shall ret
42da0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 0a urn [SQLITE_OK].
42db0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 4e ** if N
42dc0 20 62 79 74 65 73 20 61 72 65 20 73 75 63 63 65 bytes are succe
42dd0 73 73 66 75 6c 6c 79 20 72 65 61 64 20 69 6e 74 ssfully read int
42de0 6f 20 62 75 66 66 65 72 20 5a 2e 0a 2a 2a 0a 2a o buffer Z..**.*
42df0 2a 20 7b 48 31 37 38 36 33 7d 20 49 66 20 74 68 * {H17863} If th
42e00 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 e [BLOB handle]
42e10 50 20 69 73 20 65 78 70 69 72 65 64 20 61 6e 64 P is expired and
42e20 20 58 20 61 6e 64 20 4e 20 61 72 65 20 77 69 74 X and N are wit
42e30 68 69 6e 20 62 6f 75 6e 64 73 0a 2a 2a 20 20 20 hin bounds.**
42e40 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c then [sql
42e50 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 50 ite3_blob_read(P
42e60 2c 5a 2c 4e 2c 58 29 5d 20 73 68 61 6c 6c 20 6c ,Z,N,X)] shall l
42e70 65 61 76 65 20 74 68 65 20 5a 20 62 75 66 66 65 eave the Z buffe
42e80 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 6e r.** un
42e90 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 changed and retu
42ea0 72 6e 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 rn [SQLITE_ABORT
42eb0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 36 35 ]..**.** {H17865
42ec0 7d 20 49 66 20 74 68 65 20 72 65 71 75 65 73 74 } If the request
42ed0 65 64 20 72 65 61 64 20 63 6f 75 6c 64 20 6e 6f ed read could no
42ee0 74 20 62 65 20 63 6f 6d 70 6c 65 74 65 64 2c 0a t be completed,.
42ef0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
42f00 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 [sqlite3_blob_re
42f10 61 64 28 50 2c 5a 2c 4e 2c 58 29 5d 20 69 6e 74 ad(P,Z,N,X)] int
42f20 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 74 erface shall ret
42f30 75 72 6e 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 urn an.**
42f40 20 20 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b appropriate [
42f50 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b error code] or [
42f60 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 extended error c
42f70 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 ode]..**.** {H17
42f80 38 36 38 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 868} If an error
42f90 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 65 occurs during e
42fa0 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 valuation of [sq
42fb0 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 lite3_blob_read(
42fc0 50 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 P,...)].**
42fd0 20 20 20 20 74 68 65 6e 20 73 75 62 73 65 71 75 then subsequ
42fe0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 ent calls to [sq
42ff0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 lite3_errcode(D)
43000 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b ],.** [
43010 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
43020 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 _errcode()],.**
43030 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
43040 33 5f 65 72 72 6d 73 67 28 44 29 5d 2c 20 61 6e 3_errmsg(D)], an
43050 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 d [sqlite3_errms
43060 67 31 36 28 44 29 5d 20 73 68 61 6c 6c 20 72 65 g16(D)] shall re
43070 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 turn.**
43080 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 70 70 information app
43090 72 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68 61 ropriate for tha
430a0 74 20 65 72 72 6f 72 2c 20 77 68 65 72 65 20 44 t error, where D
430b0 20 69 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 is the.**
430c0 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f [database co
430d0 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 77 nnection] that w
430e0 61 73 20 75 73 65 64 20 74 6f 20 6f 70 65 6e 20 as used to open
430f0 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 the [BLOB handle
43100 5d 20 50 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ] P..*/.int sqli
43110 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 73 71 te3_blob_read(sq
43120 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 76 6f lite3_blob *, vo
43130 69 64 20 2a 5a 2c 20 69 6e 74 20 4e 2c 20 69 6e id *Z, int N, in
43140 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a t iOffset);../*.
43150 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 57 72 69 ** CAPI3REF: Wri
43160 74 65 20 44 61 74 61 20 49 6e 74 6f 20 41 20 42 te Data Into A B
43170 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c LOB Incrementall
43180 79 20 7b 48 31 37 38 37 30 7d 20 3c 53 33 30 32 y {H17870} <S302
43190 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 30>.**.** This f
431a0 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20 unction is used
431b0 74 6f 20 77 72 69 74 65 20 64 61 74 61 20 69 6e to write data in
431c0 74 6f 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 to an open [BLOB
431d0 20 68 61 6e 64 6c 65 5d 20 66 72 6f 6d 20 61 0a handle] from a.
431e0 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70 6c 69 ** caller-suppli
431f0 65 64 20 62 75 66 66 65 72 2e 20 4e 20 62 79 74 ed buffer. N byt
43200 65 73 20 6f 66 20 64 61 74 61 20 61 72 65 20 63 es of data are c
43210 6f 70 69 65 64 20 66 72 6f 6d 20 74 68 65 20 62 opied from the b
43220 75 66 66 65 72 20 5a 0a 2a 2a 20 69 6e 74 6f 20 uffer Z.** into
43230 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 the open BLOB, s
43240 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65 tarting at offse
43250 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a t iOffset..**.**
43260 20 49 66 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 If the [BLOB ha
43270 6e 64 6c 65 5d 20 70 61 73 73 65 64 20 61 73 20 ndle] passed as
43280 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
43290 6e 74 20 77 61 73 20 6e 6f 74 20 6f 70 65 6e 65 nt was not opene
432a0 64 20 66 6f 72 0a 2a 2a 20 77 72 69 74 69 6e 67 d for.** writing
432b0 20 28 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 (the flags para
432c0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 meter to [sqlite
432d0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 77 3_blob_open()] w
432e0 61 73 20 7a 65 72 6f 29 2c 0a 2a 2a 20 74 68 69 as zero),.** thi
432f0 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 s function retur
43300 6e 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 4f ns [SQLITE_READO
43310 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 NLY]..**.** This
43320 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6f 6e function may on
43330 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 63 6f ly modify the co
43340 6e 74 65 6e 74 73 20 6f 66 20 74 68 65 20 42 4c ntents of the BL
43350 4f 42 3b 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 OB; it is.** not
43360 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 63 possible to inc
43370 72 65 61 73 65 20 74 68 65 20 73 69 7a 65 20 6f rease the size o
43380 66 20 61 20 42 4c 4f 42 20 75 73 69 6e 67 20 74 f a BLOB using t
43390 68 69 73 20 41 50 49 2e 0a 2a 2a 20 49 66 20 6f his API..** If o
433a0 66 66 73 65 74 20 69 4f 66 66 73 65 74 20 69 73 ffset iOffset is
433b0 20 6c 65 73 73 20 74 68 61 6e 20 4e 20 62 79 74 less than N byt
433c0 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e 64 20 es from the end
433d0 6f 66 20 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 of the BLOB,.**
433e0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 [SQLITE_ERROR] i
433f0 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e s returned and n
43400 6f 20 64 61 74 61 20 69 73 20 77 72 69 74 74 65 o data is writte
43410 6e 2e 20 20 49 66 20 4e 20 69 73 0a 2a 2a 20 6c n. If N is.** l
43420 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 20 5b 53 ess than zero [S
43430 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 QLITE_ERROR] is
43440 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 returned and no
43450 64 61 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e data is written.
43460 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 74 74 65 6d 70 .**.** An attemp
43470 74 20 74 6f 20 77 72 69 74 65 20 74 6f 20 61 6e t to write to an
43480 20 65 78 70 69 72 65 64 20 5b 42 4c 4f 42 20 68 expired [BLOB h
43490 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77 69 74 andle] fails wit
434a0 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f h an.** error co
434b0 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 de of [SQLITE_AB
434c0 4f 52 54 5d 2e 20 20 57 72 69 74 65 73 20 74 6f ORT]. Writes to
434d0 20 74 68 65 20 42 4c 4f 42 20 74 68 61 74 20 6f the BLOB that o
434e0 63 63 75 72 72 65 64 0a 2a 2a 20 62 65 66 6f 72 ccurred.** befor
434f0 65 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 e the [BLOB hand
43500 6c 65 5d 20 65 78 70 69 72 65 64 20 61 72 65 20 le] expired are
43510 6e 6f 74 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 not rolled back
43520 62 79 20 74 68 65 0a 2a 2a 20 65 78 70 69 72 61 by the.** expira
43530 74 69 6f 6e 20 6f 66 20 74 68 65 20 68 61 6e 64 tion of the hand
43540 6c 65 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f le, though of co
43550 75 72 73 65 20 74 68 6f 73 65 20 63 68 61 6e 67 urse those chang
43560 65 73 20 6d 69 67 68 74 0a 2a 2a 20 68 61 76 65 es might.** have
43570 20 62 65 65 6e 20 6f 76 65 72 77 72 69 74 74 65 been overwritte
43580 6e 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 n by the stateme
43590 6e 74 20 74 68 61 74 20 65 78 70 69 72 65 64 20 nt that expired
435a0 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 0a the BLOB handle.
435b0 2a 2a 20 6f 72 20 62 79 20 6f 74 68 65 72 20 69 ** or by other i
435c0 6e 64 65 70 65 6e 64 65 6e 74 20 73 74 61 74 65 ndependent state
435d0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 ments..**.** On
435e0 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54 45 5f success, SQLITE_
435f0 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a OK is returned..
43600 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e ** Otherwise, an
43610 20 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f [error code] o
43620 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65 r an [extended e
43630 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 rror code] is re
43640 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e turned..**.** IN
43650 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
43660 7b 48 31 37 38 37 33 7d 20 41 20 73 75 63 63 65 {H17873} A succe
43670 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e ssful invocation
43680 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f of [sqlite3_blo
43690 62 5f 77 72 69 74 65 28 50 2c 5a 2c 4e 2c 58 29 b_write(P,Z,N,X)
436a0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 ].** sh
436b0 61 6c 6c 20 77 72 69 74 65 20 4e 20 62 79 74 65 all write N byte
436c0 73 20 6f 66 20 64 61 74 61 20 66 72 6f 6d 20 62 s of data from b
436d0 75 66 66 65 72 20 5a 20 69 6e 74 6f 20 74 68 65 uffer Z into the
436e0 20 42 4c 4f 42 20 0a 2a 2a 20 20 20 20 20 20 20 BLOB .**
436f0 20 20 20 72 65 66 65 72 65 6e 63 65 64 20 62 79 referenced by
43700 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 50 [BLOB handle] P
43710 20 62 65 67 69 6e 6e 69 6e 67 20 61 74 20 6f 66 beginning at of
43720 66 73 65 74 20 58 20 69 6e 74 6f 0a 2a 2a 20 20 fset X into.**
43730 20 20 20 20 20 20 20 20 74 68 65 20 42 4c 4f 42 the BLOB
43740 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 37 34 7d ..**.** {H17874}
43750 20 49 6e 20 74 68 65 20 61 62 73 65 6e 63 65 20 In the absence
43760 6f 66 20 6f 74 68 65 72 20 6f 76 65 72 72 69 64 of other overrid
43770 64 69 6e 67 20 63 68 61 6e 67 65 73 2c 20 74 68 ding changes, th
43780 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 20 20 20 e changes.**
43790 20 20 20 20 20 20 77 72 69 74 74 65 6e 20 74 6f written to
437a0 20 61 20 42 4c 4f 42 20 62 79 20 5b 73 71 6c 69 a BLOB by [sqli
437b0 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 te3_blob_write()
437c0 5d 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 ] shall.**
437d0 20 20 20 20 72 65 6d 61 69 6e 20 69 6e 20 65 66 remain in ef
437e0 66 65 63 74 20 61 66 74 65 72 20 74 68 65 20 61 fect after the a
437f0 73 73 6f 63 69 61 74 65 64 20 5b 42 4c 4f 42 20 ssociated [BLOB
43800 68 61 6e 64 6c 65 5d 20 65 78 70 69 72 65 73 2e handle] expires.
43810 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 37 35 7d 20 .**.** {H17875}
43820 49 66 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e If the [BLOB han
43830 64 6c 65 5d 20 50 20 77 61 73 20 6f 70 65 6e 65 dle] P was opene
43840 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e d for reading on
43850 6c 79 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 ly then.**
43860 20 20 20 20 61 6e 20 69 6e 76 6f 63 61 74 69 6f an invocatio
43870 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 62 6c n of [sqlite3_bl
43880 6f 62 5f 77 72 69 74 65 28 50 2c 5a 2c 4e 2c 58 ob_write(P,Z,N,X
43890 29 5d 20 73 68 61 6c 6c 20 6c 65 61 76 65 0a 2a )] shall leave.*
438a0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 72 * the r
438b0 65 66 65 72 65 6e 63 65 64 20 42 4c 4f 42 20 75 eferenced BLOB u
438c0 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 nchanged and ret
438d0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 urn [SQLITE_READ
438e0 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ONLY]..**.** {H1
438f0 37 38 37 36 7d 20 49 66 20 74 68 65 20 73 69 7a 7876} If the siz
43900 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 72 65 e of the BLOB re
43910 66 65 72 65 6e 63 65 64 20 62 79 20 5b 42 4c 4f ferenced by [BLO
43920 42 20 68 61 6e 64 6c 65 5d 20 50 20 69 73 0a 2a B handle] P is.*
43930 2a 20 20 20 20 20 20 20 20 20 20 6c 65 73 73 20 * less
43940 74 68 61 6e 20 4e 2b 58 20 62 79 74 65 73 20 74 than N+X bytes t
43950 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f hen [sqlite3_blo
43960 62 5f 77 72 69 74 65 28 50 2c 5a 2c 4e 2c 58 29 b_write(P,Z,N,X)
43970 5d 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 ] shall.**
43980 20 20 20 20 6c 65 61 76 65 20 74 68 65 20 42 4c leave the BL
43990 4f 42 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 OB unchanged and
439a0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
439b0 45 52 52 4f 52 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ERROR]..**.** {H
439c0 31 37 38 37 37 7d 20 49 66 20 74 68 65 20 5b 42 17877} If the [B
439d0 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 50 20 69 73 LOB handle] P is
439e0 20 65 78 70 69 72 65 64 20 61 6e 64 20 58 20 61 expired and X a
439f0 6e 64 20 4e 20 61 72 65 20 77 69 74 68 69 6e 20 nd N are within
43a00 62 6f 75 6e 64 73 0a 2a 2a 20 20 20 20 20 20 20 bounds.**
43a10 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 then [sqlite3
43a20 5f 62 6c 6f 62 5f 72 65 61 64 28 50 2c 5a 2c 4e _blob_read(P,Z,N
43a30 2c 58 29 5d 20 73 68 61 6c 6c 20 6c 65 61 76 65 ,X)] shall leave
43a40 20 74 68 65 20 42 4c 4f 42 0a 2a 2a 20 20 20 20 the BLOB.**
43a50 20 20 20 20 20 20 75 6e 63 68 61 6e 67 65 64 20 unchanged
43a60 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 and return [SQLI
43a70 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a TE_ABORT]..**.**
43a80 20 7b 48 31 37 38 37 39 7d 20 49 66 20 58 20 6f {H17879} If X o
43a90 72 20 4e 20 61 72 65 20 6c 65 73 73 20 74 68 61 r N are less tha
43aa0 6e 20 7a 65 72 6f 20 74 68 65 6e 20 5b 73 71 6c n zero then [sql
43ab0 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 ite3_blob_write(
43ac0 50 2c 5a 2c 4e 2c 58 29 5d 0a 2a 2a 20 20 20 20 P,Z,N,X)].**
43ad0 20 20 20 20 20 20 73 68 61 6c 6c 20 6c 65 61 76 shall leav
43ae0 65 20 74 68 65 20 42 4c 4f 42 20 72 65 66 65 72 e the BLOB refer
43af0 65 6e 63 65 64 20 62 79 20 5b 42 4c 4f 42 20 68 enced by [BLOB h
43b00 61 6e 64 6c 65 5d 20 50 20 75 6e 63 68 61 6e 67 andle] P unchang
43b10 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 ed.** a
43b20 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 nd return [SQLIT
43b30 45 5f 45 52 52 4f 52 5d 2e 0a 2a 2a 0a 2a 2a 20 E_ERROR]..**.**
43b40 7b 48 31 37 38 38 32 7d 20 54 68 65 20 5b 73 71 {H17882} The [sq
43b50 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 lite3_blob_write
43b60 28 50 2c 5a 2c 4e 2c 58 29 5d 20 69 6e 74 65 72 (P,Z,N,X)] inter
43b70 66 61 63 65 20 73 68 61 6c 6c 20 72 65 74 75 72 face shall retur
43b80 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 n.** [S
43b90 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 4e 20 62 QLITE_OK] if N b
43ba0 79 74 65 73 20 77 68 65 72 65 20 73 75 63 63 65 ytes where succe
43bb0 73 73 66 75 6c 6c 79 20 77 72 69 74 74 65 6e 20 ssfully written
43bc0 69 6e 74 6f 20 74 68 65 20 42 4c 4f 42 2e 0a 2a into the BLOB..*
43bd0 2a 0a 2a 2a 20 7b 48 31 37 38 38 35 7d 20 49 66 *.** {H17885} If
43be0 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 77 the requested w
43bf0 72 69 74 65 20 63 6f 75 6c 64 20 6e 6f 74 20 62 rite could not b
43c00 65 20 63 6f 6d 70 6c 65 74 65 64 2c 0a 2a 2a 20 e completed,.**
43c10 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 the [sq
43c20 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 lite3_blob_write
43c30 28 50 2c 5a 2c 4e 2c 58 29 5d 20 69 6e 74 65 72 (P,Z,N,X)] inter
43c40 66 61 63 65 20 73 68 61 6c 6c 20 72 65 74 75 72 face shall retur
43c50 6e 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 n an.**
43c60 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 appropriate [er
43c70 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 ror code] or [ex
43c80 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 tended error cod
43c90 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 38 e]..**.** {H1788
43ca0 38 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 8} If an error o
43cb0 63 63 75 72 73 20 64 75 72 69 6e 67 20 65 76 61 ccurs during eva
43cc0 6c 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 luation of [sqli
43cd0 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 44 te3_blob_write(D
43ce0 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 ,...)].**
43cf0 20 20 20 74 68 65 6e 20 73 75 62 73 65 71 75 65 then subseque
43d00 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c nt calls to [sql
43d10 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 5d ite3_errcode(D)]
43d20 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 ,.** [s
43d30 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f qlite3_extended_
43d40 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 errcode()],.**
43d50 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
43d60 5f 65 72 72 6d 73 67 28 44 29 5d 2c 20 61 6e 64 _errmsg(D)], and
43d70 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
43d80 31 36 28 44 29 5d 20 73 68 61 6c 6c 20 72 65 74 16(D)] shall ret
43d90 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 urn.**
43da0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 70 70 72 information appr
43db0 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68 61 74 opriate for that
43dc0 20 65 72 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 error..*/.int s
43dd0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 qlite3_blob_writ
43de0 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a e(sqlite3_blob *
43df0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c , const void *z,
43e00 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 int n, int iOff
43e10 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 set);../*.** CAP
43e20 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 46 I3REF: Virtual F
43e30 69 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a 65 63 ile System Objec
43e40 74 73 20 7b 48 31 31 32 30 30 7d 20 3c 53 32 30 ts {H11200} <S20
43e50 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 100>.**.** A vir
43e60 74 75 61 6c 20 66 69 6c 65 73 79 73 74 65 6d 20 tual filesystem
43e70 28 56 46 53 29 20 69 73 20 61 6e 20 5b 73 71 6c (VFS) is an [sql
43e80 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
43e90 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 .** that SQLite
43ea0 75 73 65 73 20 74 6f 20 69 6e 74 65 72 61 63 74 uses to interact
43eb0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 75 6e 64 .** with the und
43ec0 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e erlying operatin
43ed0 67 20 73 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20 g system. Most
43ee0 53 51 4c 69 74 65 20 62 75 69 6c 64 73 20 63 6f SQLite builds co
43ef0 6d 65 20 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e me with a.** sin
43f00 67 6c 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 gle default VFS
43f10 74 68 61 74 20 69 73 20 61 70 70 72 6f 70 72 69 that is appropri
43f20 61 74 65 20 66 6f 72 20 74 68 65 20 68 6f 73 74 ate for the host
43f30 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 computer..** Ne
43f40 77 20 56 46 53 65 73 20 63 61 6e 20 62 65 20 72 w VFSes can be r
43f50 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 65 78 egistered and ex
43f60 69 73 74 69 6e 67 20 56 46 53 65 73 20 63 61 6e isting VFSes can
43f70 20 62 65 20 75 6e 72 65 67 69 73 74 65 72 65 64 be unregistered
43f80 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 ..** The followi
43f90 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 ng interfaces ar
43fa0 65 20 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a e provided..**.*
43fb0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66 * The sqlite3_vf
43fc0 73 5f 66 69 6e 64 28 29 20 69 6e 74 65 72 66 61 s_find() interfa
43fd0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ce returns a poi
43fe0 6e 74 65 72 20 74 6f 20 61 20 56 46 53 20 67 69 nter to a VFS gi
43ff0 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 0a 2a 2a ven its name..**
44000 20 4e 61 6d 65 73 20 61 72 65 20 63 61 73 65 20 Names are case
44010 73 65 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 4e 61 sensitive..** Na
44020 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 mes are zero-ter
44030 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 minated UTF-8 st
44040 72 69 6e 67 73 2e 0a 2a 2a 20 49 66 20 74 68 65 rings..** If the
44050 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c 20 re is no match,
44060 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 a NULL pointer i
44070 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 s returned..** I
44080 66 20 7a 56 66 73 4e 61 6d 65 20 69 73 20 4e 55 f zVfsName is NU
44090 4c 4c 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 LL then the defa
440a0 75 6c 74 20 56 46 53 20 69 73 20 72 65 74 75 72 ult VFS is retur
440b0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 56 ned..**.** New V
440c0 46 53 65 73 20 61 72 65 20 72 65 67 69 73 74 65 FSes are registe
440d0 72 65 64 20 77 69 74 68 20 73 71 6c 69 74 65 33 red with sqlite3
440e0 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 2e _vfs_register().
440f0 0a 2a 2a 20 45 61 63 68 20 6e 65 77 20 56 46 53 .** Each new VFS
44100 20 62 65 63 6f 6d 65 73 20 74 68 65 20 64 65 66 becomes the def
44110 61 75 6c 74 20 56 46 53 20 69 66 20 74 68 65 20 ault VFS if the
44120 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 69 73 makeDflt flag is
44130 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20 73 61 6d set..** The sam
44140 65 20 56 46 53 20 63 61 6e 20 62 65 20 72 65 67 e VFS can be reg
44150 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 istered multiple
44160 20 74 69 6d 65 73 20 77 69 74 68 6f 75 74 20 69 times without i
44170 6e 6a 75 72 79 2e 0a 2a 2a 20 54 6f 20 6d 61 6b njury..** To mak
44180 65 20 61 6e 20 65 78 69 73 74 69 6e 67 20 56 46 e an existing VF
44190 53 20 69 6e 74 6f 20 74 68 65 20 64 65 66 61 75 S into the defau
441a0 6c 74 20 56 46 53 2c 20 72 65 67 69 73 74 65 72 lt VFS, register
441b0 20 69 74 20 61 67 61 69 6e 0a 2a 2a 20 77 69 74 it again.** wit
441c0 68 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 h the makeDflt f
441d0 6c 61 67 20 73 65 74 2e 20 20 49 66 20 74 77 6f lag set. If two
441e0 20 64 69 66 66 65 72 65 6e 74 20 56 46 53 65 73 different VFSes
441f0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 73 61 6d with the.** sam
44200 65 20 6e 61 6d 65 20 61 72 65 20 72 65 67 69 73 e name are regis
44210 74 65 72 65 64 2c 20 74 68 65 20 62 65 68 61 76 tered, the behav
44220 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ior is undefined
44230 2e 20 20 49 66 20 61 0a 2a 2a 20 56 46 53 20 69 . If a.** VFS i
44240 73 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 s registered wit
44250 68 20 61 20 6e 61 6d 65 20 74 68 61 74 20 69 73 h a name that is
44260 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 NULL or an empt
44270 79 20 73 74 72 69 6e 67 2c 0a 2a 2a 20 74 68 65 y string,.** the
44280 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 n the behavior i
44290 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a s undefined..**.
442a0 2a 2a 20 55 6e 72 65 67 69 73 74 65 72 20 61 20 ** Unregister a
442b0 56 46 53 20 77 69 74 68 20 74 68 65 20 73 71 6c VFS with the sql
442c0 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 ite3_vfs_unregis
442d0 74 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e ter() interface.
442e0 0a 2a 2a 20 49 66 20 74 68 65 20 64 65 66 61 75 .** If the defau
442f0 6c 74 20 56 46 53 20 69 73 20 75 6e 72 65 67 69 lt VFS is unregi
44300 73 74 65 72 65 64 2c 20 61 6e 6f 74 68 65 72 20 stered, another
44310 56 46 53 20 69 73 20 63 68 6f 73 65 6e 20 61 73 VFS is chosen as
44320 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e .** the default.
44330 20 20 54 68 65 20 63 68 6f 69 63 65 20 66 6f 72 The choice for
44340 20 74 68 65 20 6e 65 77 20 56 46 53 20 69 73 20 the new VFS is
44350 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a arbitrary..**.**
44360 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
44370 2a 2a 20 7b 48 31 31 32 30 33 7d 20 54 68 65 20 ** {H11203} The
44380 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e [sqlite3_vfs_fin
44390 64 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 d(N)] interface
443a0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
443b0 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 r to the.**
443c0 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20 registered
443d0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 [sqlite3_vfs] ob
443e0 6a 65 63 74 20 77 68 6f 73 65 20 6e 61 6d 65 20 ject whose name
443f0 65 78 61 63 74 6c 79 20 6d 61 74 63 68 65 73 0a exactly matches.
44400 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
44410 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
44420 55 54 46 2d 38 20 73 74 72 69 6e 67 20 4e 2c 20 UTF-8 string N,
44430 6f 72 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 or it returns NU
44440 4c 4c 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 LL if.**
44450 20 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 61 there is no ma
44460 74 63 68 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 32 tch..**.** {H112
44470 30 36 7d 20 49 66 20 74 68 65 20 4e 20 70 61 72 06} If the N par
44480 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 ameter to [sqlit
44490 65 33 5f 76 66 73 5f 66 69 6e 64 28 4e 29 5d 20 e3_vfs_find(N)]
444a0 69 73 20 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a 20 is NULL then.**
444b0 20 20 20 20 20 20 20 20 20 74 68 65 20 66 75 6e the fun
444c0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 ction returns a
444d0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 64 pointer to the d
444e0 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f efault [sqlite3_
444f0 76 66 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 vfs].**
44500 20 6f 62 6a 65 63 74 20 69 66 20 74 68 65 72 65 object if there
44510 20 69 73 20 6f 6e 65 2c 20 6f 72 20 4e 55 4c 4c is one, or NULL
44520 20 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 if there is no
44530 64 65 66 61 75 6c 74 0a 2a 2a 20 20 20 20 20 20 default.**
44540 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 [sqlite3_vfs
44550 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 ] object..**.**
44560 7b 48 31 31 32 30 39 7d 20 54 68 65 20 5b 73 71 {H11209} The [sq
44570 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 lite3_vfs_regist
44580 65 72 28 50 2c 46 29 5d 20 69 6e 74 65 72 66 61 er(P,F)] interfa
44590 63 65 20 72 65 67 69 73 74 65 72 73 20 74 68 65 ce registers the
445a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 65 6c .** wel
445b0 6c 2d 66 6f 72 6d 65 64 20 5b 73 71 6c 69 74 65 l-formed [sqlite
445c0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 50 20 3_vfs] object P
445d0 75 73 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 67 using the name g
445e0 69 76 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 iven.**
445f0 20 62 79 20 74 68 65 20 7a 4e 61 6d 65 20 66 69 by the zName fi
44600 65 6c 64 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 eld of the objec
44610 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 32 31 32 t..**.** {H11212
44620 7d 20 55 73 69 6e 67 20 74 68 65 20 5b 73 71 6c } Using the [sql
44630 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 ite3_vfs_registe
44640 72 28 50 2c 46 29 5d 20 69 6e 74 65 72 66 61 63 r(P,F)] interfac
44650 65 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a e to register.**
44660 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61 the sa
44670 6d 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d me [sqlite3_vfs]
44680 20 6f 62 6a 65 63 74 20 6d 75 6c 74 69 70 6c 65 object multiple
44690 20 74 69 6d 65 73 20 69 73 20 61 20 68 61 72 6d times is a harm
446a0 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a less no-op..**.*
446b0 2a 20 7b 48 31 31 32 31 35 7d 20 54 68 65 20 5b * {H11215} The [
446c0 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 sqlite3_vfs_regi
446d0 73 74 65 72 28 50 2c 46 29 5d 20 69 6e 74 65 72 ster(P,F)] inter
446e0 66 61 63 65 20 6d 61 6b 65 73 20 74 68 65 20 5b face makes the [
446f0 73 71 6c 69 74 65 33 5f 76 66 73 5d 0a 2a 2a 20 sqlite3_vfs].**
44700 20 20 20 20 20 20 20 20 20 6f 62 6a 65 63 74 20 object
44710 50 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 P the default [s
44720 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
44730 63 74 20 69 66 20 46 20 69 73 20 6e 6f 6e 2d 7a ct if F is non-z
44740 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 32 ero..**.** {H112
44750 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 18} The [sqlite3
44760 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 _vfs_unregister(
44770 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 75 6e P)] interface un
44780 72 65 67 69 73 74 65 72 73 20 74 68 65 0a 2a 2a registers the.**
44790 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
447a0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 50 e3_vfs] object P
447b0 20 73 6f 20 74 68 61 74 20 69 74 20 69 73 20 6e so that it is n
447c0 6f 20 6c 6f 6e 67 65 72 20 72 65 74 75 72 6e 65 o longer returne
447d0 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 d by.**
447e0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c subsequent call
447f0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76 66 s to [sqlite3_vf
44800 73 5f 66 69 6e 64 28 29 5d 2e 0a 2a 2f 0a 73 71 s_find()]..*/.sq
44810 6c 69 74 65 33 5f 76 66 73 20 2a 73 71 6c 69 74 lite3_vfs *sqlit
44820 65 33 5f 76 66 73 5f 66 69 6e 64 28 63 6f 6e 73 e3_vfs_find(cons
44830 74 20 63 68 61 72 20 2a 7a 56 66 73 4e 61 6d 65 t char *zVfsName
44840 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 );.int sqlite3_v
44850 66 73 5f 72 65 67 69 73 74 65 72 28 73 71 6c 69 fs_register(sqli
44860 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 61 te3_vfs*, int ma
44870 6b 65 44 66 6c 74 29 3b 0a 69 6e 74 20 73 71 6c keDflt);.int sql
44880 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 ite3_vfs_unregis
44890 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ter(sqlite3_vfs*
448a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
448b0 45 46 3a 20 4d 75 74 65 78 65 73 20 7b 48 31 37 EF: Mutexes {H17
448c0 30 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 000} <S20000>.**
448d0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 .** The SQLite c
448e0 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 72 ore uses these r
448f0 6f 75 74 69 6e 65 73 20 66 6f 72 20 74 68 72 65 outines for thre
44900 61 64 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e 69 7a ad.** synchroniz
44910 61 74 69 6f 6e 2e 20 54 68 6f 75 67 68 20 74 68 ation. Though th
44920 65 79 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 ey are intended
44930 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 for internal.**
44940 75 73 65 20 62 79 20 53 51 4c 69 74 65 2c 20 63 use by SQLite, c
44950 6f 64 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 ode that links a
44960 67 61 69 6e 73 74 20 53 51 4c 69 74 65 20 69 73 gainst SQLite is
44970 0a 2a 2a 20 70 65 72 6d 69 74 74 65 64 20 74 6f .** permitted to
44980 20 75 73 65 20 61 6e 79 20 6f 66 20 74 68 65 73 use any of thes
44990 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a e routines..**.*
449a0 2a 20 54 68 65 20 53 51 4c 69 74 65 20 73 6f 75 * The SQLite sou
449b0 72 63 65 20 63 6f 64 65 20 63 6f 6e 74 61 69 6e rce code contain
449c0 73 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 s multiple imple
449d0 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6f 66 mentations.** of
449e0 20 74 68 65 73 65 20 6d 75 74 65 78 20 72 6f 75 these mutex rou
449f0 74 69 6e 65 73 2e 20 20 41 6e 20 61 70 70 72 6f tines. An appro
44a00 70 72 69 61 74 65 20 69 6d 70 6c 65 6d 65 6e 74 priate implement
44a10 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c 65 ation.** is sele
44a20 63 74 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c cted automatical
44a30 6c 79 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 ly at compile-ti
44a40 6d 65 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 me. The followi
44a50 6e 67 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 ng.** implementa
44a60 74 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61 tions are availa
44a70 62 6c 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 ble in the SQLit
44a80 65 20 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 e core:.**.** <u
44a90 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c l>.** <li> SQL
44aa0 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a ITE_MUTEX_OS2.**
44ab0 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d <li> SQLITE_M
44ac0 55 54 45 58 5f 50 54 48 52 45 41 44 0a 2a 2a 20 UTEX_PTHREAD.**
44ad0 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 <li> SQLITE_MU
44ae0 54 45 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20 TEX_W32.** <li>
44af0 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e SQLITE_MUTEX_N
44b00 4f 4f 50 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a OOP.** </ul>.**.
44b10 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 ** The SQLITE_MU
44b20 54 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 TEX_NOOP impleme
44b30 6e 74 61 74 69 6f 6e 20 69 73 20 61 20 73 65 74 ntation is a set
44b40 20 6f 66 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 of routines.**
44b50 74 68 61 74 20 64 6f 65 73 20 6e 6f 20 72 65 61 that does no rea
44b60 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73 l locking and is
44b70 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 appropriate for
44b80 20 75 73 65 20 69 6e 0a 2a 2a 20 61 20 73 69 6e use in.** a sin
44b90 67 6c 65 2d 74 68 72 65 61 64 65 64 20 61 70 70 gle-threaded app
44ba0 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 53 lication. The S
44bb0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 2c QLITE_MUTEX_OS2,
44bc0 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 .** SQLITE_MUTEX
44bd0 5f 50 54 48 52 45 41 44 2c 20 61 6e 64 20 53 51 _PTHREAD, and SQ
44be0 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 20 69 LITE_MUTEX_W32 i
44bf0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a mplementations.*
44c00 2a 20 61 72 65 20 61 70 70 72 6f 70 72 69 61 74 * are appropriat
44c10 65 20 66 6f 72 20 75 73 65 20 6f 6e 20 4f 53 2f e for use on OS/
44c20 32 2c 20 55 6e 69 78 2c 20 61 6e 64 20 57 69 6e 2, Unix, and Win
44c30 64 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 53 dows..**.** If S
44c40 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
44c50 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 d with the SQLIT
44c60 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 20 70 E_MUTEX_APPDEF p
44c70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d reprocessor.** m
44c80 61 63 72 6f 20 64 65 66 69 6e 65 64 20 28 77 69 acro defined (wi
44c90 74 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d 55 54 th "-DSQLITE_MUT
44ca0 45 58 5f 41 50 50 44 45 46 3d 31 22 29 2c 20 74 EX_APPDEF=1"), t
44cb0 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20 hen no mutex.**
44cc0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 implementation i
44cd0 73 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68 20 s included with
44ce0 74 68 65 20 6c 69 62 72 61 72 79 2e 20 49 6e 20 the library. In
44cf0 74 68 69 73 20 63 61 73 65 20 74 68 65 0a 2a 2a this case the.**
44d00 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
44d10 74 20 73 75 70 70 6c 79 20 61 20 63 75 73 74 6f t supply a custo
44d20 6d 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e m mutex implemen
44d30 74 61 74 69 6f 6e 20 75 73 69 6e 67 20 74 68 65 tation using the
44d40 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 .** [SQLITE_CONF
44d50 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e IG_MUTEX] option
44d60 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f of the sqlite3_
44d70 63 6f 6e 66 69 67 28 29 20 66 75 6e 63 74 69 6f config() functio
44d80 6e 0a 2a 2a 20 62 65 66 6f 72 65 20 63 61 6c 6c n.** before call
44d90 69 6e 67 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 ing sqlite3_init
44da0 69 61 6c 69 7a 65 28 29 20 6f 72 20 61 6e 79 20 ialize() or any
44db0 6f 74 68 65 72 20 70 75 62 6c 69 63 20 73 71 6c other public sql
44dc0 69 74 65 33 5f 0a 2a 2a 20 66 75 6e 63 74 69 6f ite3_.** functio
44dd0 6e 20 74 68 61 74 20 63 61 6c 6c 73 20 73 71 6c n that calls sql
44de0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
44df0 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 31 )..**.** {H17011
44e00 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 } The sqlite3_mu
44e10 74 65 78 5f 61 6c 6c 6f 63 28 29 20 72 6f 75 74 tex_alloc() rout
44e20 69 6e 65 20 61 6c 6c 6f 63 61 74 65 73 20 61 20 ine allocates a
44e30 6e 65 77 0a 2a 2a 20 6d 75 74 65 78 20 61 6e 64 new.** mutex and
44e40 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
44e50 65 72 20 74 6f 20 69 74 2e 20 7b 48 31 37 30 31 er to it. {H1701
44e60 32 7d 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 2} If it returns
44e70 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d 65 NULL.** that me
44e80 61 6e 73 20 74 68 61 74 20 61 20 6d 75 74 65 78 ans that a mutex
44e90 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 61 6c could not be al
44ea0 6c 6f 63 61 74 65 64 2e 20 7b 48 31 37 30 31 33 located. {H17013
44eb0 7d 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c } SQLite.** will
44ec0 20 75 6e 77 69 6e 64 20 69 74 73 20 73 74 61 63 unwind its stac
44ed0 6b 20 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 k and return an
44ee0 65 72 72 6f 72 2e 20 7b 48 31 37 30 31 34 7d 20 error. {H17014}
44ef0 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 The argument.**
44f00 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 to sqlite3_mutex
44f10 5f 61 6c 6c 6f 63 28 29 20 69 73 20 6f 6e 65 20 _alloc() is one
44f20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 of these integer
44f30 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 0a 2a constants:.**.*
44f40 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 * <ul>.** <li>
44f50 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 SQLITE_MUTEX_FAS
44f60 54 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 T.** <li> SQLIT
44f70 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 E_MUTEX_RECURSIV
44f80 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 E.** <li> SQLIT
44f90 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d E_MUTEX_STATIC_M
44fa0 41 53 54 45 52 0a 2a 2a 20 3c 6c 69 3e 20 20 53 ASTER.** <li> S
44fb0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 QLITE_MUTEX_STAT
44fc0 49 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 20 IC_MEM.** <li>
44fd0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 SQLITE_MUTEX_STA
44fe0 54 49 43 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 3e TIC_MEM2.** <li>
44ff0 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 SQLITE_MUTEX_S
45000 54 41 54 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c 6c TATIC_PRNG.** <l
45010 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 i> SQLITE_MUTEX
45020 5f 53 54 41 54 49 43 5f 4c 52 55 0a 2a 2a 20 3c _STATIC_LRU.** <
45030 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 li> SQLITE_MUTE
45040 58 5f 53 54 41 54 49 43 5f 4c 52 55 32 0a 2a 2a X_STATIC_LRU2.**
45050 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 </ul>.**.** {H1
45060 37 30 31 35 7d 20 54 68 65 20 66 69 72 73 74 20 7015} The first
45070 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 two constants ca
45080 75 73 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 use sqlite3_mute
45090 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20 63 72 65 x_alloc() to cre
450a0 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20 6d 75 74 ate.** a new mut
450b0 65 78 2e 20 20 54 68 65 20 6e 65 77 20 6d 75 74 ex. The new mut
450c0 65 78 20 69 73 20 72 65 63 75 72 73 69 76 65 20 ex is recursive
450d0 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 when SQLITE_MUTE
450e0 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 69 X_RECURSIVE.** i
450f0 73 20 75 73 65 64 20 62 75 74 20 6e 6f 74 20 6e s used but not n
45100 65 63 65 73 73 61 72 69 6c 79 20 73 6f 20 77 68 ecessarily so wh
45110 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f en SQLITE_MUTEX_
45120 46 41 53 54 20 69 73 20 75 73 65 64 2e 20 7b 45 FAST is used. {E
45130 4e 44 7d 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 ND}.** The mutex
45140 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
45150 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f does not need to
45160 20 6d 61 6b 65 20 61 20 64 69 73 74 69 6e 63 74 make a distinct
45170 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 ion.** between S
45180 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 QLITE_MUTEX_RECU
45190 52 53 49 56 45 20 61 6e 64 20 53 51 4c 49 54 45 RSIVE and SQLITE
451a0 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 66 20 69 _MUTEX_FAST if i
451b0 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 t does.** not wa
451c0 6e 74 20 74 6f 2e 20 20 7b 48 31 37 30 31 36 7d nt to. {H17016}
451d0 20 42 75 74 20 53 51 4c 69 74 65 20 77 69 6c 6c But SQLite will
451e0 20 6f 6e 6c 79 20 72 65 71 75 65 73 74 20 61 20 only request a
451f0 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 20 recursive mutex
45200 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77 68 65 72 in.** cases wher
45210 65 20 69 74 20 72 65 61 6c 6c 79 20 6e 65 65 64 e it really need
45220 73 20 6f 6e 65 2e 20 20 7b 45 4e 44 7d 20 49 66 s one. {END} If
45230 20 61 20 66 61 73 74 65 72 20 6e 6f 6e 2d 72 65 a faster non-re
45240 63 75 72 73 69 76 65 20 6d 75 74 65 78 0a 2a 2a cursive mutex.**
45250 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
45260 69 73 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 is available on
45270 74 68 65 20 68 6f 73 74 20 70 6c 61 74 66 6f 72 the host platfor
45280 6d 2c 20 74 68 65 20 6d 75 74 65 78 20 73 75 62 m, the mutex sub
45290 73 79 73 74 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 system.** might
452a0 72 65 74 75 72 6e 20 73 75 63 68 20 61 20 6d 75 return such a mu
452b0 74 65 78 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 tex in response
452c0 74 6f 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f to SQLITE_MUTEX_
452d0 46 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 FAST..**.** {H17
452e0 30 31 37 7d 20 54 68 65 20 6f 74 68 65 72 20 61 017} The other a
452f0 6c 6c 6f 77 65 64 20 70 61 72 61 6d 65 74 65 72 llowed parameter
45300 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 s to sqlite3_mut
45310 65 78 5f 61 6c 6c 6f 63 28 29 20 65 61 63 68 20 ex_alloc() each
45320 72 65 74 75 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e return.** a poin
45330 74 65 72 20 74 6f 20 61 20 73 74 61 74 69 63 20 ter to a static
45340 70 72 65 65 78 69 73 74 69 6e 67 20 6d 75 74 65 preexisting mute
45350 78 2e 20 7b 45 4e 44 7d 20 20 46 6f 75 72 20 73 x. {END} Four s
45360 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72 tatic mutexes ar
45370 65 0a 2a 2a 20 75 73 65 64 20 62 79 20 74 68 65 e.** used by the
45380 20 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f 6e current version
45390 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 46 75 74 of SQLite. Fut
453a0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 ure versions of
453b0 53 51 4c 69 74 65 0a 2a 2a 20 6d 61 79 20 61 64 SQLite.** may ad
453c0 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61 d additional sta
453d0 74 69 63 20 6d 75 74 65 78 65 73 2e 20 20 53 74 tic mutexes. St
453e0 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72 65 atic mutexes are
453f0 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a for internal.**
45400 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 20 6f use by SQLite o
45410 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f nly. Applicatio
45420 6e 73 20 74 68 61 74 20 75 73 65 20 53 51 4c 69 ns that use SQLi
45430 74 65 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c te mutexes shoul
45440 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79 20 74 68 d.** use only th
45450 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65 e dynamic mutexe
45460 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 s returned by SQ
45470 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 LITE_MUTEX_FAST
45480 6f 72 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 or.** SQLITE_MUT
45490 45 58 5f 52 45 43 55 52 53 49 56 45 2e 0a 2a 2a EX_RECURSIVE..**
454a0 0a 2a 2a 20 7b 48 31 37 30 31 38 7d 20 4e 6f 74 .** {H17018} Not
454b0 65 20 74 68 61 74 20 69 66 20 6f 6e 65 20 6f 66 e that if one of
454c0 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 the dynamic mut
454d0 65 78 20 70 61 72 61 6d 65 74 65 72 73 20 28 53 ex parameters (S
454e0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 QLITE_MUTEX_FAST
454f0 0a 2a 2a 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55 .** or SQLITE_MU
45500 54 45 58 5f 52 45 43 55 52 53 49 56 45 29 20 69 TEX_RECURSIVE) i
45510 73 20 75 73 65 64 20 74 68 65 6e 20 73 71 6c 69 s used then sqli
45520 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 te3_mutex_alloc(
45530 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 64 ).** returns a d
45540 69 66 66 65 72 65 6e 74 20 6d 75 74 65 78 20 6f ifferent mutex o
45550 6e 20 65 76 65 72 79 20 63 61 6c 6c 2e 20 20 7b n every call. {
45560 48 31 37 30 33 34 7d 20 42 75 74 20 66 6f 72 20 H17034} But for
45570 74 68 65 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 the static.** mu
45580 74 65 78 20 74 79 70 65 73 2c 20 74 68 65 20 73 tex types, the s
45590 61 6d 65 20 6d 75 74 65 78 20 69 73 20 72 65 74 ame mutex is ret
455a0 75 72 6e 65 64 20 6f 6e 20 65 76 65 72 79 20 63 urned on every c
455b0 61 6c 6c 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 all that has.**
455c0 74 68 65 20 73 61 6d 65 20 74 79 70 65 20 6e 75 the same type nu
455d0 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 mber..**.** {H17
455e0 30 31 39 7d 20 54 68 65 20 73 71 6c 69 74 65 33 019} The sqlite3
455f0 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 20 72 6f _mutex_free() ro
45600 75 74 69 6e 65 20 64 65 61 6c 6c 6f 63 61 74 65 utine deallocate
45610 73 20 61 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a s a previously.*
45620 2a 20 61 6c 6c 6f 63 61 74 65 64 20 64 79 6e 61 * allocated dyna
45630 6d 69 63 20 6d 75 74 65 78 2e 20 7b 48 31 37 30 mic mutex. {H170
45640 32 30 7d 20 53 51 4c 69 74 65 20 69 73 20 63 61 20} SQLite is ca
45650 72 65 66 75 6c 20 74 6f 20 64 65 61 6c 6c 6f 63 reful to dealloc
45660 61 74 65 20 65 76 65 72 79 0a 2a 2a 20 64 79 6e ate every.** dyn
45670 61 6d 69 63 20 6d 75 74 65 78 20 74 68 61 74 20 amic mutex that
45680 69 74 20 61 6c 6c 6f 63 61 74 65 73 2e 20 7b 41 it allocates. {A
45690 31 37 30 32 31 7d 20 54 68 65 20 64 79 6e 61 6d 17021} The dynam
456a0 69 63 20 6d 75 74 65 78 65 73 20 6d 75 73 74 20 ic mutexes must
456b0 6e 6f 74 20 62 65 20 69 6e 0a 2a 2a 20 75 73 65 not be in.** use
456c0 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 64 when they are d
456d0 65 61 6c 6c 6f 63 61 74 65 64 2e 20 7b 41 31 37 eallocated. {A17
456e0 30 32 32 7d 20 41 74 74 65 6d 70 74 69 6e 67 20 022} Attempting
456f0 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 20 to deallocate a
45700 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20 static.** mutex
45710 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 results in undef
45720 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 20 7b ined behavior. {
45730 48 31 37 30 32 33 7d 20 53 51 4c 69 74 65 20 6e H17023} SQLite n
45740 65 76 65 72 20 64 65 61 6c 6c 6f 63 61 74 65 73 ever deallocates
45750 0a 2a 2a 20 61 20 73 74 61 74 69 63 20 6d 75 74 .** a static mut
45760 65 78 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 ex. {END}.**.**
45770 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 The sqlite3_mute
45780 78 5f 65 6e 74 65 72 28 29 20 61 6e 64 20 73 71 x_enter() and sq
45790 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 lite3_mutex_try(
457a0 29 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d ) routines attem
457b0 70 74 0a 2a 2a 20 74 6f 20 65 6e 74 65 72 20 61 pt.** to enter a
457c0 20 6d 75 74 65 78 2e 20 7b 48 31 37 30 32 34 7d mutex. {H17024}
457d0 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 If another thre
457e0 61 64 20 69 73 20 61 6c 72 65 61 64 79 20 77 69 ad is already wi
457f0 74 68 69 6e 20 74 68 65 20 6d 75 74 65 78 2c 0a thin the mutex,.
45800 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 ** sqlite3_mutex
45810 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c 20 62 6c _enter() will bl
45820 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 65 33 5f ock and sqlite3_
45830 6d 75 74 65 78 5f 74 72 79 28 29 20 77 69 6c 6c mutex_try() will
45840 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 return.** SQLIT
45850 45 5f 42 55 53 59 2e 20 7b 48 31 37 30 32 35 7d E_BUSY. {H17025}
45860 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 The sqlite3_mu
45870 74 65 78 5f 74 72 79 28 29 20 69 6e 74 65 72 66 tex_try() interf
45880 61 63 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ace returns [SQL
45890 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 75 70 6f 6e 20 ITE_OK].** upon
458a0 73 75 63 63 65 73 73 66 75 6c 20 65 6e 74 72 79 successful entry
458b0 2e 20 20 7b 48 31 37 30 32 36 7d 20 4d 75 74 65 . {H17026} Mute
458c0 78 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e xes created usin
458d0 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 g.** SQLITE_MUTE
458e0 58 5f 52 45 43 55 52 53 49 56 45 20 63 61 6e 20 X_RECURSIVE can
458f0 62 65 20 65 6e 74 65 72 65 64 20 6d 75 6c 74 69 be entered multi
45900 70 6c 65 20 74 69 6d 65 73 20 62 79 20 74 68 65 ple times by the
45910 20 73 61 6d 65 20 74 68 72 65 61 64 2e 0a 2a 2a same thread..**
45920 20 7b 48 31 37 30 32 37 7d 20 49 6e 20 73 75 63 {H17027} In suc
45930 68 20 63 61 73 65 73 20 74 68 65 2c 0a 2a 2a 20 h cases the,.**
45940 6d 75 74 65 78 20 6d 75 73 74 20 62 65 20 65 78 mutex must be ex
45950 69 74 65 64 20 61 6e 20 65 71 75 61 6c 20 6e 75 ited an equal nu
45960 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 62 65 mber of times be
45970 66 6f 72 65 20 61 6e 6f 74 68 65 72 20 74 68 72 fore another thr
45980 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74 65 72 ead.** can enter
45990 2e 20 20 7b 41 31 37 30 32 38 7d 20 49 66 20 74 . {A17028} If t
459a0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 74 he same thread t
459b0 72 69 65 73 20 74 6f 20 65 6e 74 65 72 20 61 6e ries to enter an
459c0 79 20 6f 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 y other.** kind
459d0 6f 66 20 6d 75 74 65 78 20 6d 6f 72 65 20 74 68 of mutex more th
459e0 61 6e 20 6f 6e 63 65 2c 20 74 68 65 20 62 65 68 an once, the beh
459f0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e avior is undefin
45a00 65 64 2e 0a 2a 2a 20 7b 48 31 37 30 32 39 7d 20 ed..** {H17029}
45a10 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 SQLite will neve
45a20 72 20 65 78 68 69 62 69 74 0a 2a 2a 20 73 75 63 r exhibit.** suc
45a30 68 20 62 65 68 61 76 69 6f 72 20 69 6e 20 69 74 h behavior in it
45a40 73 20 6f 77 6e 20 75 73 65 20 6f 66 20 6d 75 74 s own use of mut
45a50 65 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 exes..**.** Some
45a60 20 73 79 73 74 65 6d 73 20 28 66 6f 72 20 65 78 systems (for ex
45a70 61 6d 70 6c 65 2c 20 57 69 6e 64 6f 77 73 20 39 ample, Windows 9
45a80 35 29 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72 5) do not suppor
45a90 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a t the operation.
45aa0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 ** implemented b
45ab0 79 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f y sqlite3_mutex_
45ac0 74 72 79 28 29 2e 20 20 4f 6e 20 74 68 6f 73 65 try(). On those
45ad0 20 73 79 73 74 65 6d 73 2c 20 73 71 6c 69 74 65 systems, sqlite
45ae0 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 0a 2a 2a 3_mutex_try().**
45af0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 will always ret
45b00 75 72 6e 20 53 51 4c 49 54 45 5f 42 55 53 59 2e urn SQLITE_BUSY.
45b10 20 20 7b 48 31 37 30 33 30 7d 20 54 68 65 20 53 {H17030} The S
45b20 51 4c 69 74 65 20 63 6f 72 65 20 6f 6e 6c 79 20 QLite core only
45b30 65 76 65 72 20 75 73 65 73 0a 2a 2a 20 73 71 6c ever uses.** sql
45b40 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 ite3_mutex_try()
45b50 20 61 73 20 61 6e 20 6f 70 74 69 6d 69 7a 61 74 as an optimizat
45b60 69 6f 6e 20 73 6f 20 74 68 69 73 20 69 73 20 61 ion so this is a
45b70 63 63 65 70 74 61 62 6c 65 20 62 65 68 61 76 69 cceptable behavi
45b80 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 33 or..**.** {H1703
45b90 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 1} The sqlite3_m
45ba0 75 74 65 78 5f 6c 65 61 76 65 28 29 20 72 6f 75 utex_leave() rou
45bb0 74 69 6e 65 20 65 78 69 74 73 20 61 20 6d 75 74 tine exits a mut
45bc0 65 78 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 70 ex that was.** p
45bd0 72 65 76 69 6f 75 73 6c 79 20 65 6e 74 65 72 65 reviously entere
45be0 64 20 62 79 20 74 68 65 20 73 61 6d 65 20 74 68 d by the same th
45bf0 72 65 61 64 2e 20 20 7b 41 31 37 30 33 32 7d 20 read. {A17032}
45c00 54 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 The behavior.**
45c10 69 73 20 75 6e 64 65 66 69 6e 65 64 20 69 66 20 is undefined if
45c20 74 68 65 20 6d 75 74 65 78 20 69 73 20 6e 6f 74 the mutex is not
45c30 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 currently enter
45c40 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c ed by the.** cal
45c50 6c 69 6e 67 20 74 68 72 65 61 64 20 6f 72 20 69 ling thread or i
45c60 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 s not currently
45c70 61 6c 6c 6f 63 61 74 65 64 2e 20 20 7b 48 31 37 allocated. {H17
45c80 30 33 33 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 033} SQLite will
45c90 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20 65 69 74 .** never do eit
45ca0 68 65 72 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a her. {END}.**.**
45cb0 20 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 If the argument
45cc0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 to sqlite3_mute
45cd0 78 5f 65 6e 74 65 72 28 29 2c 20 73 71 6c 69 74 x_enter(), sqlit
45ce0 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 2c 20 e3_mutex_try(),
45cf0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 or.** sqlite3_mu
45d00 74 65 78 5f 6c 65 61 76 65 28 29 20 69 73 20 61 tex_leave() is a
45d10 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 NULL pointer, t
45d20 68 65 6e 20 61 6c 6c 20 74 68 72 65 65 20 72 6f hen all three ro
45d30 75 74 69 6e 65 73 0a 2a 2a 20 62 65 68 61 76 65 utines.** behave
45d40 20 61 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a as no-ops..**.*
45d50 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
45d60 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 ite3_mutex_held(
45d70 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
45d80 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d mutex_notheld()]
45d90 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 ..*/.sqlite3_mut
45da0 65 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65 ex *sqlite3_mute
45db0 78 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f x_alloc(int);.vo
45dc0 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 id sqlite3_mutex
45dd0 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f 6d 75 _free(sqlite3_mu
45de0 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 tex*);.void sqli
45df0 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 te3_mutex_enter(
45e00 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b sqlite3_mutex*);
45e10 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 .int sqlite3_mut
45e20 65 78 5f 74 72 79 28 73 71 6c 69 74 65 33 5f 6d ex_try(sqlite3_m
45e30 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c utex*);.void sql
45e40 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 ite3_mutex_leave
45e50 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 (sqlite3_mutex*)
45e60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
45e70 46 3a 20 4d 75 74 65 78 20 4d 65 74 68 6f 64 73 F: Mutex Methods
45e80 20 4f 62 6a 65 63 74 20 7b 48 31 37 31 32 30 7d Object {H17120}
45e90 20 3c 53 32 30 31 33 30 3e 0a 2a 2a 20 45 58 50 <S20130>.** EXP
45ea0 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 ERIMENTAL.**.**
45eb0 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 An instance of t
45ec0 68 69 73 20 73 74 72 75 63 74 75 72 65 20 64 65 his structure de
45ed0 66 69 6e 65 73 20 74 68 65 20 6c 6f 77 2d 6c 65 fines the low-le
45ee0 76 65 6c 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 vel routines.**
45ef0 75 73 65 64 20 74 6f 20 61 6c 6c 6f 63 61 74 65 used to allocate
45f00 20 61 6e 64 20 75 73 65 20 6d 75 74 65 78 65 73 and use mutexes
45f10 2e 0a 2a 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c ..**.** Usually,
45f20 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 the default mut
45f30 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ex implementatio
45f40 6e 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 53 ns provided by S
45f50 51 4c 69 74 65 20 61 72 65 0a 2a 2a 20 73 75 66 QLite are.** suf
45f60 66 69 63 69 65 6e 74 2c 20 68 6f 77 65 76 65 72 ficient, however
45f70 20 74 68 65 20 75 73 65 72 20 68 61 73 20 74 68 the user has th
45f80 65 20 6f 70 74 69 6f 6e 20 6f 66 20 73 75 62 73 e option of subs
45f90 74 69 74 75 74 69 6e 67 20 61 20 63 75 73 74 6f tituting a custo
45fa0 6d 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 m.** implementat
45fb0 69 6f 6e 20 66 6f 72 20 73 70 65 63 69 61 6c 69 ion for speciali
45fc0 7a 65 64 20 64 65 70 6c 6f 79 6d 65 6e 74 73 20 zed deployments
45fd0 6f 72 20 73 79 73 74 65 6d 73 20 66 6f 72 20 77 or systems for w
45fe0 68 69 63 68 20 53 51 4c 69 74 65 0a 2a 2a 20 64 hich SQLite.** d
45ff0 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 oes not provide
46000 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 a suitable imple
46010 6d 65 6e 74 61 74 69 6f 6e 2e 20 49 6e 20 74 68 mentation. In th
46020 69 73 20 63 61 73 65 2c 20 74 68 65 20 75 73 65 is case, the use
46030 72 0a 2a 2a 20 63 72 65 61 74 65 73 20 61 6e 64 r.** creates and
46040 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 20 69 6e populates an in
46050 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 stance of this s
46060 74 72 75 63 74 75 72 65 20 74 6f 20 70 61 73 73 tructure to pass
46070 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 .** to sqlite3_c
46080 6f 6e 66 69 67 28 29 20 61 6c 6f 6e 67 20 77 69 onfig() along wi
46090 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 th the [SQLITE_C
460a0 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 ONFIG_MUTEX] opt
460b0 69 6f 6e 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e ion..** Addition
460c0 61 6c 6c 79 2c 20 61 6e 20 69 6e 73 74 61 6e 63 ally, an instanc
460d0 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 e of this struct
460e0 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ure can be used
460f0 61 73 20 61 6e 0a 2a 2a 20 6f 75 74 70 75 74 20 as an.** output
46100 76 61 72 69 61 62 6c 65 20 77 68 65 6e 20 71 75 variable when qu
46110 65 72 79 69 6e 67 20 74 68 65 20 73 79 73 74 65 erying the syste
46120 6d 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e m for the curren
46130 74 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 t mutex.** imple
46140 6d 65 6e 74 61 74 69 6f 6e 2c 20 75 73 69 6e 67 mentation, using
46150 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e the [SQLITE_CON
46160 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 20 6f 70 FIG_GETMUTEX] op
46170 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 tion..**.** The
46180 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f xMutexInit metho
46190 64 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 d defined by thi
461a0 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20 69 s structure is i
461b0 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 nvoked as.** par
461c0 74 20 6f 66 20 73 79 73 74 65 6d 20 69 6e 69 74 t of system init
461d0 69 61 6c 69 7a 61 74 69 6f 6e 20 62 79 20 74 68 ialization by th
461e0 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
461f0 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 2e lize() function.
46200 0a 2a 2a 20 7b 48 31 37 30 30 31 7d 20 54 68 65 .** {H17001} The
46210 20 78 4d 75 74 65 78 49 6e 69 74 20 72 6f 75 74 xMutexInit rout
46220 69 6e 65 20 73 68 61 6c 6c 20 62 65 20 63 61 6c ine shall be cal
46230 6c 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e led by SQLite on
46240 63 65 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 65 ce for each.** e
46250 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f ffective call to
46260 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 [sqlite3_initia
46270 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 lize()]..**.** T
46280 68 65 20 78 4d 75 74 65 78 45 6e 64 20 6d 65 74 he xMutexEnd met
46290 68 6f 64 20 64 65 66 69 6e 65 64 20 62 79 20 74 hod defined by t
462a0 68 69 73 20 73 74 72 75 63 74 75 72 65 20 69 73 his structure is
462b0 20 69 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 invoked as.** p
462c0 61 72 74 20 6f 66 20 73 79 73 74 65 6d 20 73 68 art of system sh
462d0 75 74 64 6f 77 6e 20 62 79 20 74 68 65 20 73 71 utdown by the sq
462e0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
462f0 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 0a 2a function. The.*
46300 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
46310 20 6f 66 20 74 68 69 73 20 6d 65 74 68 6f 64 20 of this method
46320 69 73 20 65 78 70 65 63 74 65 64 20 74 6f 20 72 is expected to r
46330 65 6c 65 61 73 65 20 61 6c 6c 20 6f 75 74 73 74 elease all outst
46340 61 6e 64 69 6e 67 0a 2a 2a 20 72 65 73 6f 75 72 anding.** resour
46350 63 65 73 20 6f 62 74 61 69 6e 65 64 20 62 79 20 ces obtained by
46360 74 68 65 20 6d 75 74 65 78 20 6d 65 74 68 6f 64 the mutex method
46370 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e s implementation
46380 2c 20 65 73 70 65 63 69 61 6c 6c 79 0a 2a 2a 20 , especially.**
46390 74 68 6f 73 65 20 6f 62 74 61 69 6e 65 64 20 62 those obtained b
463a0 79 20 74 68 65 20 78 4d 75 74 65 78 49 6e 69 74 y the xMutexInit
463b0 20 6d 65 74 68 6f 64 2e 20 7b 48 31 37 30 30 33 method. {H17003
463c0 7d 20 54 68 65 20 78 4d 75 74 65 78 45 6e 64 28 } The xMutexEnd(
463d0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 73 ).** interface s
463e0 68 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 hall be invoked
463f0 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 63 61 once for each ca
46400 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 ll to [sqlite3_s
46410 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a hutdown()]..**.*
46420 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 * The remaining
46430 73 65 76 65 6e 20 6d 65 74 68 6f 64 73 20 64 65 seven methods de
46440 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 74 fined by this st
46450 72 75 63 74 75 72 65 20 28 78 4d 75 74 65 78 41 ructure (xMutexA
46460 6c 6c 6f 63 2c 0a 2a 2a 20 78 4d 75 74 65 78 46 lloc,.** xMutexF
46470 72 65 65 2c 20 78 4d 75 74 65 78 45 6e 74 65 72 ree, xMutexEnter
46480 2c 20 78 4d 75 74 65 78 54 72 79 2c 20 78 4d 75 , xMutexTry, xMu
46490 74 65 78 4c 65 61 76 65 2c 20 78 4d 75 74 65 78 texLeave, xMutex
464a0 48 65 6c 64 20 61 6e 64 0a 2a 2a 20 78 4d 75 74 Held and.** xMut
464b0 65 78 4e 6f 74 68 65 6c 64 29 20 69 6d 70 6c 65 exNotheld) imple
464c0 6d 65 6e 74 20 74 68 65 20 66 6f 6c 6c 6f 77 69 ment the followi
464d0 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20 28 72 ng interfaces (r
464e0 65 73 70 65 63 74 69 76 65 6c 79 29 3a 0a 2a 2a espectively):.**
464f0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c .** <ul>.** <l
46500 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 i> [sqlite3_mut
46510 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 3c 2f 6c 69 ex_alloc()] </li
46520 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 >.** <li> [sq
46530 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 lite3_mutex_free
46540 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c ()] </li>.** <
46550 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 li> [sqlite3_mu
46560 74 65 78 5f 65 6e 74 65 72 28 29 5d 20 3c 2f 6c tex_enter()] </l
46570 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 i>.** <li> [s
46580 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 qlite3_mutex_try
46590 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c ()] </li>.** <
465a0 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 li> [sqlite3_mu
465b0 74 65 78 5f 6c 65 61 76 65 28 29 5d 20 3c 2f 6c tex_leave()] </l
465c0 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 i>.** <li> [s
465d0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c qlite3_mutex_hel
465e0 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 d()] </li>.**
465f0 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d <li> [sqlite3_m
46600 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 20 utex_notheld()]
46610 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a </li>.** </ul>.*
46620 2a 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 64 69 *.** The only di
46630 66 66 65 72 65 6e 63 65 20 69 73 20 74 68 61 74 fference is that
46640 20 74 68 65 20 70 75 62 6c 69 63 20 73 71 6c 69 the public sqli
46650 74 65 33 5f 58 58 58 20 66 75 6e 63 74 69 6f 6e te3_XXX function
46660 73 20 65 6e 75 6d 65 72 61 74 65 64 0a 2a 2a 20 s enumerated.**
46670 61 62 6f 76 65 20 73 69 6c 65 6e 74 6c 79 20 69 above silently i
46680 67 6e 6f 72 65 20 61 6e 79 20 69 6e 76 6f 63 61 gnore any invoca
46690 74 69 6f 6e 73 20 74 68 61 74 20 70 61 73 73 20 tions that pass
466a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 a NULL pointer i
466b0 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 76 nstead.** of a v
466c0 61 6c 69 64 20 6d 75 74 65 78 20 68 61 6e 64 6c alid mutex handl
466d0 65 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 e. The implement
466e0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 6d 65 ations of the me
466f0 74 68 6f 64 73 20 64 65 66 69 6e 65 64 0a 2a 2a thods defined.**
46700 20 62 79 20 74 68 69 73 20 73 74 72 75 63 74 75 by this structu
46710 72 65 20 61 72 65 20 6e 6f 74 20 72 65 71 75 69 re are not requi
46720 72 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 74 68 red to handle th
46730 69 73 20 63 61 73 65 2c 20 74 68 65 20 72 65 73 is case, the res
46740 75 6c 74 73 0a 2a 2a 20 6f 66 20 70 61 73 73 69 ults.** of passi
46750 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ng a NULL pointe
46760 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 76 r instead of a v
46770 61 6c 69 64 20 6d 75 74 65 78 20 68 61 6e 64 6c alid mutex handl
46780 65 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 0a e are undefined.
46790 2a 2a 20 28 69 2e 65 2e 20 69 74 20 69 73 20 61 ** (i.e. it is a
467a0 63 63 65 70 74 61 62 6c 65 20 74 6f 20 70 72 6f cceptable to pro
467b0 76 69 64 65 20 61 6e 20 69 6d 70 6c 65 6d 65 6e vide an implemen
467c0 74 61 74 69 6f 6e 20 74 68 61 74 20 73 65 67 66 tation that segf
467d0 61 75 6c 74 73 20 69 66 0a 2a 2a 20 69 74 20 69 aults if.** it i
467e0 73 20 70 61 73 73 65 64 20 61 20 4e 55 4c 4c 20 s passed a NULL
467f0 70 6f 69 6e 74 65 72 29 2e 0a 2a 2f 0a 74 79 70 pointer)..*/.typ
46800 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
46810 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 te3_mutex_method
46820 73 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f s sqlite3_mutex_
46830 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 methods;.struct
46840 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 sqlite3_mutex_me
46850 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 28 2a thods {. int (*
46860 78 4d 75 74 65 78 49 6e 69 74 29 28 76 6f 69 64 xMutexInit)(void
46870 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 );. int (*xMute
46880 78 45 6e 64 29 28 76 6f 69 64 29 3b 0a 20 20 73 xEnd)(void);. s
46890 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 28 2a qlite3_mutex *(*
468a0 78 4d 75 74 65 78 41 6c 6c 6f 63 29 28 69 6e 74 xMutexAlloc)(int
468b0 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 74 );. void (*xMut
468c0 65 78 46 72 65 65 29 28 73 71 6c 69 74 65 33 5f exFree)(sqlite3_
468d0 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 mutex *);. void
468e0 20 28 2a 78 4d 75 74 65 78 45 6e 74 65 72 29 28 (*xMutexEnter)(
468f0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 sqlite3_mutex *)
46900 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 ;. int (*xMutex
46910 54 72 79 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 Try)(sqlite3_mut
46920 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a ex *);. void (*
46930 78 4d 75 74 65 78 4c 65 61 76 65 29 28 73 71 6c xMutexLeave)(sql
46940 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 ite3_mutex *);.
46950 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 48 65 6c int (*xMutexHel
46960 64 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 d)(sqlite3_mutex
46970 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 *);. int (*xMu
46980 74 65 78 4e 6f 74 68 65 6c 64 29 28 73 71 6c 69 texNotheld)(sqli
46990 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d 3b te3_mutex *);.};
469a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
469b0 3a 20 4d 75 74 65 78 20 56 65 72 69 66 69 63 61 : Mutex Verifica
469c0 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48 tion Routines {H
469d0 31 37 30 38 30 7d 20 3c 53 32 30 31 33 30 3e 20 17080} <S20130>
469e0 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S30800>.**.** T
469f0 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 he sqlite3_mutex
46a00 5f 68 65 6c 64 28 29 20 61 6e 64 20 73 71 6c 69 _held() and sqli
46a10 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c te3_mutex_nothel
46a20 64 28 29 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 d() routines.**
46a30 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 are intended for
46a40 20 75 73 65 20 69 6e 73 69 64 65 20 61 73 73 65 use inside asse
46a50 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 2e rt() statements.
46a60 20 7b 48 31 37 30 38 31 7d 20 54 68 65 20 53 51 {H17081} The SQ
46a70 4c 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 Lite core.** nev
46a80 65 72 20 75 73 65 73 20 74 68 65 73 65 20 72 6f er uses these ro
46a90 75 74 69 6e 65 73 20 65 78 63 65 70 74 20 69 6e utines except in
46aa0 73 69 64 65 20 61 6e 20 61 73 73 65 72 74 28 29 side an assert()
46ab0 20 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e and application
46ac0 73 0a 2a 2a 20 61 72 65 20 61 64 76 69 73 65 64 s.** are advised
46ad0 20 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c to follow the l
46ae0 65 61 64 20 6f 66 20 74 68 65 20 63 6f 72 65 2e ead of the core.
46af0 20 20 7b 48 31 37 30 38 32 7d 20 54 68 65 20 63 {H17082} The c
46b00 6f 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 ore only.** prov
46b10 69 64 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ides implementat
46b20 69 6f 6e 73 20 66 6f 72 20 74 68 65 73 65 20 72 ions for these r
46b30 6f 75 74 69 6e 65 73 20 77 68 65 6e 20 69 74 20 outines when it
46b40 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 is compiled.** w
46b50 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 44 ith the SQLITE_D
46b60 45 42 55 47 20 66 6c 61 67 2e 20 20 7b 41 31 37 EBUG flag. {A17
46b70 30 38 37 7d 20 45 78 74 65 72 6e 61 6c 20 6d 75 087} External mu
46b80 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 tex implementati
46b90 6f 6e 73 0a 2a 2a 20 61 72 65 20 6f 6e 6c 79 20 ons.** are only
46ba0 72 65 71 75 69 72 65 64 20 74 6f 20 70 72 6f 76 required to prov
46bb0 69 64 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e ide these routin
46bc0 65 73 20 69 66 20 53 51 4c 49 54 45 5f 44 45 42 es if SQLITE_DEB
46bd0 55 47 20 69 73 0a 2a 2a 20 64 65 66 69 6e 65 64 UG is.** defined
46be0 20 61 6e 64 20 69 66 20 4e 44 45 42 55 47 20 69 and if NDEBUG i
46bf0 73 20 6e 6f 74 20 64 65 66 69 6e 65 64 2e 0a 2a s not defined..*
46c00 2a 0a 2a 2a 20 7b 48 31 37 30 38 33 7d 20 54 68 *.** {H17083} Th
46c10 65 73 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f ese routines sho
46c20 75 6c 64 20 72 65 74 75 72 6e 20 74 72 75 65 20 uld return true
46c30 69 66 20 74 68 65 20 6d 75 74 65 78 20 69 6e 20 if the mutex in
46c40 74 68 65 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a their argument.*
46c50 2a 20 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74 * is held or not
46c60 20 68 65 6c 64 2c 20 72 65 73 70 65 63 74 69 76 held, respectiv
46c70 65 6c 79 2c 20 62 79 20 74 68 65 20 63 61 6c 6c ely, by the call
46c80 69 6e 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a ing thread..**.*
46c90 2a 20 7b 58 31 37 30 38 34 7d 20 54 68 65 20 69 * {X17084} The i
46ca0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 mplementation is
46cb0 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f not required to
46cc0 20 70 72 6f 76 69 64 65 64 20 76 65 72 73 69 6f provided versio
46cd0 6e 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 72 ns of these.** r
46ce0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 61 63 74 outines that act
46cf0 75 61 6c 6c 79 20 77 6f 72 6b 2e 20 49 66 20 74 ually work. If t
46d00 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
46d10 6e 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 n does not provi
46d20 64 65 20 77 6f 72 6b 69 6e 67 0a 2a 2a 20 76 65 de working.** ve
46d30 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 20 rsions of these
46d40 72 6f 75 74 69 6e 65 73 2c 20 69 74 20 73 68 6f routines, it sho
46d50 75 6c 64 20 61 74 20 6c 65 61 73 74 20 70 72 6f uld at least pro
46d60 76 69 64 65 20 73 74 75 62 73 20 74 68 61 74 20 vide stubs that
46d70 61 6c 77 61 79 73 0a 2a 2a 20 72 65 74 75 72 6e always.** return
46d80 20 74 72 75 65 20 73 6f 20 74 68 61 74 20 6f 6e true so that on
46d90 65 20 64 6f 65 73 20 6e 6f 74 20 67 65 74 20 73 e does not get s
46da0 70 75 72 69 6f 75 73 20 61 73 73 65 72 74 69 6f purious assertio
46db0 6e 20 66 61 69 6c 75 72 65 73 2e 0a 2a 2a 0a 2a n failures..**.*
46dc0 2a 20 7b 48 31 37 30 38 35 7d 20 49 66 20 74 68 * {H17085} If th
46dd0 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 e argument to sq
46de0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 lite3_mutex_held
46df0 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 () is a NULL poi
46e00 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65 nter then.** the
46e10 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 routine should
46e20 72 65 74 75 72 6e 20 31 2e 20 20 7b 45 4e 44 7d return 1. {END}
46e30 20 54 68 69 73 20 73 65 65 6d 73 20 63 6f 75 6e This seems coun
46e40 74 65 72 2d 69 6e 74 75 69 74 69 76 65 20 73 69 ter-intuitive si
46e50 6e 63 65 0a 2a 2a 20 63 6c 65 61 72 6c 79 20 74 nce.** clearly t
46e60 68 65 20 6d 75 74 65 78 20 63 61 6e 6e 6f 74 20 he mutex cannot
46e70 62 65 20 68 65 6c 64 20 69 66 20 69 74 20 64 6f be held if it do
46e80 65 73 20 6e 6f 74 20 65 78 69 73 74 2e 20 20 42 es not exist. B
46e90 75 74 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 65 ut the.** the re
46ea0 61 73 6f 6e 20 74 68 65 20 6d 75 74 65 78 20 64 ason the mutex d
46eb0 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20 69 73 oes not exist is
46ec0 20 62 65 63 61 75 73 65 20 74 68 65 20 62 75 69 because the bui
46ed0 6c 64 20 69 73 20 6e 6f 74 0a 2a 2a 20 75 73 69 ld is not.** usi
46ee0 6e 67 20 6d 75 74 65 78 65 73 2e 20 20 41 6e 64 ng mutexes. And
46ef0 20 77 65 20 64 6f 20 6e 6f 74 20 77 61 6e 74 20 we do not want
46f00 74 68 65 20 61 73 73 65 72 74 28 29 20 63 6f 6e the assert() con
46f10 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 taining the.** c
46f20 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d all to sqlite3_m
46f30 75 74 65 78 5f 68 65 6c 64 28 29 20 74 6f 20 66 utex_held() to f
46f40 61 69 6c 2c 20 73 6f 20 61 20 6e 6f 6e 2d 7a 65 ail, so a non-ze
46f50 72 6f 20 72 65 74 75 72 6e 20 69 73 0a 2a 2a 20 ro return is.**
46f60 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 the appropriate
46f70 74 68 69 6e 67 20 74 6f 20 64 6f 2e 20 20 7b 48 thing to do. {H
46f80 31 37 30 38 36 7d 20 54 68 65 20 73 71 6c 69 74 17086} The sqlit
46f90 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 e3_mutex_notheld
46fa0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 ().** interface
46fb0 73 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74 75 should also retu
46fc0 72 6e 20 31 20 77 68 65 6e 20 67 69 76 65 6e 20 rn 1 when given
46fd0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a a NULL pointer..
46fe0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d */.int sqlite3_m
46ff0 75 74 65 78 5f 68 65 6c 64 28 73 71 6c 69 74 65 utex_held(sqlite
47000 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73 3_mutex*);.int s
47010 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 qlite3_mutex_not
47020 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 held(sqlite3_mut
47030 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ex*);../*.** CAP
47040 49 33 52 45 46 3a 20 4d 75 74 65 78 20 54 79 70 I3REF: Mutex Typ
47050 65 73 20 7b 48 31 37 30 30 31 7d 20 3c 48 31 37 es {H17001} <H17
47060 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 000>.**.** The [
47070 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c sqlite3_mutex_al
47080 6c 6f 63 28 29 5d 20 69 6e 74 65 72 66 61 63 65 loc()] interface
47090 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
470a0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 69 63 argument.** whic
470b0 68 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 h is one of thes
470c0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 e integer consta
470d0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 nts..**.** The s
470e0 65 74 20 6f 66 20 73 74 61 74 69 63 20 6d 75 74 et of static mut
470f0 65 78 65 73 20 6d 61 79 20 63 68 61 6e 67 65 20 exes may change
47100 66 72 6f 6d 20 6f 6e 65 20 53 51 4c 69 74 65 20 from one SQLite
47110 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 0a 2a release to the.*
47120 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 * next. Applica
47130 74 69 6f 6e 73 20 74 68 61 74 20 6f 76 65 72 72 tions that overr
47140 69 64 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e ide the built-in
47150 20 6d 75 74 65 78 20 6c 6f 67 69 63 20 6d 75 73 mutex logic mus
47160 74 20 62 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 t be.** prepared
47170 20 74 6f 20 61 63 63 6f 6d 6d 6f 64 61 74 65 20 to accommodate
47180 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61 74 69 additional stati
47190 63 20 6d 75 74 65 78 65 73 2e 0a 2a 2f 0a 23 64 c mutexes..*/.#d
471a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 efine SQLITE_MUT
471b0 45 58 5f 46 41 53 54 20 20 20 20 20 20 20 20 20 EX_FAST
471c0 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 0.#define SQ
471d0 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 LITE_MUTEX_RECUR
471e0 53 49 56 45 20 20 20 20 20 20 20 20 31 0a 23 64 SIVE 1.#d
471f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 efine SQLITE_MUT
47200 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 EX_STATIC_MASTER
47210 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 2.#define SQ
47220 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 LITE_MUTEX_STATI
47230 43 5f 4d 45 4d 20 20 20 20 20 20 20 33 20 20 2f C_MEM 3 /
47240 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 * sqlite3_malloc
47250 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
47260 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 LITE_MUTEX_STATI
47270 43 5f 4d 45 4d 32 20 20 20 20 20 20 34 20 20 2f C_MEM2 4 /
47280 2a 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 * sqlite3_releas
47290 65 5f 6d 65 6d 6f 72 79 28 29 20 2a 2f 0a 23 64 e_memory() */.#d
472a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 efine SQLITE_MUT
472b0 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 20 20 EX_STATIC_PRNG
472c0 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 5 /* sqlite
472d0 33 5f 72 61 6e 64 6f 6d 28 29 20 2a 2f 0a 23 64 3_random() */.#d
472e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 efine SQLITE_MUT
472f0 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 20 20 20 EX_STATIC_LRU
47300 20 20 20 20 36 20 20 2f 2a 20 6c 72 75 20 70 61 6 /* lru pa
47310 67 65 20 6c 69 73 74 20 2a 2f 0a 23 64 65 66 69 ge list */.#defi
47320 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f ne SQLITE_MUTEX_
47330 53 54 41 54 49 43 5f 4c 52 55 32 20 20 20 20 20 STATIC_LRU2
47340 20 37 20 20 2f 2a 20 6c 72 75 20 70 61 67 65 20 7 /* lru page
47350 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 list */../*.** C
47360 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 API3REF: Retriev
47370 65 20 74 68 65 20 6d 75 74 65 78 20 66 6f 72 20 e the mutex for
47380 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 a database conne
47390 63 74 69 6f 6e 20 7b 48 31 37 30 30 32 7d 20 3c ction {H17002} <
473a0 48 31 37 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 H17000>.**.** Th
473b0 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 is interface ret
473c0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
473d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 he [sqlite3_mute
473e0 78 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 0a x] object that .
473f0 2a 2a 20 73 65 72 69 61 6c 69 7a 65 73 20 61 63 ** serializes ac
47400 63 65 73 73 20 74 6f 20 74 68 65 20 5b 64 61 74 cess to the [dat
47410 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
47420 5d 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 61 ] given in the a
47430 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 rgument.** when
47440 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d the [threading m
47450 6f 64 65 5d 20 69 73 20 53 65 72 69 61 6c 69 7a ode] is Serializ
47460 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 74 ed..** If the [t
47470 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 hreading mode] i
47480 73 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 s Single-thread
47490 6f 72 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 or Multi-thread
474a0 74 68 65 6e 20 74 68 69 73 0a 2a 2a 20 72 6f 75 then this.** rou
474b0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e tine returns a N
474c0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a ULL pointer..*/.
474d0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 73 sqlite3_mutex *s
474e0 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 28 qlite3_db_mutex(
474f0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a sqlite3*);../*.*
47500 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 77 2d * CAPI3REF: Low-
47510 4c 65 76 65 6c 20 43 6f 6e 74 72 6f 6c 20 4f 66 Level Control Of
47520 20 44 61 74 61 62 61 73 65 20 46 69 6c 65 73 20 Database Files
47530 7b 48 31 31 33 30 30 7d 20 3c 53 33 30 38 30 30 {H11300} <S30800
47540 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 31 7d >.**.** {H11301}
47550 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 The [sqlite3_fi
47560 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e le_control()] in
47570 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 terface makes a
47580 64 69 72 65 63 74 20 63 61 6c 6c 20 74 6f 20 74 direct call to t
47590 68 65 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 he.** xFileContr
475a0 6f 6c 20 6d 65 74 68 6f 64 20 66 6f 72 20 74 68 ol method for th
475b0 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 e [sqlite3_io_me
475c0 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 73 thods] object as
475d0 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 sociated.** with
475e0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 a particular da
475f0 74 61 62 61 73 65 20 69 64 65 6e 74 69 66 69 65 tabase identifie
47600 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 d by the second
47610 61 72 67 75 6d 65 6e 74 2e 20 7b 48 31 31 33 30 argument. {H1130
47620 32 7d 20 54 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 2} The.** name o
47630 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 f the database i
47640 73 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 s the name assig
47650 6e 65 64 20 74 6f 20 74 68 65 20 64 61 74 61 62 ned to the datab
47660 61 73 65 20 62 79 20 74 68 65 0a 2a 2a 20 3c 61 ase by the.** <a
47670 20 68 72 65 66 3d 22 6c 61 6e 67 5f 61 74 74 61 href="lang_atta
47680 63 68 2e 68 74 6d 6c 22 3e 41 54 54 41 43 48 3c ch.html">ATTACH<
47690 2f 61 3e 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 /a> SQL command
476a0 74 68 61 74 20 6f 70 65 6e 65 64 20 74 68 65 0a that opened the.
476b0 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 7b 48 31 ** database. {H1
476c0 31 33 30 33 7d 20 54 6f 20 63 6f 6e 74 72 6f 6c 1303} To control
476d0 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 the main databa
476e0 73 65 20 66 69 6c 65 2c 20 75 73 65 20 74 68 65 se file, use the
476f0 20 6e 61 6d 65 20 22 6d 61 69 6e 22 0a 2a 2a 20 name "main".**
47700 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 or a NULL pointe
47710 72 2e 20 7b 48 31 31 33 30 34 7d 20 54 68 65 20 r. {H11304} The
47720 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 third and fourth
47730 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 parameters to t
47740 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 61 his routine.** a
47750 72 65 20 70 61 73 73 65 64 20 64 69 72 65 63 74 re passed direct
47760 6c 79 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 ly through to th
47770 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 e second and thi
47780 72 64 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 rd parameters of
47790 0a 2a 2a 20 74 68 65 20 78 46 69 6c 65 43 6f 6e .** the xFileCon
477a0 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 20 7b 48 trol method. {H
477b0 31 31 33 30 35 7d 20 54 68 65 20 72 65 74 75 72 11305} The retur
477c0 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 78 n value of the x
477d0 46 69 6c 65 43 6f 6e 74 72 6f 6c 0a 2a 2a 20 6d FileControl.** m
477e0 65 74 68 6f 64 20 62 65 63 6f 6d 65 73 20 74 68 ethod becomes th
477f0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f e return value o
47800 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a f this routine..
47810 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 36 7d 20 49 **.** {H11306} I
47820 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 f the second par
47830 61 6d 65 74 65 72 20 28 7a 44 62 4e 61 6d 65 29 ameter (zDbName)
47840 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 does not match
47850 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 6e 79 0a the name of any.
47860 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 ** open database
47870 20 66 69 6c 65 2c 20 74 68 65 6e 20 53 51 4c 49 file, then SQLI
47880 54 45 5f 45 52 52 4f 52 20 69 73 20 72 65 74 75 TE_ERROR is retu
47890 72 6e 65 64 2e 20 7b 48 31 31 33 30 37 7d 20 54 rned. {H11307} T
478a0 68 69 73 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 his error.** cod
478b0 65 20 69 73 20 6e 6f 74 20 72 65 6d 65 6d 62 65 e is not remembe
478c0 72 65 64 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74 red and will not
478d0 20 62 65 20 72 65 63 61 6c 6c 65 64 20 62 79 20 be recalled by
478e0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 [sqlite3_errcode
478f0 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 ()].** or [sqlit
47900 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 20 7b 41 e3_errmsg()]. {A
47910 31 31 33 30 38 7d 20 54 68 65 20 75 6e 64 65 72 11308} The under
47920 6c 79 69 6e 67 20 78 46 69 6c 65 43 6f 6e 74 72 lying xFileContr
47930 6f 6c 20 6d 65 74 68 6f 64 20 6d 69 67 68 74 0a ol method might.
47940 2a 2a 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 53 ** also return S
47950 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 7b 41 QLITE_ERROR. {A
47960 31 31 33 30 39 7d 20 54 68 65 72 65 20 69 73 20 11309} There is
47970 6e 6f 20 77 61 79 20 74 6f 20 64 69 73 74 69 6e no way to distin
47980 67 75 69 73 68 20 62 65 74 77 65 65 6e 0a 2a 2a guish between.**
47990 20 61 6e 20 69 6e 63 6f 72 72 65 63 74 20 7a 44 an incorrect zD
479a0 62 4e 61 6d 65 20 61 6e 64 20 61 6e 20 53 51 4c bName and an SQL
479b0 49 54 45 5f 45 52 52 4f 52 20 72 65 74 75 72 6e ITE_ERROR return
479c0 20 66 72 6f 6d 20 74 68 65 20 75 6e 64 65 72 6c from the underl
479d0 79 69 6e 67 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e ying.** xFileCon
479e0 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 7b 45 4e trol method. {EN
479f0 44 7d 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 D}.**.** See als
47a00 6f 3a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c o: [SQLITE_FCNTL
47a10 5f 4c 4f 43 4b 53 54 41 54 45 5d 0a 2a 2f 0a 69 _LOCKSTATE].*/.i
47a20 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f nt sqlite3_file_
47a30 63 6f 6e 74 72 6f 6c 28 73 71 6c 69 74 65 33 2a control(sqlite3*
47a40 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 , const char *zD
47a50 62 4e 61 6d 65 2c 20 69 6e 74 20 6f 70 2c 20 76 bName, int op, v
47a60 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 oid*);../*.** CA
47a70 50 49 33 52 45 46 3a 20 54 65 73 74 69 6e 67 20 PI3REF: Testing
47a80 49 6e 74 65 72 66 61 63 65 20 7b 48 31 31 34 30 Interface {H1140
47a90 30 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 0} <S30800>.**.*
47aa0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 74 65 * The sqlite3_te
47ab0 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 20 69 6e 74 st_control() int
47ac0 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 erface is used t
47ad0 6f 20 72 65 61 64 20 6f 75 74 20 69 6e 74 65 72 o read out inter
47ae0 6e 61 6c 0a 2a 2a 20 73 74 61 74 65 20 6f 66 20 nal.** state of
47af0 53 51 4c 69 74 65 20 61 6e 64 20 74 6f 20 69 6e SQLite and to in
47b00 6a 65 63 74 20 66 61 75 6c 74 73 20 69 6e 74 6f ject faults into
47b10 20 53 51 4c 69 74 65 20 66 6f 72 20 74 65 73 74 SQLite for test
47b20 69 6e 67 0a 2a 2a 20 70 75 72 70 6f 73 65 73 2e ing.** purposes.
47b30 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 The first para
47b40 6d 65 74 65 72 20 69 73 20 61 6e 20 6f 70 65 72 meter is an oper
47b50 61 74 69 6f 6e 20 63 6f 64 65 20 74 68 61 74 20 ation code that
47b60 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 74 68 determines.** th
47b70 65 20 6e 75 6d 62 65 72 2c 20 6d 65 61 6e 69 6e e number, meanin
47b80 67 2c 20 61 6e 64 20 6f 70 65 72 61 74 69 6f 6e g, and operation
47b90 20 6f 66 20 61 6c 6c 20 73 75 62 73 65 71 75 65 of all subseque
47ba0 6e 74 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a nt parameters..*
47bb0 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 *.** This interf
47bc0 61 63 65 20 69 73 20 6e 6f 74 20 66 6f 72 20 75 ace is not for u
47bd0 73 65 20 62 79 20 61 70 70 6c 69 63 61 74 69 6f se by applicatio
47be0 6e 73 2e 20 20 49 74 20 65 78 69 73 74 73 20 73 ns. It exists s
47bf0 6f 6c 65 6c 79 0a 2a 2a 20 66 6f 72 20 76 65 72 olely.** for ver
47c00 69 66 79 69 6e 67 20 74 68 65 20 63 6f 72 72 65 ifying the corre
47c10 63 74 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 ct operation of
47c20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 the SQLite libra
47c30 72 79 2e 20 20 44 65 70 65 6e 64 69 6e 67 0a 2a ry. Depending.*
47c40 2a 20 6f 6e 20 68 6f 77 20 74 68 65 20 53 51 4c * on how the SQL
47c50 69 74 65 20 6c 69 62 72 61 72 79 20 69 73 20 63 ite library is c
47c60 6f 6d 70 69 6c 65 64 2c 20 74 68 69 73 20 69 6e ompiled, this in
47c70 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 6e 6f terface might no
47c80 74 20 65 78 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 54 t exist..**.** T
47c90 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 he details of th
47ca0 65 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 65 e operation code
47cb0 73 2c 20 74 68 65 69 72 20 6d 65 61 6e 69 6e 67 s, their meaning
47cc0 73 2c 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 s, the parameter
47cd0 73 0a 2a 2a 20 74 68 65 79 20 74 61 6b 65 2c 20 s.** they take,
47ce0 61 6e 64 20 77 68 61 74 20 74 68 65 79 20 64 6f and what they do
47cf0 20 61 72 65 20 61 6c 6c 20 73 75 62 6a 65 63 74 are all subject
47d00 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f to change witho
47d10 75 74 20 6e 6f 74 69 63 65 2e 0a 2a 2a 20 55 6e ut notice..** Un
47d20 6c 69 6b 65 20 6d 6f 73 74 20 6f 66 20 74 68 65 like most of the
47d30 20 53 51 4c 69 74 65 20 41 50 49 2c 20 74 68 69 SQLite API, thi
47d40 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f s function is no
47d50 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 0a t guaranteed to.
47d60 2a 2a 20 6f 70 65 72 61 74 65 20 63 6f 6e 73 69 ** operate consi
47d70 73 74 65 6e 74 6c 79 20 66 72 6f 6d 20 6f 6e 65 stently from one
47d80 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 release to the
47d90 6e 65 78 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c next..*/.int sql
47da0 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f ite3_test_contro
47db0 6c 28 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a l(int op, ...);.
47dc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
47dd0 20 54 65 73 74 69 6e 67 20 49 6e 74 65 72 66 61 Testing Interfa
47de0 63 65 20 4f 70 65 72 61 74 69 6f 6e 20 43 6f 64 ce Operation Cod
47df0 65 73 20 7b 48 31 31 34 31 30 7d 20 3c 48 31 31 es {H11410} <H11
47e00 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 400>.**.** These
47e10 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 constants are t
47e20 68 65 20 76 61 6c 69 64 20 6f 70 65 72 61 74 69 he valid operati
47e30 6f 6e 20 63 6f 64 65 20 70 61 72 61 6d 65 74 65 on code paramete
47e40 72 73 20 75 73 65 64 0a 2a 2a 20 61 73 20 74 68 rs used.** as th
47e50 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
47e60 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 65 73 to [sqlite3_tes
47e70 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d 2e 0a 2a 2a t_control()]..**
47e80 0a 2a 2a 20 54 68 65 73 65 20 70 61 72 61 6d 65 .** These parame
47e90 74 65 72 73 20 61 6e 64 20 74 68 65 69 72 20 6d ters and their m
47ea0 65 61 6e 69 6e 67 73 20 61 72 65 20 73 75 62 6a eanings are subj
47eb0 65 63 74 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a ect to change.**
47ec0 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 2e without notice.
47ed0 20 20 54 68 65 73 65 20 76 61 6c 75 65 73 20 61 These values a
47ee0 72 65 20 66 6f 72 20 74 65 73 74 69 6e 67 20 70 re for testing p
47ef0 75 72 70 6f 73 65 73 20 6f 6e 6c 79 2e 0a 2a 2a urposes only..**
47f00 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 Applications sh
47f10 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 61 6e 79 ould not use any
47f20 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 of these parame
47f30 74 65 72 73 20 6f 72 20 74 68 65 0a 2a 2a 20 5b ters or the.** [
47f40 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e sqlite3_test_con
47f50 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 trol()] interfac
47f60 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 e..*/.#define SQ
47f70 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 50 52 LITE_TESTCTRL_PR
47f80 4e 47 5f 53 41 56 45 20 20 20 20 20 20 20 20 20 NG_SAVE
47f90 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 5.#define
47fa0 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c SQLITE_TESTCTRL
47fb0 5f 50 52 4e 47 5f 52 45 53 54 4f 52 45 20 20 20 _PRNG_RESTORE
47fc0 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 6.#def
47fd0 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 ine SQLITE_TESTC
47fe0 54 52 4c 5f 50 52 4e 47 5f 52 45 53 45 54 20 20 TRL_PRNG_RESET
47ff0 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 7.#
48000 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 define SQLITE_TE
48010 53 54 43 54 52 4c 5f 42 49 54 56 45 43 5f 54 45 STCTRL_BITVEC_TE
48020 53 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ST
48030 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 8.#define SQLITE
48040 5f 54 45 53 54 43 54 52 4c 5f 46 41 55 4c 54 5f _TESTCTRL_FAULT_
48050 49 4e 53 54 41 4c 4c 20 20 20 20 20 20 20 20 20 INSTALL
48060 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 9.#define SQL
48070 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 42 45 4e ITE_TESTCTRL_BEN
48080 49 47 4e 5f 4d 41 4c 4c 4f 43 5f 48 4f 4f 4b 53 IGN_MALLOC_HOOKS
48090 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 10../*.** C
480a0 41 50 49 33 52 45 46 3a 20 53 51 4c 69 74 65 20 API3REF: SQLite
480b0 52 75 6e 74 69 6d 65 20 53 74 61 74 75 73 20 7b Runtime Status {
480c0 48 31 37 32 30 30 7d 20 3c 53 36 30 32 30 30 3e H17200} <S60200>
480d0 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c .** EXPERIMENTAL
480e0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 .**.** This inte
480f0 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f rface is used to
48100 20 72 65 74 72 69 65 76 65 20 72 75 6e 74 69 6d retrieve runtim
48110 65 20 73 74 61 74 75 73 20 69 6e 66 6f 72 6d 61 e status informa
48120 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 74 68 tion.** about th
48130 65 20 70 72 65 66 6f 72 6d 61 6e 63 65 20 6f 66 e preformance of
48140 20 53 51 4c 69 74 65 2c 20 61 6e 64 20 6f 70 74 SQLite, and opt
48150 69 6f 6e 61 6c 6c 79 20 74 6f 20 72 65 73 65 74 ionally to reset
48160 20 76 61 72 69 6f 75 73 0a 2a 2a 20 68 69 67 68 various.** high
48170 77 61 74 65 72 20 6d 61 72 6b 73 2e 20 20 54 68 water marks. Th
48180 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
48190 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 is an integer c
481a0 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 ode for.** the s
481b0 70 65 63 69 66 69 63 20 70 61 72 61 6d 65 74 65 pecific paramete
481c0 72 20 74 6f 20 6d 65 61 73 75 72 65 2e 20 20 52 r to measure. R
481d0 65 63 6f 67 6e 69 7a 65 64 20 69 6e 74 65 67 65 ecognized intege
481e0 72 20 63 6f 64 65 73 0a 2a 2a 20 61 72 65 20 6f r codes.** are o
481f0 66 20 74 68 65 20 66 6f 72 6d 20 5b 53 51 4c 49 f the form [SQLI
48200 54 45 5f 53 54 41 54 55 53 5f 4d 45 4d 4f 52 59 TE_STATUS_MEMORY
48210 5f 55 53 45 44 20 7c 20 53 51 4c 49 54 45 5f 53 _USED | SQLITE_S
48220 54 41 54 55 53 5f 2e 2e 2e 5d 2e 0a 2a 2a 20 54 TATUS_...]..** T
48230 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 he current value
48240 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 of the paramete
48250 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6e r is returned in
48260 74 6f 20 2a 70 43 75 72 72 65 6e 74 2e 0a 2a 2a to *pCurrent..**
48270 20 54 68 65 20 68 69 67 68 65 73 74 20 72 65 63 The highest rec
48280 6f 72 64 65 64 20 76 61 6c 75 65 20 69 73 20 72 orded value is r
48290 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 48 69 67 eturned in *pHig
482a0 68 77 61 74 65 72 2e 20 20 49 66 20 74 68 65 0a hwater. If the.
482b0 2a 2a 20 72 65 73 65 74 46 6c 61 67 20 69 73 20 ** resetFlag is
482c0 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 68 true, then the h
482d0 69 67 68 65 73 74 20 72 65 63 6f 72 64 20 76 61 ighest record va
482e0 6c 75 65 20 69 73 20 72 65 73 65 74 20 61 66 74 lue is reset aft
482f0 65 72 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74 65 er.** *pHighwate
48300 72 20 69 73 20 77 72 69 74 74 65 6e 2e 20 53 6f r is written. So
48310 6d 65 20 70 61 72 61 6d 65 74 65 72 73 20 64 6f me parameters do
48320 20 6e 6f 74 20 72 65 63 6f 72 64 20 74 68 65 20 not record the
48330 68 69 67 68 65 73 74 0a 2a 2a 20 76 61 6c 75 65 highest.** value
48340 2e 20 20 46 6f 72 20 74 68 6f 73 65 20 70 61 72 . For those par
48350 61 6d 65 74 65 72 73 0a 2a 2a 20 6e 6f 74 68 69 ameters.** nothi
48360 6e 67 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e ng is written in
48370 74 6f 20 2a 70 48 69 67 68 77 61 74 65 72 20 61 to *pHighwater a
48380 6e 64 20 74 68 65 20 72 65 73 65 74 46 6c 61 67 nd the resetFlag
48390 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 20 is ignored..**
483a0 4f 74 68 65 72 20 70 61 72 61 6d 65 74 65 72 73 Other parameters
483b0 20 72 65 63 6f 72 64 20 6f 6e 6c 79 20 74 68 65 record only the
483c0 20 68 69 67 68 77 61 74 65 72 20 6d 61 72 6b 20 highwater mark
483d0 61 6e 64 20 6e 6f 74 20 74 68 65 20 63 75 72 72 and not the curr
483e0 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 2e 20 20 46 ent.** value. F
483f0 6f 72 20 74 68 65 73 65 20 6c 61 74 74 65 72 20 or these latter
48400 70 61 72 61 6d 65 74 65 72 73 20 6e 6f 74 68 69 parameters nothi
48410 6e 67 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e ng is written in
48420 74 6f 20 2a 70 43 75 72 72 65 6e 74 2e 0a 2a 2a to *pCurrent..**
48430 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
48440 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f returns SQLITE_
48450 4f 4b 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e OK on success an
48460 64 20 61 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 d a non-zero.**
48470 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e 20 [error code] on
48480 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 failure..**.** T
48490 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 his routine is t
484a0 68 72 65 61 64 73 61 66 65 20 62 75 74 20 69 73 hreadsafe but is
484b0 20 6e 6f 74 20 61 74 6f 6d 69 63 2e 20 20 54 68 not atomic. Th
484c0 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 0a 2a is routine can.*
484d0 2a 20 63 61 6c 6c 65 64 20 77 68 69 6c 65 20 6f * called while o
484e0 74 68 65 72 20 74 68 72 65 61 64 73 20 61 72 65 ther threads are
484f0 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 73 61 6d running the sam
48500 65 20 6f 72 20 64 69 66 66 65 72 65 6e 74 20 53 e or different S
48510 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 66 61 QLite.** interfa
48520 63 65 73 2e 20 20 48 6f 77 65 76 65 72 20 74 68 ces. However th
48530 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 e values returne
48540 64 20 69 6e 20 2a 70 43 75 72 72 65 6e 74 20 61 d in *pCurrent a
48550 6e 64 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74 65 nd.** *pHighwate
48560 72 20 72 65 66 6c 65 63 74 20 74 68 65 20 73 74 r reflect the st
48570 61 74 75 73 20 6f 66 20 53 51 4c 69 74 65 20 61 atus of SQLite a
48580 74 20 64 69 66 66 65 72 65 6e 74 20 70 6f 69 6e t different poin
48590 74 73 20 69 6e 20 74 69 6d 65 0a 2a 2a 20 61 6e ts in time.** an
485a0 64 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 d it is possible
485b0 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 that another th
485c0 72 65 61 64 20 6d 69 67 68 74 20 63 68 61 6e 67 read might chang
485d0 65 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a e the parameter.
485e0 2a 2a 20 69 6e 20 62 65 74 77 65 65 6e 20 74 68 ** in between th
485f0 65 20 74 69 6d 65 73 20 77 68 65 6e 20 2a 70 43 e times when *pC
48600 75 72 72 65 6e 74 20 61 6e 64 20 2a 70 48 69 67 urrent and *pHig
48610 68 77 61 74 65 72 20 61 72 65 20 77 72 69 74 74 hwater are writt
48620 65 6e 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c en..**.** See al
48630 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f so: [sqlite3_db_
48640 73 74 61 74 75 73 28 29 5d 0a 2a 2f 0a 53 51 4c status()].*/.SQL
48650 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c ITE_EXPERIMENTAL
48660 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 61 int sqlite3_sta
48670 74 75 73 28 69 6e 74 20 6f 70 2c 20 69 6e 74 20 tus(int op, int
48680 2a 70 43 75 72 72 65 6e 74 2c 20 69 6e 74 20 2a *pCurrent, int *
48690 70 48 69 67 68 77 61 74 65 72 2c 20 69 6e 74 20 pHighwater, int
486a0 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 0a 2f 2a resetFlag);.../*
486b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 .** CAPI3REF: St
486c0 61 74 75 73 20 50 61 72 61 6d 65 74 65 72 73 20 atus Parameters
486d0 7b 48 31 37 32 35 30 7d 20 3c 48 31 37 32 30 30 {H17250} <H17200
486e0 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 >.** EXPERIMENTA
486f0 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e L.**.** These in
48700 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 teger constants
48710 64 65 73 69 67 6e 61 74 65 20 76 61 72 69 6f 75 designate variou
48720 73 20 72 75 6e 2d 74 69 6d 65 20 73 74 61 74 75 s run-time statu
48730 73 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 s parameters.**
48740 74 68 61 74 20 63 61 6e 20 62 65 20 72 65 74 75 that can be retu
48750 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 rned by [sqlite3
48760 5f 73 74 61 74 75 73 28 29 5d 2e 0a 2a 2a 0a 2a _status()]..**.*
48770 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 * <dl>.** <dt>SQ
48780 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 45 4d 4f LITE_STATUS_MEMO
48790 52 59 5f 55 53 45 44 3c 2f 64 74 3e 0a 2a 2a 20 RY_USED</dt>.**
487a0 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 <dd>This paramet
487b0 65 72 20 69 73 20 74 68 65 20 63 75 72 72 65 6e er is the curren
487c0 74 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f t amount of memo
487d0 72 79 20 63 68 65 63 6b 65 64 20 6f 75 74 0a 2a ry checked out.*
487e0 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 * using [sqlite3
487f0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 65 69 74 68 _malloc()], eith
48800 65 72 20 64 69 72 65 63 74 6c 79 20 6f 72 20 69 er directly or i
48810 6e 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 0a ndirectly. The.
48820 2a 2a 20 66 69 67 75 72 65 20 69 6e 63 6c 75 64 ** figure includ
48830 65 73 20 63 61 6c 6c 73 20 6d 61 64 65 20 74 6f es calls made to
48840 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
48850 28 29 5d 20 62 79 20 74 68 65 20 61 70 70 6c 69 ()] by the appli
48860 63 61 74 69 6f 6e 0a 2a 2a 20 61 6e 64 20 69 6e cation.** and in
48870 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 75 73 ternal memory us
48880 61 67 65 20 62 79 20 74 68 65 20 53 51 4c 69 74 age by the SQLit
48890 65 20 6c 69 62 72 61 72 79 2e 20 20 53 63 72 61 e library. Scra
488a0 74 63 68 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f tch memory.** co
488b0 6e 74 72 6f 6c 6c 65 64 20 62 79 20 5b 53 51 4c ntrolled by [SQL
488c0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 ITE_CONFIG_SCRAT
488d0 43 48 5d 20 61 6e 64 20 61 75 78 69 6c 69 61 72 CH] and auxiliar
488e0 79 20 70 61 67 65 2d 63 61 63 68 65 0a 2a 2a 20 y page-cache.**
488f0 6d 65 6d 6f 72 79 20 63 6f 6e 74 72 6f 6c 6c 65 memory controlle
48900 64 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e d by [SQLITE_CON
48910 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 20 69 FIG_PAGECACHE] i
48920 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 s not included i
48930 6e 0a 2a 2a 20 74 68 69 73 20 70 61 72 61 6d 65 n.** this parame
48940 74 65 72 2e 20 20 54 68 65 20 61 6d 6f 75 6e 74 ter. The amount
48950 20 72 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 returned is the
48960 20 73 75 6d 20 6f 66 20 74 68 65 20 61 6c 6c 6f sum of the allo
48970 63 61 74 69 6f 6e 0a 2a 2a 20 73 69 7a 65 73 20 cation.** sizes
48980 61 73 20 72 65 70 6f 72 74 65 64 20 62 79 20 74 as reported by t
48990 68 65 20 78 53 69 7a 65 20 6d 65 74 68 6f 64 20 he xSize method
489a0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f in [sqlite3_mem_
489b0 6d 65 74 68 6f 64 73 5d 2e 3c 2f 64 64 3e 0a 2a methods].</dd>.*
489c0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
489d0 53 54 41 54 55 53 5f 4d 41 4c 4c 4f 43 5f 53 49 STATUS_MALLOC_SI
489e0 5a 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 ZE</dt>.** <dd>T
489f0 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 his parameter re
48a00 63 6f 72 64 73 20 74 68 65 20 6c 61 72 67 65 73 cords the larges
48a10 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 t memory allocat
48a20 69 6f 6e 20 72 65 71 75 65 73 74 0a 2a 2a 20 68 ion request.** h
48a30 61 6e 64 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 anded to [sqlite
48a40 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 3_malloc()] or [
48a50 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
48a60 29 5d 20 28 6f 72 20 74 68 65 69 72 0a 2a 2a 20 )] (or their.**
48a70 69 6e 74 65 72 6e 61 6c 20 65 71 75 69 76 61 6c internal equival
48a80 65 6e 74 73 29 2e 20 20 4f 6e 6c 79 20 74 68 65 ents). Only the
48a90 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
48aa0 69 6e 20 74 68 65 0a 2a 2a 20 2a 70 48 69 67 68 in the.** *pHigh
48ab0 77 61 74 65 72 20 70 61 72 61 6d 65 74 65 72 20 water parameter
48ac0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 to [sqlite3_stat
48ad0 75 73 28 29 5d 20 69 73 20 6f 66 20 69 6e 74 65 us()] is of inte
48ae0 72 65 73 74 2e 20 20 0a 2a 2a 20 54 68 65 20 76 rest. .** The v
48af0 61 6c 75 65 20 77 72 69 74 74 65 6e 20 69 6e 74 alue written int
48b00 6f 20 74 68 65 20 2a 70 43 75 72 72 65 6e 74 20 o the *pCurrent
48b10 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 6e 64 parameter is und
48b20 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a efined.</dd>.**.
48b30 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 ** <dt>SQLITE_ST
48b40 41 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f 55 ATUS_PAGECACHE_U
48b50 53 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e SED</dt>.** <dd>
48b60 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 This parameter r
48b70 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
48b80 72 20 6f 66 20 70 61 67 65 73 20 75 73 65 64 20 r of pages used
48b90 6f 75 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 out of the.** [p
48ba0 61 67 65 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 agecache memory
48bb0 61 6c 6c 6f 63 61 74 6f 72 5d 20 74 68 61 74 20 allocator] that
48bc0 77 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 75 was configured u
48bd0 73 69 6e 67 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 sing .** [SQLITE
48be0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 _CONFIG_PAGECACH
48bf0 45 5d 2e 20 20 54 68 65 0a 2a 2a 20 76 61 6c 75 E]. The.** valu
48c00 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 69 6e e returned is in
48c10 20 70 61 67 65 73 2c 20 6e 6f 74 20 69 6e 20 62 pages, not in b
48c20 79 74 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ytes.</dd>.**.**
48c30 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 <dt>SQLITE_STAT
48c40 55 53 5f 50 41 47 45 43 41 43 48 45 5f 4f 56 45 US_PAGECACHE_OVE
48c50 52 46 4c 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 RFLOW</dt>.** <d
48c60 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 d>This parameter
48c70 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
48c80 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 ber of bytes of
48c90 70 61 67 65 20 63 61 63 68 65 0a 2a 2a 20 61 6c page cache.** al
48ca0 6c 6f 63 61 74 69 6f 6e 20 77 68 69 63 68 20 63 location which c
48cb0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 73 74 61 74 ould not be stat
48cc0 69 73 66 69 65 64 20 62 79 20 74 68 65 20 5b 53 isfied by the [S
48cd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 QLITE_CONFIG_PAG
48ce0 45 43 41 43 48 45 5d 0a 2a 2a 20 62 75 66 66 65 ECACHE].** buffe
48cf0 72 20 61 6e 64 20 77 68 65 72 65 20 66 6f 72 63 r and where forc
48d00 65 64 20 74 6f 20 6f 76 65 72 66 6c 6f 77 20 74 ed to overflow t
48d10 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f o [sqlite3_mallo
48d20 63 28 29 5d 2e 20 20 54 68 65 0a 2a 2a 20 72 65 c()]. The.** re
48d30 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 6e 63 turned value inc
48d40 6c 75 64 65 73 20 61 6c 6c 6f 63 61 74 69 6f 6e ludes allocation
48d50 73 20 74 68 61 74 20 6f 76 65 72 66 6c 6f 77 65 s that overflowe
48d60 64 20 62 65 63 61 75 73 65 20 74 68 65 79 0a 2a d because they.*
48d70 2a 20 77 68 65 72 65 20 74 6f 6f 20 6c 61 72 67 * where too larg
48d80 65 20 28 74 68 65 79 20 77 65 72 65 20 6c 61 72 e (they were lar
48d90 67 65 72 20 74 68 61 6e 20 74 68 65 20 22 73 7a ger than the "sz
48da0 22 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a " parameter to.*
48db0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 * [SQLITE_CONFIG
48dc0 5f 50 41 47 45 43 41 43 48 45 5d 29 20 61 6e 64 _PAGECACHE]) and
48dd0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 74 68 61 allocations tha
48de0 74 20 6f 76 65 72 66 6c 6f 77 65 64 20 62 65 63 t overflowed bec
48df0 61 75 73 65 0a 2a 2a 20 6e 6f 20 73 70 61 63 65 ause.** no space
48e00 20 77 61 73 20 6c 65 66 74 20 69 6e 20 74 68 65 was left in the
48e10 20 70 61 67 65 20 63 61 63 68 65 2e 3c 2f 64 64 page cache.</dd
48e20 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
48e30 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45 43 41 TE_STATUS_PAGECA
48e40 43 48 45 5f 53 49 5a 45 3c 2f 64 74 3e 0a 2a 2a CHE_SIZE</dt>.**
48e50 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 <dd>This parame
48e60 74 65 72 20 72 65 63 6f 72 64 73 20 74 68 65 20 ter records the
48e70 6c 61 72 67 65 73 74 20 6d 65 6d 6f 72 79 20 61 largest memory a
48e80 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 llocation reques
48e90 74 0a 2a 2a 20 68 61 6e 64 65 64 20 74 6f 20 5b t.** handed to [
48ea0 70 61 67 65 63 61 63 68 65 20 6d 65 6d 6f 72 79 pagecache memory
48eb0 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e 20 20 4f 6e allocator]. On
48ec0 6c 79 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 ly the value ret
48ed0 75 72 6e 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 urned in the.**
48ee0 2a 70 48 69 67 68 77 61 74 65 72 20 70 61 72 61 *pHighwater para
48ef0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 meter to [sqlite
48f00 33 5f 73 74 61 74 75 73 28 29 5d 20 69 73 20 6f 3_status()] is o
48f10 66 20 69 6e 74 65 72 65 73 74 2e 20 20 0a 2a 2a f interest. .**
48f20 20 54 68 65 20 76 61 6c 75 65 20 77 72 69 74 74 The value writt
48f30 65 6e 20 69 6e 74 6f 20 74 68 65 20 2a 70 43 75 en into the *pCu
48f40 72 72 65 6e 74 20 70 61 72 61 6d 65 74 65 72 20 rrent parameter
48f50 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 is undefined.</d
48f60 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
48f70 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54 ITE_STATUS_SCRAT
48f80 43 48 5f 55 53 45 44 3c 2f 64 74 3e 0a 2a 2a 20 CH_USED</dt>.**
48f90 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 <dd>This paramet
48fa0 65 72 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e er returns the n
48fb0 75 6d 62 65 72 20 6f 66 20 61 6c 6c 6f 63 61 74 umber of allocat
48fc0 69 6f 6e 73 20 75 73 65 64 20 6f 75 74 20 6f 66 ions used out of
48fd0 20 74 68 65 0a 2a 2a 20 5b 73 63 72 61 74 63 68 the.** [scratch
48fe0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
48ff0 72 5d 20 63 6f 6e 66 69 67 75 72 65 64 20 75 73 r] configured us
49000 69 6e 67 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 ing.** [SQLITE_C
49010 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 2e 20 ONFIG_SCRATCH].
49020 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 The value retur
49030 6e 65 64 20 69 73 20 69 6e 20 61 6c 6c 6f 63 61 ned is in alloca
49040 74 69 6f 6e 73 2c 20 6e 6f 74 0a 2a 2a 20 69 6e tions, not.** in
49050 20 62 79 74 65 73 2e 20 20 53 69 6e 63 65 20 61 bytes. Since a
49060 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 20 6d single thread m
49070 61 79 20 6f 6e 6c 79 20 68 61 76 65 20 6f 6e 65 ay only have one
49080 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 scratch allocat
49090 69 6f 6e 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 ion.** outstandi
490a0 6e 67 20 61 74 20 74 69 6d 65 2c 20 74 68 69 73 ng at time, this
490b0 20 70 61 72 61 6d 65 74 65 72 20 61 6c 73 6f 20 parameter also
490c0 72 65 70 6f 72 74 73 20 74 68 65 20 6e 75 6d 62 reports the numb
490d0 65 72 20 6f 66 20 74 68 72 65 61 64 73 0a 2a 2a er of threads.**
490e0 20 75 73 69 6e 67 20 73 63 72 61 74 63 68 20 6d using scratch m
490f0 65 6d 6f 72 79 20 61 74 20 74 68 65 20 73 61 6d emory at the sam
49100 65 20 74 69 6d 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a e time.</dd>.**.
49110 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 ** <dt>SQLITE_ST
49120 41 54 55 53 5f 53 43 52 41 54 43 48 5f 4f 56 45 ATUS_SCRATCH_OVE
49130 52 46 4c 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 RFLOW</dt>.** <d
49140 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 d>This parameter
49150 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
49160 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 ber of bytes of
49170 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 0a 2a scratch memory.*
49180 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 77 68 69 * allocation whi
49190 63 68 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 ch could not be
491a0 73 74 61 74 69 73 66 69 65 64 20 62 79 20 74 68 statisfied by th
491b0 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 e [SQLITE_CONFIG
491c0 5f 53 43 52 41 54 43 48 5d 0a 2a 2a 20 62 75 66 _SCRATCH].** buf
491d0 66 65 72 20 61 6e 64 20 77 68 65 72 65 20 66 6f fer and where fo
491e0 72 63 65 64 20 74 6f 20 6f 76 65 72 66 6c 6f 77 rced to overflow
491f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c to [sqlite3_mal
49200 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 76 61 6c loc()]. The val
49210 75 65 73 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 ues.** returned
49220 69 6e 63 6c 75 64 65 20 6f 76 65 72 66 6c 6f 77 include overflow
49230 73 20 62 65 63 61 75 73 65 20 74 68 65 20 72 65 s because the re
49240 71 75 65 73 74 65 64 20 61 6c 6c 6f 63 61 74 69 quested allocati
49250 6f 6e 20 77 61 73 20 74 6f 6f 0a 2a 2a 20 6c 61 on was too.** la
49260 72 67 65 72 20 28 74 68 61 74 20 69 73 2c 20 62 rger (that is, b
49270 65 63 61 75 73 65 20 74 68 65 20 72 65 71 75 65 ecause the reque
49280 73 74 65 64 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 sted allocation
49290 77 61 73 20 6c 61 72 67 65 72 20 74 68 61 6e 20 was larger than
492a0 74 68 65 0a 2a 2a 20 22 73 7a 22 20 70 61 72 61 the.** "sz" para
492b0 6d 65 74 65 72 20 74 6f 20 5b 53 51 4c 49 54 45 meter to [SQLITE
492c0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d _CONFIG_SCRATCH]
492d0 29 20 61 6e 64 20 62 65 63 61 75 73 65 20 6e 6f ) and because no
492e0 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 0a scratch buffer.
492f0 2a 2a 20 73 6c 6f 74 73 20 77 65 72 65 20 61 76 ** slots were av
49300 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 3c 2f 64 64 ailable..** </dd
49310 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
49320 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54 43 TE_STATUS_SCRATC
49330 48 5f 53 49 5a 45 3c 2f 64 74 3e 0a 2a 2a 20 3c H_SIZE</dt>.** <
49340 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 dd>This paramete
49350 72 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c 61 r records the la
49360 72 67 65 73 74 20 6d 65 6d 6f 72 79 20 61 6c 6c rgest memory all
49370 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 0a ocation request.
49380 2a 2a 20 68 61 6e 64 65 64 20 74 6f 20 5b 73 63 ** handed to [sc
49390 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 6c 6c ratch memory all
493a0 6f 63 61 74 6f 72 5d 2e 20 20 4f 6e 6c 79 20 74 ocator]. Only t
493b0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
493c0 64 20 69 6e 20 74 68 65 0a 2a 2a 20 2a 70 48 69 d in the.** *pHi
493d0 67 68 77 61 74 65 72 20 70 61 72 61 6d 65 74 65 ghwater paramete
493e0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 r to [sqlite3_st
493f0 61 74 75 73 28 29 5d 20 69 73 20 6f 66 20 69 6e atus()] is of in
49400 74 65 72 65 73 74 2e 20 20 0a 2a 2a 20 54 68 65 terest. .** The
49410 20 76 61 6c 75 65 20 77 72 69 74 74 65 6e 20 69 value written i
49420 6e 74 6f 20 74 68 65 20 2a 70 43 75 72 72 65 6e nto the *pCurren
49430 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 t parameter is u
49440 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a ndefined.</dd>.*
49450 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
49460 53 54 41 54 55 53 5f 50 41 52 53 45 52 5f 53 54 STATUS_PARSER_ST
49470 41 43 4b 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ACK</dt>.** <dd>
49480 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 This parameter r
49490 65 63 6f 72 64 73 20 74 68 65 20 64 65 65 70 65 ecords the deepe
494a0 73 74 20 70 61 72 73 65 72 20 73 74 61 63 6b 2e st parser stack.
494b0 20 20 49 74 20 69 73 20 6f 6e 6c 79 0a 2a 2a 20 It is only.**
494c0 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 53 51 meaningful if SQ
494d0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
494e0 20 77 69 74 68 20 5b 59 59 54 52 41 43 4b 4d 41 with [YYTRACKMA
494f0 58 53 54 41 43 4b 44 45 50 54 48 5d 2e 3c 2f 64 XSTACKDEPTH].</d
49500 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a d>.** </dl>.**.*
49510 2a 20 4e 65 77 20 73 74 61 74 75 73 20 70 61 72 * New status par
49520 61 6d 65 74 65 72 73 20 6d 61 79 20 62 65 20 61 ameters may be a
49530 64 64 65 64 20 66 72 6f 6d 20 74 69 6d 65 20 74 dded from time t
49540 6f 20 74 69 6d 65 2e 0a 2a 2f 0a 23 64 65 66 69 o time..*/.#defi
49550 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 ne SQLITE_STATUS
49560 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 20 20 20 20 _MEMORY_USED
49570 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 0.#define
49580 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 SQLITE_STATUS_PA
49590 47 45 43 41 43 48 45 5f 55 53 45 44 20 20 20 20 GECACHE_USED
495a0 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 1.#define SQL
495b0 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45 43 ITE_STATUS_PAGEC
495c0 41 43 48 45 5f 4f 56 45 52 46 4c 4f 57 20 20 20 ACHE_OVERFLOW
495d0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
495e0 5f 53 54 41 54 55 53 5f 53 43 52 41 54 43 48 5f _STATUS_SCRATCH_
495f0 55 53 45 44 20 20 20 20 20 20 20 20 20 33 0a 23 USED 3.#
49600 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 define SQLITE_ST
49610 41 54 55 53 5f 53 43 52 41 54 43 48 5f 4f 56 45 ATUS_SCRATCH_OVE
49620 52 46 4c 4f 57 20 20 20 20 20 34 0a 23 64 65 66 RFLOW 4.#def
49630 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 ine SQLITE_STATU
49640 53 5f 4d 41 4c 4c 4f 43 5f 53 49 5a 45 20 20 20 S_MALLOC_SIZE
49650 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 5.#define
49660 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 SQLITE_STATUS_P
49670 41 52 53 45 52 5f 53 54 41 43 4b 20 20 20 20 20 ARSER_STACK
49680 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 6.#define SQ
49690 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45 LITE_STATUS_PAGE
496a0 43 41 43 48 45 5f 53 49 5a 45 20 20 20 20 20 20 CACHE_SIZE
496b0 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 7.#define SQLIT
496c0 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54 43 48 E_STATUS_SCRATCH
496d0 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 38 0a _SIZE 8.
496e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
496f0 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 Database Connec
49700 74 69 6f 6e 20 53 74 61 74 75 73 20 7b 48 31 37 tion Status {H17
49710 35 30 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 500} <S60200>.**
49720 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a EXPERIMENTAL.**
49730 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 .** This interfa
49740 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 ce is used to re
49750 74 72 69 65 76 65 20 72 75 6e 74 69 6d 65 20 73 trieve runtime s
49760 74 61 74 75 73 20 69 6e 66 6f 72 6d 61 74 69 6f tatus informatio
49770 6e 20 0a 2a 2a 20 61 62 6f 75 74 20 61 20 73 69 n .** about a si
49780 6e 67 6c 65 20 5b 64 61 74 61 62 61 73 65 20 63 ngle [database c
49790 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 onnection]. The
497a0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
497b0 69 73 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 is the.** databa
497c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 62 se connection ob
497d0 6a 65 63 74 20 74 6f 20 62 65 20 69 6e 74 65 72 ject to be inter
497e0 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 73 65 rogated. The se
497f0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a cond argument.**
49800 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 is the paramete
49810 72 20 74 6f 20 69 6e 74 65 72 72 6f 67 61 74 65 r to interrogate
49820 2e 20 20 43 75 72 72 65 6e 74 6c 79 2c 20 74 68 . Currently, th
49830 65 20 6f 6e 6c 79 20 61 6c 6c 6f 77 65 64 20 76 e only allowed v
49840 61 6c 75 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 alue.** for the
49850 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
49860 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 42 53 54 is [SQLITE_DBST
49870 41 54 55 53 5f 4c 4f 4f 4b 41 53 49 44 45 5f 55 ATUS_LOOKASIDE_U
49880 53 45 44 5d 2e 0a 2a 2a 20 41 64 64 69 74 69 6f SED]..** Additio
49890 6e 61 6c 20 6f 70 74 69 6f 6e 73 20 77 69 6c 6c nal options will
498a0 20 6c 69 6b 65 6c 79 20 61 70 70 65 61 72 20 69 likely appear i
498b0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
498c0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a s of SQLite..**.
498d0 2a 2a 20 54 68 65 20 63 75 72 72 65 6e 74 20 76 ** The current v
498e0 61 6c 75 65 20 6f 66 20 74 68 65 20 72 65 71 75 alue of the requ
498f0 65 73 74 65 64 20 70 61 72 61 6d 65 74 65 72 20 ested parameter
49900 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 is written into
49910 2a 70 43 75 72 0a 2a 2a 20 61 6e 64 20 74 68 65 *pCur.** and the
49920 20 68 69 67 68 65 73 74 20 69 6e 73 74 61 6e 74 highest instant
49930 61 6e 65 6f 75 73 20 76 61 6c 75 65 20 69 73 20 aneous value is
49940 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 48 written into *pH
49950 69 77 74 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 iwtr. If.** the
49960 20 72 65 73 65 74 46 6c 67 20 69 73 20 74 72 75 resetFlg is tru
49970 65 2c 20 74 68 65 6e 20 74 68 65 20 68 69 67 68 e, then the high
49980 65 73 74 20 69 6e 73 74 61 6e 74 61 6e 65 6f 75 est instantaneou
49990 73 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 72 65 s value is.** re
499a0 73 65 74 20 62 61 63 6b 20 64 6f 77 6e 20 74 6f set back down to
499b0 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c the current val
499c0 75 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c ue..**.** See al
499d0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 so: [sqlite3_sta
499e0 74 75 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 tus()] and [sqli
499f0 74 65 33 5f 73 74 6d 74 5f 73 74 61 74 75 73 28 te3_stmt_status(
49a00 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 )]..*/.SQLITE_EX
49a10 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 PERIMENTAL int s
49a20 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 qlite3_db_status
49a30 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f (sqlite3*, int o
49a40 70 2c 20 69 6e 74 20 2a 70 43 75 72 2c 20 69 6e p, int *pCur, in
49a50 74 20 2a 70 48 69 77 74 72 2c 20 69 6e 74 20 72 t *pHiwtr, int r
49a60 65 73 65 74 46 6c 67 29 3b 0a 0a 2f 2a 0a 2a 2a esetFlg);../*.**
49a70 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 74 75 CAPI3REF: Statu
49a80 73 20 50 61 72 61 6d 65 74 65 72 73 20 66 6f 72 s Parameters for
49a90 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
49aa0 74 69 6f 6e 73 20 7b 48 31 37 35 32 30 7d 20 3c tions {H17520} <
49ab0 48 31 37 35 30 30 3e 0a 2a 2a 20 45 58 50 45 52 H17500>.** EXPER
49ac0 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 53 74 IMENTAL.**.** St
49ad0 61 74 75 73 20 76 65 72 62 73 20 66 6f 72 20 5b atus verbs for [
49ae0 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 sqlite3_db_statu
49af0 73 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e s()]..**.** <dl>
49b00 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 .** <dt>SQLITE_D
49b10 42 53 54 41 54 55 53 5f 4c 4f 4f 4b 41 53 49 44 BSTATUS_LOOKASID
49b20 45 5f 55 53 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c E_USED</dt>.** <
49b30 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 dd>This paramete
49b40 72 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 r returns the nu
49b50 6d 62 65 72 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 mber of lookasid
49b60 65 20 6d 65 6d 6f 72 79 20 73 6c 6f 74 73 20 63 e memory slots c
49b70 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 63 68 65 63 urrently.** chec
49b80 6b 65 64 20 6f 75 74 2e 3c 2f 64 64 3e 0a 2a 2a ked out.</dd>.**
49b90 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e </dl>.*/.#defin
49ba0 65 20 53 51 4c 49 54 45 5f 44 42 53 54 41 54 55 e SQLITE_DBSTATU
49bb0 53 5f 4c 4f 4f 4b 41 53 49 44 45 5f 55 53 45 44 S_LOOKASIDE_USED
49bc0 20 20 20 20 20 30 0a 0a 0a 2f 2a 0a 2a 2a 20 43 0.../*.** C
49bd0 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 65 API3REF: Prepare
49be0 64 20 53 74 61 74 65 6d 65 6e 74 20 53 74 61 74 d Statement Stat
49bf0 75 73 20 7b 48 31 37 35 35 30 7d 20 3c 53 36 30 us {H17550} <S60
49c00 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 200>.** EXPERIME
49c10 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 NTAL.**.** Each
49c20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
49c30 6e 74 20 6d 61 69 6e 74 61 69 6e 73 20 76 61 72 nt maintains var
49c40 69 6f 75 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ious.** [SQLITE_
49c50 53 54 4d 54 53 54 41 54 55 53 5f 53 4f 52 54 20 STMTSTATUS_SORT
49c60 7c 20 63 6f 75 6e 74 65 72 73 5d 20 74 68 61 74 | counters] that
49c70 20 6d 65 61 73 75 72 65 20 74 68 65 20 6e 75 6d measure the num
49c80 62 65 72 0a 2a 2a 20 6f 66 20 74 69 6d 65 73 20 ber.** of times
49c90 69 74 20 68 61 73 20 70 65 72 66 6f 72 6d 65 64 it has performed
49ca0 20 73 70 65 63 69 66 69 63 20 6f 70 65 72 61 74 specific operat
49cb0 69 6f 6e 73 2e 20 20 54 68 65 73 65 20 63 6f 75 ions. These cou
49cc0 6e 74 65 72 73 20 63 61 6e 0a 2a 2a 20 62 65 20 nters can.** be
49cd0 75 73 65 64 20 74 6f 20 6d 6f 6e 69 74 6f 72 20 used to monitor
49ce0 74 68 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 the performance
49cf0 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 characteristics
49d00 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 64 0a of the prepared.
49d10 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 ** statements.
49d20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 For example, if
49d30 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 61 the number of ta
49d40 62 6c 65 20 73 74 65 70 73 20 67 72 65 61 74 6c ble steps greatl
49d50 79 20 65 78 63 65 65 64 73 0a 2a 2a 20 74 68 65 y exceeds.** the
49d60 20 6e 75 6d 62 65 72 20 6f 66 20 74 61 62 6c 65 number of table
49d70 20 73 65 61 72 63 68 65 73 20 6f 72 20 72 65 73 searches or res
49d80 75 6c 74 20 72 6f 77 73 2c 20 74 68 61 74 20 77 ult rows, that w
49d90 6f 75 6c 64 20 74 65 6e 64 20 74 6f 20 69 6e 64 ould tend to ind
49da0 69 63 61 74 65 0a 2a 2a 20 74 68 61 74 20 74 68 icate.** that th
49db0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 e prepared state
49dc0 6d 65 6e 74 20 69 73 20 75 73 69 6e 67 20 61 20 ment is using a
49dd0 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 20 full table scan
49de0 72 61 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 61 rather than.** a
49df0 6e 20 69 6e 64 65 78 2e 20 20 0a 2a 2a 0a 2a 2a n index. .**.**
49e00 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 This interface
49e10 69 73 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 is used to retri
49e20 65 76 65 20 61 6e 64 20 72 65 73 65 74 20 63 6f eve and reset co
49e30 75 6e 74 65 72 20 76 61 6c 75 65 73 20 66 72 6f unter values fro
49e40 6d 0a 2a 2a 20 61 20 5b 70 72 65 70 61 72 65 64 m.** a [prepared
49e50 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 54 68 statement]. Th
49e60 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
49e70 20 69 73 20 74 68 65 20 70 72 65 70 61 72 65 64 is the prepared
49e80 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 62 statement.** ob
49e90 6a 65 63 74 20 74 6f 20 62 65 20 69 6e 74 65 72 ject to be inter
49ea0 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 73 65 rogated. The se
49eb0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a cond argument.**
49ec0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 is an integer c
49ed0 6f 64 65 20 66 6f 72 20 61 20 73 70 65 63 69 66 ode for a specif
49ee0 69 63 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 53 ic [SQLITE_STMTS
49ef0 54 41 54 55 53 5f 53 4f 52 54 20 7c 20 63 6f 75 TATUS_SORT | cou
49f00 6e 74 65 72 5d 0a 2a 2a 20 74 6f 20 62 65 20 69 nter].** to be i
49f10 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 0a 2a 2a nterrogated. .**
49f20 20 54 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c The current val
49f30 75 65 20 6f 66 20 74 68 65 20 72 65 71 75 65 73 ue of the reques
49f40 74 65 64 20 63 6f 75 6e 74 65 72 20 69 73 20 72 ted counter is r
49f50 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 eturned..** If t
49f60 68 65 20 72 65 73 65 74 46 6c 67 20 69 73 20 74 he resetFlg is t
49f70 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63 6f rue, then the co
49f80 75 6e 74 65 72 20 69 73 20 72 65 73 65 74 20 74 unter is reset t
49f90 6f 20 7a 65 72 6f 20 61 66 74 65 72 20 74 68 69 o zero after thi
49fa0 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 63 s.** interface c
49fb0 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a all returns..**.
49fc0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
49fd0 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 20 lite3_status()]
49fe0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f and [sqlite3_db_
49ff0 73 74 61 74 75 73 28 29 5d 2e 0a 2a 2f 0a 53 51 status()]..*/.SQ
4a000 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 LITE_EXPERIMENTA
4a010 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 L int sqlite3_st
4a020 6d 74 5f 73 74 61 74 75 73 28 73 71 6c 69 74 65 mt_status(sqlite
4a030 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 6f 70 2c 3_stmt*, int op,
4a040 69 6e 74 20 72 65 73 65 74 46 6c 67 29 3b 0a 0a int resetFlg);..
4a050 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
4a060 53 74 61 74 75 73 20 50 61 72 61 6d 65 74 65 72 Status Parameter
4a070 73 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 73 s for prepared s
4a080 74 61 74 65 6d 65 6e 74 73 20 7b 48 31 37 35 37 tatements {H1757
4a090 30 7d 20 3c 48 31 37 35 35 30 3e 0a 2a 2a 20 45 0} <H17550>.** E
4a0a0 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a XPERIMENTAL.**.*
4a0b0 2a 20 54 68 65 73 65 20 70 72 65 70 72 6f 63 65 * These preproce
4a0c0 73 73 6f 72 20 6d 61 63 72 6f 73 20 64 65 66 69 ssor macros defi
4a0d0 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 ne integer codes
4a0e0 20 74 68 61 74 20 6e 61 6d 65 20 63 6f 75 6e 74 that name count
4a0f0 65 72 0a 2a 2a 20 76 61 6c 75 65 73 20 61 73 73 er.** values ass
4a100 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 ociated with the
4a110 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 73 [sqlite3_stmt_s
4a120 74 61 74 75 73 28 29 5d 20 69 6e 74 65 72 66 61 tatus()] interfa
4a130 63 65 2e 0a 2a 2a 20 54 68 65 20 6d 65 61 6e 69 ce..** The meani
4a140 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f ngs of the vario
4a150 75 73 20 63 6f 75 6e 74 65 72 73 20 61 72 65 20 us counters are
4a160 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a as follows:.**.*
4a170 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 * <dl>.** <dt>SQ
4a180 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f LITE_STMTSTATUS_
4a190 46 55 4c 4c 53 43 41 4e 5f 53 54 45 50 3c 2f 64 FULLSCAN_STEP</d
4a1a0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 69 t>.** <dd>This i
4a1b0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
4a1c0 74 69 6d 65 73 20 74 68 61 74 20 53 51 4c 69 74 times that SQLit
4a1d0 65 20 68 61 73 20 73 74 65 70 70 65 64 20 66 6f e has stepped fo
4a1e0 72 77 61 72 64 20 69 6e 0a 2a 2a 20 61 20 74 61 rward in.** a ta
4a1f0 62 6c 65 20 61 73 20 70 61 72 74 20 6f 66 20 61 ble as part of a
4a200 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e full table scan
4a210 2e 20 20 4c 61 72 67 65 20 6e 75 6d 62 65 72 73 . Large numbers
4a220 20 66 6f 72 20 74 68 69 73 20 63 6f 75 6e 74 65 for this counte
4a230 72 0a 2a 2a 20 6d 61 79 20 69 6e 64 69 63 61 74 r.** may indicat
4a240 65 20 6f 70 70 6f 72 74 75 6e 69 74 69 65 73 20 e opportunities
4a250 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 for performance
4a260 69 6d 70 72 6f 76 65 6d 65 6e 74 20 74 68 72 6f improvement thro
4a270 75 67 68 20 0a 2a 2a 20 63 61 72 65 66 75 6c 20 ugh .** careful
4a280 75 73 65 20 6f 66 20 69 6e 64 69 63 65 73 2e 3c use of indices.<
4a290 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
4a2a0 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 55 53 QLITE_STMTSTATUS
4a2b0 5f 53 4f 52 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 _SORT</dt>.** <d
4a2c0 64 3e 54 68 69 73 20 69 73 20 74 68 65 20 6e 75 d>This is the nu
4a2d0 6d 62 65 72 20 6f 66 20 73 6f 72 74 20 6f 70 65 mber of sort ope
4a2e0 72 61 74 69 6f 6e 73 20 74 68 61 74 20 68 61 76 rations that hav
4a2f0 65 20 6f 63 63 75 72 72 65 64 2e 0a 2a 2a 20 41 e occurred..** A
4a300 20 6e 6f 6e 2d 7a 65 72 6f 20 76 61 6c 75 65 20 non-zero value
4a310 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 65 72 20 in this counter
4a320 6d 61 79 20 69 6e 64 69 63 61 74 65 20 61 6e 20 may indicate an
4a330 6f 70 70 6f 72 74 75 6e 69 74 79 20 74 6f 0a 2a opportunity to.*
4a340 2a 20 69 6d 70 72 6f 76 65 6d 65 6e 74 20 70 65 * improvement pe
4a350 72 66 6f 72 6d 61 6e 63 65 20 74 68 72 6f 75 67 rformance throug
4a360 68 20 63 61 72 65 66 75 6c 20 75 73 65 20 6f 66 h careful use of
4a370 20 69 6e 64 69 63 65 73 2e 3c 2f 64 64 3e 0a 2a indices.</dd>.*
4a380 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 *.** </dl>.*/.#d
4a390 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 4d efine SQLITE_STM
4a3a0 54 53 54 41 54 55 53 5f 46 55 4c 4c 53 43 41 4e TSTATUS_FULLSCAN
4a3b0 5f 53 54 45 50 20 20 20 20 20 31 0a 23 64 65 66 _STEP 1.#def
4a3c0 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 4d 54 53 ine SQLITE_STMTS
4a3d0 54 41 54 55 53 5f 53 4f 52 54 20 20 20 20 20 20 TATUS_SORT
4a3e0 20 20 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 2../*.**
4a3f0 20 55 6e 64 6f 20 74 68 65 20 68 61 63 6b 20 74 Undo the hack t
4a400 68 61 74 20 63 6f 6e 76 65 72 74 73 20 66 6c 6f hat converts flo
4a410 61 74 69 6e 67 20 70 6f 69 6e 74 20 74 79 70 65 ating point type
4a420 73 20 74 6f 20 69 6e 74 65 67 65 72 20 66 6f 72 s to integer for
4a430 0a 2a 2a 20 62 75 69 6c 64 73 20 6f 6e 20 70 72 .** builds on pr
4a440 6f 63 65 73 73 6f 72 73 20 77 69 74 68 6f 75 74 ocessors without
4a450 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 floating point
4a460 73 75 70 70 6f 72 74 2e 0a 2a 2f 0a 23 69 66 64 support..*/.#ifd
4a470 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 ef SQLITE_OMIT_F
4a480 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 LOATING_POINT.#
4a490 75 6e 64 65 66 20 64 6f 75 62 6c 65 0a 23 65 6e undef double.#en
4a4a0 64 69 66 0a 0a 23 69 66 64 65 66 20 5f 5f 63 70 dif..#ifdef __cp
4a4b0 6c 75 73 70 6c 75 73 0a 7d 20 20 2f 2a 20 45 6e lusplus.} /* En
4a4c0 64 20 6f 66 20 74 68 65 20 27 65 78 74 65 72 6e d of the 'extern
4a4d0 20 22 43 22 27 20 62 6c 6f 63 6b 20 2a 2f 0a 23 "C"' block */.#
4a4e0 65 6e 64 69 66 0a 23 65 6e 64 69 66 0a endif.#endif.