0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65 /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69 e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20 ms copyright to
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a . In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73 , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d sing:.**.** M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 nd not evil..**
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 May you find
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20 forgiveness for
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 give others..**
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65 May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 aking more than
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68 ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65 that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73 library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70 ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43 rograms. If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63 -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64 ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69 ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20 s file, then it
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20 ite, is subject
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64 t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72 should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53 grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74 e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70 arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70 erimental". Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65 y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64 s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20 to SQLite. We
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74 do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 e changes.** to
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65 erfaces but rese
03b0: 72 76 65 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f rve to make mino
03c0: 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a 20 r changes if.**
03d0: 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20 experience from
03e0: 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64 use "in the wild
03f0: 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20 63 " suggest such c
0400: 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64 65 hanges are prude
0410: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66 nt..**.** The of
0420: 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67 ficial C-languag
0430: 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74 e API documentat
0440: 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69 ion for SQLite i
0450: 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f s derived.** fro
0460: 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68 m comments in th
0470: 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66 is file. This f
0480: 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68 6f ile is the autho
0490: 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a ritative source.
04a0: 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65 ** on how SQLite
04b0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
04c0: 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61 suppose to opera
04d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 te..**.** The na
04e0: 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20 me of this file
04f0: 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74 under configurat
0500: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69 ion management i
0510: 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e s "sqlite.h.in".
0520: 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65 .** The makefile
0530: 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f makes some mino
0540: 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69 r changes to thi
0550: 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 20 s file (such as
0560: 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65 inserting.** the
0570: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29 version number)
0580: 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73 and changes its
0590: 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65 name to "sqlite
05a0: 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20 3.h" as.** part
05b0: 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f of the build pro
05c0: 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23 29 cess..**.** @(#)
05d0: 20 24 49 64 3a 20 73 71 6c 69 74 65 2e 68 2e 69 $Id: sqlite.h.i
05e0: 6e 2c 76 20 31 2e 34 32 34 20 32 30 30 39 2f 30 n,v 1.424 2009/0
05f0: 32 2f 30 33 20 31 38 3a 32 35 3a 31 33 20 64 72 2/03 18:25:13 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 2d 2d 56 45 52 53 2d 2d 22 0a "--VERS--".
1020: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 #define SQLITE_V
1030: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 20 2d ERSION_NUMBER -
1040: 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d -VERSION-NUMBER-
1050: 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 -../*.** CAPI3RE
1060: 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 F: Run-Time Libr
1070: 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 ary Version Numb
1080: 65 72 73 20 7b 48 31 30 30 32 30 7d 20 3c 53 36 ers {H10020} <S6
1090: 30 31 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 0100>.** KEYWORD
10a0: 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 S: sqlite3_versi
10b0: 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 on.**.** These f
10c0: 65 61 74 75 72 65 73 20 70 72 6f 76 69 64 65 20 eatures provide
10d0: 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 the same informa
10e0: 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c tion as the [SQL
10f0: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 ITE_VERSION].**
1100: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 and [SQLITE_VERS
1110: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 23 64 65 66 ION_NUMBER] #def
1120: 69 6e 65 73 20 69 6e 20 74 68 65 20 68 65 61 64 ines in the head
1130: 65 72 2c 20 62 75 74 20 61 72 65 20 61 73 73 6f er, but are asso
1140: 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 ciated.** with t
1150: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65 he library inste
1160: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72 ad of the header
1170: 20 66 69 6c 65 2e 20 20 43 61 75 74 69 6f 75 73 file. Cautious
1180: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 programmers mig
1190: 68 74 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 61 20 ht.** include a
11a0: 63 68 65 63 6b 20 69 6e 20 74 68 65 69 72 20 61 check in their a
11b0: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 76 65 pplication to ve
11c0: 72 69 66 79 20 74 68 61 74 0a 2a 2a 20 73 71 6c rify that.** sql
11d0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f ite3_libversion_
11e0: 6e 75 6d 62 65 72 28 29 20 61 6c 77 61 79 73 20 number() always
11f0: 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 returns the valu
1200: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 e.** [SQLITE_VER
1210: 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a 2a SION_NUMBER]..**
1220: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
1230: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e libversion() fun
1240: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 ction returns th
1250: 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 e same informati
1260: 6f 6e 20 61 73 20 69 73 0a 2a 2a 20 69 6e 20 74 on as is.** in t
1270: 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 he sqlite3_versi
1280: 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 on[] string cons
1290: 74 61 6e 74 2e 20 20 54 68 65 20 66 75 6e 63 74 tant. The funct
12a0: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 0a ion is provided.
12b0: 2a 2a 20 66 6f 72 20 75 73 65 20 69 6e 20 44 4c ** for use in DL
12c0: 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 Ls since DLL use
12d0: 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f rs usually do no
12e0: 74 20 68 61 76 65 20 64 69 72 65 63 74 20 61 63 t have direct ac
12f0: 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 0a 2a cess to string.*
1300: 2a 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 * constants with
1310: 69 6e 20 74 68 65 20 44 4c 4c 2e 0a 2a 2a 0a 2a in the DLL..**.*
1320: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
1330: 0a 2a 2a 20 7b 48 31 30 30 32 31 7d 20 54 68 65 .** {H10021} The
1340: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 [sqlite3_libver
1350: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 20 69 sion_number()] i
1360: 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72 nterface shall r
1370: 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 eturn.**
1380: 20 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71 75 an integer equ
1390: 61 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 56 45 al to [SQLITE_VE
13a0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a RSION_NUMBER]..*
13b0: 2a 0a 2a 2a 20 7b 48 31 30 30 32 32 7d 20 54 68 *.** {H10022} Th
13c0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 65 72 73 69 e [sqlite3_versi
13d0: 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 on] string const
13e0: 61 6e 74 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 ant shall contai
13f0: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 n.** th
1400: 65 20 74 65 78 74 20 6f 66 20 74 68 65 20 5b 53 e text of the [S
1410: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 73 QLITE_VERSION] s
1420: 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 tring..**.** {H1
1430: 30 30 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 0023} The [sqlit
1440: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d e3_libversion()]
1450: 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 function shall
1460: 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 return.**
1470: 20 20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 a pointer to
1480: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 65 72 the [sqlite3_ver
1490: 73 69 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e sion] string con
14a0: 73 74 61 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 stant..*/.SQLITE
14b0: 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 _EXTERN const ch
14c0: 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 ar sqlite3_versi
14d0: 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 on[];.const char
14e0: 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 *sqlite3_libver
14f0: 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 sion(void);.int
1500: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 sqlite3_libversi
1510: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b on_number(void);
1520: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1530: 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 : Test To See If
1540: 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 The Library Is
1550: 54 68 72 65 61 64 73 61 66 65 20 7b 48 31 30 31 Threadsafe {H101
1560: 30 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 00} <S60100>.**.
1570: 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 ** SQLite can be
1580: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f compiled with o
1590: 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 r without mutexe
15a0: 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 s. When.** the
15b0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
15c0: 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 FE] C preprocess
15d0: 6f 72 20 6d 61 63 72 6f 20 31 20 6f 72 20 32 2c or macro 1 or 2,
15e0: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 mutexes.** are
15f0: 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 enabled and SQLi
1600: 74 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 te is threadsafe
1610: 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b . When the.** [
1620: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
1630: 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a E] macro is 0, .
1640: 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 ** the mutexes a
1650: 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 re omitted. Wit
1660: 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 hout the mutexes
1670: 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 , it is not safe
1680: 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 .** to use SQLit
1690: 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 e concurrently f
16a0: 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e rom more than on
16b0: 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 e thread..**.**
16c0: 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 Enabling mutexes
16d0: 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 incurs a measur
16e0: 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 able performance
16f0: 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 penalty..** So
1700: 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 if speed is of u
1710: 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 tmost importance
1720: 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 , it makes sense
1730: 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 to disable.** t
1740: 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 he mutexes. But
1750: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 for maximum saf
1760: 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f ety, mutexes sho
1770: 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a uld be enabled..
1780: 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 62 ** The default b
1790: 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d ehavior is for m
17a0: 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61 utexes to be ena
17b0: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 bled..**.** This
17c0: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 interface can b
17d0: 65 20 75 73 65 64 20 62 79 20 61 20 70 72 6f 67 e used by a prog
17e0: 72 61 6d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 ram to make sure
17f0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 that the.** ver
1800: 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 sion of SQLite t
1810: 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e hat it is linkin
1820: 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63 6f g against was co
1830: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 mpiled with.** t
1840: 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74 69 he desired setti
1850: 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 ng of the [SQLIT
1860: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 E_THREADSAFE] ma
1870: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 cro..**.** This
1880: 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 interface only r
1890: 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 6f eports on the co
18a0: 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 mpile-time mutex
18b0: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 setting.** of t
18c0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 he [SQLITE_THREA
18d0: 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 DSAFE] flag. If
18e0: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
18f0: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 led with.** SQLI
1900: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20 TE_THREADSAFE=1
1910: 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 then mutexes are
1920: 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 enabled by defa
1930: 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 ult but.** can b
1940: 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 e fully or parti
1950: 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 ally disabled us
1960: 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 ing a call to [s
1970: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
1980: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 .** with the ver
1990: 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 bs [SQLITE_CONFI
19a0: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c G_SINGLETHREAD],
19b0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
19c0: 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a MULTITHREAD],.**
19d0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 or [SQLITE_CONF
19e0: 49 47 5f 4d 55 54 45 58 5d 2e 20 20 54 68 65 20 IG_MUTEX]. The
19f0: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 return value of
1a00: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 this function sh
1a10: 6f 77 73 0a 2a 2a 20 6f 6e 6c 79 20 74 68 65 20 ows.** only the
1a20: 64 65 66 61 75 6c 74 20 63 6f 6d 70 69 6c 65 2d default compile-
1a30: 74 69 6d 65 20 73 65 74 74 69 6e 67 2c 20 6e 6f time setting, no
1a40: 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 t any run-time c
1a50: 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 74 68 61 hanges.** to tha
1a60: 74 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a t setting..**.**
1a70: 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 See the [thread
1a80: 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 ing mode] docume
1a90: 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 ntation for addi
1aa0: 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 tional informati
1ab0: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 on..**.** INVARI
1ac0: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 ANTS:.**.** {H10
1ad0: 31 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 101} The [sqlite
1ae0: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 3_threadsafe()]
1af0: 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 function shall r
1b00: 65 74 75 72 6e 20 7a 65 72 6f 20 69 66 0a 2a 2a eturn zero if.**
1b10: 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 6f 6e and on
1b20: 6c 79 20 69 66 20 53 51 4c 69 74 65 20 77 61 73 ly if SQLite was
1b30: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d compiled with m
1b40: 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 utexing code omi
1b50: 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 tted..**.** {H10
1b60: 31 30 32 7d 20 54 68 65 20 76 61 6c 75 65 20 72 102} The value r
1b70: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 5b eturned by the [
1b80: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 sqlite3_threadsa
1b90: 66 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a fe()] function.*
1ba0: 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c * shall
1bb0: 20 72 65 6d 61 69 6e 20 74 68 65 20 73 61 6d 65 remain the same
1bc0: 20 61 63 72 6f 73 73 20 63 61 6c 6c 73 20 74 6f across calls to
1bd0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
1be0: 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ()]..*/.int sqli
1bf0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 te3_threadsafe(v
1c00: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 oid);../*.** CAP
1c10: 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 I3REF: Database
1c20: 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c Connection Handl
1c30: 65 20 7b 48 31 32 30 30 30 7d 20 3c 53 34 30 32 e {H12000} <S402
1c40: 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 00>.** KEYWORDS:
1c50: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 {database conne
1c60: 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 ction} {database
1c70: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a connections}.**
1c80: 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 .** Each open SQ
1c90: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 Lite database is
1ca0: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 represented by
1cb0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
1cc0: 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 instance of.** t
1cd0: 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 he opaque struct
1ce0: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 ure named "sqlit
1cf0: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 e3". It is usef
1d00: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 ul to think of a
1d10: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 n sqlite3.** poi
1d20: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 nter as an objec
1d30: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 t. The [sqlite3
1d40: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 _open()], [sqlit
1d50: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e e3_open16()], an
1d60: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 d.** [sqlite3_op
1d70: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 en_v2()] interfa
1d80: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 ces are its cons
1d90: 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 tructors, and [s
1da0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a qlite3_close()].
1db0: 2a 2a 20 69 73 20 69 74 73 20 64 65 73 74 72 75 ** is its destru
1dc0: 63 74 6f 72 2e 20 20 54 68 65 72 65 20 61 72 65 ctor. There are
1dd0: 20 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 many other inte
1de0: 72 66 61 63 65 73 20 28 73 75 63 68 20 61 73 0a rfaces (such as.
1df0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
1e00: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 are_v2()], [sqli
1e10: 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
1e20: 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b ion()], and.** [
1e30: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d sqlite3_busy_tim
1e40: 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 eout()] to name
1e50: 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20 but three) that
1e60: 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 are methods on a
1e70: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a n.** sqlite3 obj
1e80: 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ect..*/.typedef
1e90: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73 struct sqlite3 s
1ea0: 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 qlite3;../*.** C
1eb0: 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20 API3REF: 64-Bit
1ec0: 49 6e 74 65 67 65 72 20 54 79 70 65 73 20 7b 48 Integer Types {H
1ed0: 31 30 32 30 30 7d 20 3c 53 31 30 31 31 30 3e 0a 10200} <S10110>.
1ee0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c ** KEYWORDS: sql
1ef0: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 ite_int64 sqlite
1f00: 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 _uint64.**.** Be
1f10: 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20 6e cause there is n
1f20: 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d o cross-platform
1f30: 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 79 20 way to specify
1f40: 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74 64-bit integer t
1f50: 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 ypes.** SQLite i
1f60: 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 66 73 ncludes typedefs
1f70: 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e for 64-bit sign
1f80: 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 ed and unsigned
1f90: 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 integers..**.**
1fa0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 The sqlite3_int6
1fb0: 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 4 and sqlite3_ui
1fc0: 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 72 65 nt64 are the pre
1fd0: 66 65 72 72 65 64 20 74 79 70 65 20 64 65 66 69 ferred type defi
1fe0: 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 nitions..** The
1ff0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 sqlite_int64 and
2000: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 sqlite_uint64 t
2010: 79 70 65 73 20 61 72 65 20 73 75 70 70 6f 72 74 ypes are support
2020: 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 ed for backwards
2030: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 .** compatibilit
2040: 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e y only..**.** IN
2050: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
2060: 7b 48 31 30 32 30 31 7d 20 54 68 65 20 5b 73 71 {H10201} The [sq
2070: 6c 69 74 65 5f 69 6e 74 36 34 5d 20 61 6e 64 20 lite_int64] and
2080: 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 5d 20 [sqlite3_int64]
2090: 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65 63 69 type shall speci
20a0: 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 fy.** a
20b0: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 64-bit signed i
20c0: 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 nteger..**.** {H
20d0: 31 30 32 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 10202} The [sqli
20e0: 74 65 5f 75 69 6e 74 36 34 5d 20 61 6e 64 20 5b te_uint64] and [
20f0: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 5d 20 sqlite3_uint64]
2100: 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65 63 69 type shall speci
2110: 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 fy.** a
2120: 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 64-bit unsigned
2130: 20 69 6e 74 65 67 65 72 2e 0a 2a 2f 0a 23 69 66 integer..*/.#if
2140: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 def SQLITE_INT64
2150: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 _TYPE. typedef
2160: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 SQLITE_INT64_TYP
2170: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a E sqlite_int64;.
2180: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e typedef unsign
2190: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f ed SQLITE_INT64_
21a0: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 TYPE sqlite_uint
21b0: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64;.#elif define
21c0: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 d(_MSC_VER) || d
21d0: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 efined(__BORLAND
21e0: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f C__). typedef _
21f0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e _int64 sqlite_in
2200: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 t64;. typedef u
2210: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 nsigned __int64
2220: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 sqlite_uint64;.#
2230: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c else. typedef l
2240: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c ong long int sql
2250: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 ite_int64;. typ
2260: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f edef unsigned lo
2270: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 ng long int sqli
2280: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 te_uint64;.#endi
2290: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 f.typedef sqlite
22a0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 _int64 sqlite3_i
22b0: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 nt64;.typedef sq
22c0: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 lite_uint64 sqli
22d0: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a te3_uint64;../*.
22e0: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 ** If compiling
22f0: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 for a processor
2300: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 that lacks float
2310: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 ing point suppor
2320: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 t,.** substitute
2330: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f integer for flo
2340: 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a ating-point..*/.
2350: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d #ifdef SQLITE_OM
2360: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e IT_FLOATING_POIN
2370: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c T.# define doubl
2380: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a e sqlite3_int64.
2390: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 #endif../*.** CA
23a0: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 PI3REF: Closing
23b0: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 A Database Conne
23c0: 63 74 69 6f 6e 20 7b 48 31 32 30 31 30 7d 20 3c ction {H12010} <
23d0: 53 33 30 31 30 30 3e 3c 53 34 30 32 30 30 3e 0a S30100><S40200>.
23e0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
23f0: 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72 75 ne is the destru
2400: 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71 ctor for the [sq
2410: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a lite3] object..*
2420: 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e *.** Application
2430: 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 s should [sqlite
2440: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 3_finalize | fin
2450: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 alize] all [prep
2460: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d ared statements]
2470: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 .** and [sqlite3
2480: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c _blob_close | cl
2490: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 ose] all [BLOB h
24a0: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74 andles] associat
24b0: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b ed with.** the [
24c0: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 sqlite3] object
24d0: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 prior to attempt
24e0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 ing to close the
24f0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 65 20 object..** The
2500: 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 [sqlite3_next_st
2510: 6d 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 mt()] interface
2520: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c can be used to l
2530: 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a 20 5b 70 72 ocate all.** [pr
2540: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2550: 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 s] associated wi
2560: 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 th a [database c
2570: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 66 20 64 65 onnection] if de
2580: 73 69 72 65 64 2e 0a 2a 2a 20 54 79 70 69 63 61 sired..** Typica
2590: 6c 20 63 6f 64 65 20 6d 69 67 68 74 20 6c 6f 6f l code might loo
25a0: 6b 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a k like this:.**.
25b0: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
25c0: 70 72 65 3e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f pre>.** sqlite3_
25d0: 73 74 6d 74 20 2a 70 53 74 6d 74 3b 0a 2a 2a 20 stmt *pStmt;.**
25e0: 77 68 69 6c 65 28 20 28 70 53 74 6d 74 20 3d 20 while( (pStmt =
25f0: 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d sqlite3_next_stm
2600: 74 28 64 62 2c 20 30 29 29 21 3d 30 20 29 7b 0a t(db, 0))!=0 ){.
2610: 2a 2a 20 26 6e 62 73 70 3b 20 20 20 73 71 6c 69 ** sqli
2620: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 70 53 74 te3_finalize(pSt
2630: 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c 2f 70 mt);.** }.** </p
2640: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
2650: 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 .**.** If [sqlit
2660: 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 e3_close()] is i
2670: 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 20 74 nvoked while a t
2680: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 ransaction is op
2690: 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 en,.** the trans
26a0: 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 action is automa
26b0: 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 tically rolled b
26c0: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 ack..**.** INVAR
26d0: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 IANTS:.**.** {H1
26e0: 32 30 31 31 7d 20 41 20 73 75 63 63 65 73 73 66 2011} A successf
26f0: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 ul call to [sqli
2700: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 73 68 te3_close(C)] sh
2710: 61 6c 6c 20 64 65 73 74 72 6f 79 20 74 68 65 0a all destroy the.
2720: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 ** [dat
2730: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2740: 5d 20 6f 62 6a 65 63 74 20 43 2e 0a 2a 2a 0a 2a ] object C..**.*
2750: 2a 20 7b 48 31 32 30 31 32 7d 20 41 20 73 75 63 * {H12012} A suc
2760: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 cessful call to
2770: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 [sqlite3_close(C
2780: 29 5d 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 )] shall return
2790: 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a SQLITE_OK..**.**
27a0: 20 7b 48 31 32 30 31 33 7d 20 41 20 73 75 63 63 {H12013} A succ
27b0: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b essful call to [
27c0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 sqlite3_close(C)
27d0: 5d 20 73 68 61 6c 6c 20 72 65 6c 65 61 73 65 20 ] shall release
27e0: 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 all.**
27f0: 6d 65 6d 6f 72 79 20 61 6e 64 20 73 79 73 74 65 memory and syste
2800: 6d 20 72 65 73 6f 75 72 63 65 73 20 61 73 73 6f m resources asso
2810: 63 69 61 74 65 64 20 77 69 74 68 20 5b 64 61 74 ciated with [dat
2820: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2830: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 2e ].** C.
2840: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 34 7d 20 .**.** {H12014}
2850: 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 A call to [sqlit
2860: 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6f 6e 20 e3_close(C)] on
2870: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a [database conn
2880: 65 63 74 69 6f 6e 5d 20 43 20 74 68 61 74 0a 2a ection] C that.*
2890: 2a 20 20 20 20 20 20 20 20 20 20 68 61 73 20 6f * has o
28a0: 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 70 65 6e 20 ne or more open
28b0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
28c0: 65 6e 74 73 5d 20 73 68 61 6c 6c 20 66 61 69 6c ents] shall fail
28d0: 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 with.**
28e0: 20 20 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 an [SQLITE_BUS
28f0: 59 5d 20 65 72 72 6f 72 20 63 6f 64 65 2e 0a 2a Y] error code..*
2900: 2a 0a 2a 2a 20 7b 48 31 32 30 31 35 7d 20 41 20 *.** {H12015} A
2910: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
2920: 5f 63 6c 6f 73 65 28 43 29 5d 20 77 68 65 72 65 _close(C)] where
2930: 20 43 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 C is a NULL poi
2940: 6e 74 65 72 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 nter shall.**
2950: 20 20 20 20 20 20 20 62 65 20 61 20 68 61 72 6d be a harm
2960: 6c 65 73 73 20 6e 6f 2d 6f 70 20 72 65 74 75 72 less no-op retur
2970: 6e 69 6e 67 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a ning SQLITE_OK..
2980: 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 39 7d 20 57 **.** {H12019} W
2990: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f hen [sqlite3_clo
29a0: 73 65 28 43 29 5d 20 69 73 20 69 6e 76 6f 6b 65 se(C)] is invoke
29b0: 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 d on a [database
29c0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 43 0a 2a connection] C.*
29d0: 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 * that
29e0: 68 61 73 20 61 20 70 65 6e 64 69 6e 67 20 74 72 has a pending tr
29f0: 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 20 74 ansaction, the t
2a00: 72 61 6e 73 61 63 74 69 6f 6e 20 73 68 61 6c 6c ransaction shall
2a10: 20 62 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 be.**
2a20: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a rolled back..**.
2a30: 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a ** ASSUMPTIONS:.
2a40: 2a 2a 0a 2a 2a 20 7b 41 31 32 30 31 36 7d 20 54 **.** {A12016} T
2a50: 68 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 he C parameter t
2a60: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 o [sqlite3_close
2a70: 28 43 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74 (C)] must be eit
2a80: 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 20 20 her a NULL.**
2a90: 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 6f pointer o
2aa0: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f r an [sqlite3] o
2ab0: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 bject pointer ob
2ac0: 74 61 69 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 tained.**
2ad0: 20 20 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 from [sqlite3
2ae0: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 _open()], [sqlit
2af0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 e3_open16()], or
2b00: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
2b10: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d lite3_open_v2()]
2b20: 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f , and not previo
2b30: 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2f 0a usly closed..*/.
2b40: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 int sqlite3_clos
2b50: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f e(sqlite3 *);../
2b60: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f *.** The type fo
2b70: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e r a callback fun
2b80: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 ction..** This i
2b90: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 s legacy and dep
2ba0: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 recated. It is
2bb0: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 included for his
2bc0: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 torical.** compa
2bd0: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 tibility and is
2be0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a not documented..
2bf0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 */.typedef int (
2c00: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 *sqlite3_callbac
2c10: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 k)(void*,int,cha
2c20: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f r**, char**);../
2c30: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
2c40: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 ne-Step Query Ex
2c50: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 ecution Interfac
2c60: 65 20 7b 48 31 32 31 30 30 7d 20 3c 53 31 30 30 e {H12100} <S100
2c70: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 00>.**.** The sq
2c80: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 lite3_exec() int
2c90: 65 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 erface is a conv
2ca0: 65 6e 69 65 6e 74 20 77 61 79 20 6f 66 20 72 75 enient way of ru
2cb0: 6e 6e 69 6e 67 20 6f 6e 65 20 6f 72 20 6d 6f 72 nning one or mor
2cc0: 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 e.** SQL stateme
2cd0: 6e 74 73 20 77 69 74 68 6f 75 74 20 68 61 76 69 nts without havi
2ce0: 6e 67 20 74 6f 20 77 72 69 74 65 20 61 20 6c 6f ng to write a lo
2cf0: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 20 54 68 t of C code. Th
2d00: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 0a e UTF-8 encoded.
2d10: 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ** SQL statement
2d20: 73 20 61 72 65 20 70 61 73 73 65 64 20 69 6e 20 s are passed in
2d30: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 as the second pa
2d40: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
2d50: 65 33 5f 65 78 65 63 28 29 2e 0a 2a 2a 20 54 68 e3_exec()..** Th
2d60: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 e statements are
2d70: 20 65 76 61 6c 75 61 74 65 64 20 6f 6e 65 20 62 evaluated one b
2d80: 79 20 6f 6e 65 20 75 6e 74 69 6c 20 65 69 74 68 y one until eith
2d90: 65 72 20 61 6e 20 65 72 72 6f 72 20 6f 72 0a 2a er an error or.*
2da0: 2a 20 61 6e 20 69 6e 74 65 72 72 75 70 74 20 69 * an interrupt i
2db0: 73 20 65 6e 63 6f 75 6e 74 65 72 65 64 2c 20 6f s encountered, o
2dc0: 72 20 75 6e 74 69 6c 20 74 68 65 79 20 61 72 65 r until they are
2dd0: 20 61 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 65 20 all done. The
2de0: 33 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 3rd parameter.**
2df0: 20 69 73 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 is an optional
2e00: 63 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 69 73 callback that is
2e10: 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f invoked once fo
2e20: 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20 61 6e r each row of an
2e30: 79 20 71 75 65 72 79 0a 2a 2a 20 72 65 73 75 6c y query.** resul
2e40: 74 73 20 70 72 6f 64 75 63 65 64 20 62 79 20 74 ts produced by t
2e50: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
2e60: 73 2e 20 20 54 68 65 20 35 74 68 20 70 61 72 61 s. The 5th para
2e70: 6d 65 74 65 72 20 74 65 6c 6c 73 20 77 68 65 72 meter tells wher
2e80: 65 0a 2a 2a 20 74 6f 20 77 72 69 74 65 20 61 6e e.** to write an
2e90: 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 73 y error messages
2ea0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 72 72 6f ..**.** The erro
2eb0: 72 20 6d 65 73 73 61 67 65 20 70 61 73 73 65 64 r message passed
2ec0: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 back through th
2ed0: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 5th parameter
2ee0: 69 73 20 68 65 6c 64 0a 2a 2a 20 69 6e 20 6d 65 is held.** in me
2ef0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 mory obtained fr
2f00: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
2f10: 6f 63 28 29 5d 2e 20 20 54 6f 20 61 76 6f 69 64 oc()]. To avoid
2f20: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2c 0a a memory leak,.
2f30: 2a 2a 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 61 ** the calling a
2f40: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
2f50: 64 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f d call [sqlite3_
2f60: 66 72 65 65 28 29 5d 20 6f 6e 20 61 6e 79 20 65 free()] on any e
2f70: 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 rror.** message
2f80: 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 returned through
2f90: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 the 5th paramet
2fa0: 65 72 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 er when it has f
2fb0: 69 6e 69 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a inished using.**
2fc0: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 the error messa
2fd0: 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 ge..**.** If the
2fe0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 SQL statement i
2ff0: 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 n the 2nd parame
3000: 74 65 72 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 ter is NULL or a
3010: 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 0a 2a n empty string.*
3020: 2a 20 6f 72 20 61 20 73 74 72 69 6e 67 20 63 6f * or a string co
3030: 6e 74 61 69 6e 69 6e 67 20 6f 6e 6c 79 20 77 68 ntaining only wh
3040: 69 74 65 73 70 61 63 65 20 61 6e 64 20 63 6f 6d itespace and com
3050: 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 ments, then no S
3060: 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 QL.** statements
3070: 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 are evaluated a
3080: 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 nd the database
3090: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a is not changed..
30a0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
30b0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 3_exec() interfa
30c0: 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 ce is implemente
30d0: 64 20 69 6e 20 74 65 72 6d 73 20 6f 66 0a 2a 2a d in terms of.**
30e0: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
30f0: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 e_v2()], [sqlite
3100: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 3_step()], and [
3110: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
3120: 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ()]..** The sqli
3130: 74 65 33 5f 65 78 65 63 28 29 20 72 6f 75 74 69 te3_exec() routi
3140: 6e 65 20 64 6f 65 73 20 6e 6f 74 68 69 6e 67 20 ne does nothing
3150: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 to the database
3160: 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 64 that cannot be d
3170: 6f 6e 65 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 one.** by [sqlit
3180: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
3190: 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 , [sqlite3_step(
31a0: 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 )], and [sqlite3
31b0: 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a _finalize()]..**
31c0: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
31d0: 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 31 7d 20 41 **.** {H12101} A
31e0: 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f successful invo
31f0: 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 cation of [sqlit
3200: 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c e3_exec(D,S,C,A,
3210: 45 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 E)].**
3220: 73 68 61 6c 6c 20 73 65 71 75 65 6e 74 69 61 6c shall sequential
3230: 6c 79 20 65 76 61 6c 75 61 74 65 20 61 6c 6c 20 ly evaluate all
3240: 6f 66 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 of the UTF-8 enc
3250: 6f 64 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 oded,.**
3260: 20 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 semicolon-sepa
3270: 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d rated SQL statem
3280: 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f ents in the zero
3290: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 -terminated.**
32a0: 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 53 string S
32b0: 20 77 69 74 68 69 6e 20 74 68 65 20 63 6f 6e 74 within the cont
32c0: 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 ext of the [data
32d0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
32e0: 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 D..**.** {H1210
32f0: 32 7d 20 49 66 20 74 68 65 20 53 20 70 61 72 61 2} If the S para
3300: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 meter to [sqlite
3310: 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 3_exec(D,S,C,A,E
3320: 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 0a )] is NULL then.
3330: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
3340: 61 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 69 actions of the i
3350: 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 62 nterface shall b
3360: 65 20 74 68 65 20 73 61 6d 65 20 61 73 20 69 66 e the same as if
3370: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
3380: 20 53 20 70 61 72 61 6d 65 74 65 72 20 77 65 72 S parameter wer
3390: 65 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e e an empty strin
33a0: 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 34 g..**.** {H12104
33b0: 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c } The return val
33c0: 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 ue of [sqlite3_e
33d0: 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 62 65 20 xec()] shall be
33e0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 61 [SQLITE_OK] if a
33f0: 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 ll.** S
3400: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 72 75 QL statements ru
3410: 6e 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 61 n successfully a
3420: 6e 64 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e nd to completion
3430: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 35 7d ..**.** {H12105}
3440: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 The return valu
3450: 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 e of [sqlite3_ex
3460: 65 63 28 29 5d 20 73 68 61 6c 6c 20 62 65 20 61 ec()] shall be a
3470: 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a n appropriate.**
3480: 20 20 20 20 20 20 20 20 20 20 6e 6f 6e 2d 7a 65 non-ze
3490: 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 ro [error code]
34a0: 69 66 20 61 6e 79 20 53 51 4c 20 73 74 61 74 65 if any SQL state
34b0: 6d 65 6e 74 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a ment fails..**.*
34c0: 2a 20 7b 48 31 32 31 30 37 7d 20 49 66 20 6f 6e * {H12107} If on
34d0: 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 e or more of the
34e0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
34f0: 68 61 6e 64 65 64 20 74 6f 20 5b 73 71 6c 69 74 handed to [sqlit
3500: 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20 e3_exec()].**
3510: 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 72 65 return re
3520: 73 75 6c 74 73 20 61 6e 64 20 74 68 65 20 33 72 sults and the 3r
3530: 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e d parameter is n
3540: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 0a 2a 2a ot NULL, then.**
3550: 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63 61 the ca
3560: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
3570: 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 specified by the
3580: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 3rd parameter s
3590: 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 20 20 hall be.**
35a0: 20 20 20 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 invoked once
35b0: 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66 for each row of
35c0: 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b result..**.** {
35d0: 48 31 32 31 31 30 7d 20 49 66 20 74 68 65 20 63 H12110} If the c
35e0: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
35f0: 61 20 6e 6f 6e 2d 7a 65 72 6f 20 76 61 6c 75 65 a non-zero value
3600: 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 65 then [sqlite3_e
3610: 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 xec()].**
3620: 20 20 20 73 68 61 6c 6c 20 61 62 6f 72 74 20 74 shall abort t
3630: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
3640: 20 69 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 it is currently
3650: 20 65 76 61 6c 75 61 74 69 6e 67 2c 0a 2a 2a 20 evaluating,.**
3660: 20 20 20 20 20 20 20 20 20 73 6b 69 70 20 61 6c skip al
3670: 6c 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c l subsequent SQL
3680: 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64 statements, and
3690: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
36a0: 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ABORT]..**.** {H
36b0: 31 32 31 31 33 7d 20 54 68 65 20 5b 73 71 6c 69 12113} The [sqli
36c0: 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 te3_exec()] rout
36d0: 69 6e 65 20 73 68 61 6c 6c 20 70 61 73 73 20 69 ine shall pass i
36e0: 74 73 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 ts 4th parameter
36f0: 20 74 68 72 6f 75 67 68 0a 2a 2a 20 20 20 20 20 through.**
3700: 20 20 20 20 20 61 73 20 74 68 65 20 31 73 74 20 as the 1st
3710: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 parameter of the
3720: 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a callback..**.**
3730: 20 7b 48 31 32 31 31 36 7d 20 54 68 65 20 5b 73 {H12116} The [s
3740: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72 qlite3_exec()] r
3750: 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 65 74 outine shall set
3760: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
3770: 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 er of its.**
3780: 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 callback t
3790: 6f 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 o be the number
37a0: 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 of columns in th
37b0: 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 e current row of
37c0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 .** res
37d0: 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 ult..**.** {H121
37e0: 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 19} The [sqlite3
37f0: 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 _exec()] routine
3800: 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 33 shall set the 3
3810: 72 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 rd parameter of
3820: 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 its.**
3830: 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 61 callback to be a
3840: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 n array of point
3850: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 68 ers to strings h
3860: 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 olding the.**
3870: 20 20 20 20 20 20 20 76 61 6c 75 65 73 20 66 6f values fo
3880: 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20 69 6e r each column in
3890: 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 73 the current res
38a0: 75 6c 74 20 73 65 74 20 72 6f 77 20 61 73 0a 2a ult set row as.*
38b0: 2a 20 20 20 20 20 20 20 20 20 20 6f 62 74 61 69 * obtai
38c0: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ned from [sqlite
38d0: 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 3_column_text()]
38e0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 32 32 7d ..**.** {H12122}
38f0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 The [sqlite3_ex
3900: 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 ec()] routine sh
3910: 61 6c 6c 20 73 65 74 20 74 68 65 20 34 74 68 20 all set the 4th
3920: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 69 74 73 parameter of its
3930: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c .** cal
3940: 6c 62 61 63 6b 20 74 6f 20 62 65 20 61 6e 20 61 lback to be an a
3950: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 rray of pointers
3960: 20 74 6f 20 73 74 72 69 6e 67 73 20 68 6f 6c 64 to strings hold
3970: 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 ing the.**
3980: 20 20 20 20 6e 61 6d 65 73 20 6f 66 20 72 65 73 names of res
3990: 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 61 73 20 6f ult columns as o
39a0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
39b0: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
39c0: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 e()]..**.** {H12
39d0: 31 32 35 7d 20 49 66 20 74 68 65 20 33 72 64 20 125} If the 3rd
39e0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 parameter to [sq
39f0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 lite3_exec()] is
3a00: 20 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a 20 20 20 NULL then.**
3a10: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
3a20: 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 73 69 exec()] shall si
3a30: 6c 65 6e 74 6c 79 20 64 69 73 63 61 72 64 20 71 lently discard q
3a40: 75 65 72 79 20 72 65 73 75 6c 74 73 2e 0a 2a 2a uery results..**
3a50: 0a 2a 2a 20 7b 48 31 32 31 33 31 7d 20 49 66 20 .** {H12131} If
3a60: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 an error occurs
3a70: 77 68 69 6c 65 20 70 61 72 73 69 6e 67 20 6f 72 while parsing or
3a80: 20 65 76 61 6c 75 61 74 69 6e 67 20 61 6e 79 20 evaluating any
3a90: 6f 66 20 74 68 65 20 53 51 4c 0a 2a 2a 20 20 20 of the SQL.**
3aa0: 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 statement
3ab0: 73 20 69 6e 20 74 68 65 20 53 20 70 61 72 61 6d s in the S param
3ac0: 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 eter of [sqlite3
3ad0: 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 _exec(D,S,C,A,E)
3ae0: 5d 20 61 6e 64 20 69 66 0a 2a 2a 20 20 20 20 20 ] and if.**
3af0: 20 20 20 20 20 74 68 65 20 45 20 70 61 72 61 6d the E param
3b00: 65 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c eter is not NULL
3b10: 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f , then [sqlite3_
3b20: 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 73 74 exec()] shall st
3b30: 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ore.**
3b40: 69 6e 20 2a 45 20 61 6e 20 61 70 70 72 6f 70 72 in *E an appropr
3b50: 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 iate error messa
3b60: 67 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 ge written into
3b70: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a memory obtained.
3b80: 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d ** from
3b90: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
3ba0: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 ()]..**.** {H121
3bb0: 33 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 34} The [sqlite3
3bc0: 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 _exec(D,S,C,A,E)
3bd0: 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 ] routine shall
3be0: 73 65 74 20 74 68 65 20 76 61 6c 75 65 20 6f 66 set the value of
3bf0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 2a 45 20 .** *E
3c00: 74 6f 20 4e 55 4c 4c 20 69 66 20 45 20 69 73 20 to NULL if E is
3c10: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 74 68 65 not NULL and the
3c20: 72 65 20 61 72 65 20 6e 6f 20 65 72 72 6f 72 73 re are no errors
3c30: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33 37 7d ..**.** {H12137}
3c40: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 The [sqlite3_ex
3c50: 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 66 ec(D,S,C,A,E)] f
3c60: 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 73 65 unction shall se
3c70: 74 20 74 68 65 20 5b 65 72 72 6f 72 20 63 6f 64 t the [error cod
3c80: 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 e].** a
3c90: 6e 64 20 6d 65 73 73 61 67 65 20 61 63 63 65 73 nd message acces
3ca0: 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 sible via [sqlit
3cb0: 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 0a e3_errcode()], .
3cc0: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
3cd0: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 ite3_extended_er
3ce0: 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20 rcode()],.**
3cf0: 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 [sqlite3_e
3d00: 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73 rrmsg()], and [s
3d10: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 qlite3_errmsg16(
3d20: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33 )]..**.** {H1213
3d30: 38 7d 20 49 66 20 74 68 65 20 53 20 70 61 72 61 8} If the S para
3d40: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 meter to [sqlite
3d50: 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 3_exec(D,S,C,A,E
3d60: 29 5d 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e )] is NULL or an
3d70: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6d 70 .** emp
3d80: 74 79 20 73 74 72 69 6e 67 20 6f 72 20 63 6f 6e ty string or con
3d90: 74 61 69 6e 73 20 6e 6f 74 68 69 6e 67 20 6f 74 tains nothing ot
3da0: 68 65 72 20 74 68 61 6e 20 77 68 69 74 65 73 70 her than whitesp
3db0: 61 63 65 2c 20 63 6f 6d 6d 65 6e 74 73 2c 0a 2a ace, comments,.*
3dc0: 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 2f 6f * and/o
3dd0: 72 20 73 65 6d 69 63 6f 6c 6f 6e 73 2c 20 74 68 r semicolons, th
3de0: 65 6e 20 72 65 73 75 6c 74 73 20 6f 66 20 5b 73 en results of [s
3df0: 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 qlite3_errcode()
3e00: 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b ],.** [
3e10: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
3e20: 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 _errcode()],.**
3e30: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
3e40: 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64 3_errmsg()], and
3e50: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
3e60: 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 16()].**
3e70: 20 20 73 68 61 6c 6c 20 72 65 73 65 74 20 74 6f shall reset to
3e80: 20 69 6e 64 69 63 61 74 65 20 6e 6f 20 65 72 72 indicate no err
3e90: 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d ors..**.** ASSUM
3ea0: 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 PTIONS:.**.** {A
3eb0: 31 32 31 34 31 7d 20 54 68 65 20 66 69 72 73 74 12141} The first
3ec0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 parameter to [s
3ed0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6d qlite3_exec()] m
3ee0: 75 73 74 20 62 65 20 61 6e 20 76 61 6c 69 64 20 ust be an valid
3ef0: 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20 20 20 20 20 and open.**
3f00: 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 [database c
3f10: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a onnection]..**.*
3f20: 2a 20 7b 41 31 32 31 34 32 7d 20 54 68 65 20 64 * {A12142} The d
3f30: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
3f40: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 63 on must not be c
3f50: 6c 6f 73 65 64 20 77 68 69 6c 65 0a 2a 2a 20 20 losed while.**
3f60: 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
3f70: 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e _exec()] is runn
3f80: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31 ing..**.** {A121
3f90: 34 33 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 43} The calling
3fa0: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 function should
3fb0: 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 use [sqlite3_fre
3fc0: 65 28 29 5d 20 74 6f 20 66 72 65 65 0a 2a 2a 20 e()] to free.**
3fd0: 20 20 20 20 20 20 20 20 20 74 68 65 20 6d 65 6d the mem
3fe0: 6f 72 79 20 74 68 61 74 20 2a 65 72 72 6d 73 67 ory that *errmsg
3ff0: 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e is left pointin
4000: 67 20 61 74 20 6f 6e 63 65 20 74 68 65 20 65 72 g at once the er
4010: 72 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ror.**
4020: 6d 65 73 73 61 67 65 20 69 73 20 6e 6f 20 6c 6f message is no lo
4030: 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 0a nger needed..**.
4040: 2a 2a 20 7b 41 31 32 31 34 35 7d 20 54 68 65 20 ** {A12145} The
4050: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 SQL statement te
4060: 78 74 20 69 6e 20 74 68 65 20 32 6e 64 20 70 61 xt in the 2nd pa
4070: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
4080: 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20 te3_exec()].**
4090: 20 20 20 20 20 20 20 20 6d 75 73 74 20 72 65 6d must rem
40a0: 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 77 68 ain unchanged wh
40b0: 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 ile [sqlite3_exe
40c0: 63 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 2e c()] is running.
40d0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
40e0: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a exec(. sqlite3*
40f0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4110: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 /* An open da
4120: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 tabase */. cons
4130: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 t char *sql,
4140: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4150: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f /* SQL to
4160: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f be evaluated */
4170: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 . int (*callbac
4180: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 k)(void*,int,cha
4190: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a r**,char**), /*
41a0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 Callback functi
41b0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 on */. void *,
41c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
41e0: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 /* 1st argume
41f0: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a nt to callback *
4200: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 /. char **errms
4210: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 g
4220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
4230: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 * Error msg writ
4240: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a ten here */.);..
4250: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
4260: 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 Result Codes {H1
4270: 30 32 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 0210} <S10700>.*
4280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 * KEYWORDS: SQLI
4290: 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 TE_OK {error cod
42a0: 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d e} {error codes}
42b0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 .** KEYWORDS: {r
42c0: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73 esult code} {res
42d0: 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a ult codes}.**.**
42e0: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e Many SQLite fun
42f0: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e ctions return an
4300: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 integer result
4310: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 code from the se
4320: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 t shown.** here
4330: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 in order to indi
4340: 63 61 74 65 73 20 73 75 63 63 65 73 73 20 6f 72 cates success or
4350: 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 failure..**.**
4360: 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 New error codes
4370: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 may be added in
4380: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 future versions
4390: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a of SQLite..**.**
43a0: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 See also: [SQLI
43b0: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 TE_IOERR_READ |
43c0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
43d0: 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e codes].*/.#defin
43e0: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 e SQLITE_OK
43f0: 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 0 /* Suc
4400: 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a cessful result *
4410: 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f /./* beginning-o
4420: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f f-error-codes */
4430: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4440: 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 ERROR 1
4450: 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 /* SQL error or
4460: 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 missing databas
4470: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
4480: 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 ITE_INTERNAL
4490: 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 2 /* Internal
44a0: 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 logic error in
44b0: 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e SQLite */.#defin
44c0: 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 e SQLITE_PERM
44d0: 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 3 /* Acc
44e0: 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 ess permission d
44f0: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 enied */.#define
4500: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 SQLITE_ABORT
4510: 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 4 /* Call
4520: 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 back routine req
4530: 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 uested an abort
4540: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4550: 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 E_BUSY 5
4560: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 /* The databa
4570: 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 se file is locke
4580: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
4590: 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 ITE_LOCKED
45a0: 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 6 /* A table
45b0: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 in the database
45c0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 is locked */.#de
45d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 fine SQLITE_NOME
45e0: 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 M 7 /*
45f0: 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 A malloc() faile
4600: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
4610: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 ITE_READONLY
4620: 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 8 /* Attempt
4630: 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f to write a reado
4640: 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a nly database */.
4650: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
4660: 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 NTERRUPT 9
4670: 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 /* Operation ter
4680: 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 minated by sqlit
4690: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f e3_interrupt()*/
46a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
46b0: 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 IOERR 10
46c0: 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 /* Some kind of
46d0: 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 disk I/O error
46e0: 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 occurred */.#def
46f0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 ine SQLITE_CORRU
4700: 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 PT 11 /* T
4710: 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b he database disk
4720: 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 image is malfor
4730: 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 med */.#define S
4740: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 QLITE_NOTFOUND
4750: 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53 12 /* NOT US
4760: 45 44 2e 20 54 61 62 6c 65 20 6f 72 20 72 65 63 ED. Table or rec
4770: 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f ord not found */
4780: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4790: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 FULL 13
47a0: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 /* Insertion fa
47b0: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74 iled because dat
47c0: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f abase is full */
47d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
47e0: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 CANTOPEN 14
47f0: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 /* Unable to op
4800: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
4810: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 file */.#define
4820: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 SQLITE_PROTOCOL
4830: 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20 55 15 /* NOT U
4840: 53 45 44 2e 20 44 61 74 61 62 61 73 65 20 6c 6f SED. Database lo
4850: 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f ck protocol erro
4860: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c r */.#define SQL
4870: 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 ITE_EMPTY
4880: 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 16 /* Database
4890: 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 is empty */.#de
48a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 fine SQLITE_SCHE
48b0: 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 MA 17 /*
48c0: 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 The database sch
48d0: 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 ema changed */.#
48e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f define SQLITE_TO
48f0: 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20 2f OBIG 18 /
4900: 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 * String or BLOB
4910: 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 exceeds size li
4920: 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 mit */.#define S
4930: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
4940: 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 19 /* Abort
4950: 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e due to constrain
4960: 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 t violation */.#
4970: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 define SQLITE_MI
4980: 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 2f SMATCH 20 /
4990: 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d * Data type mism
49a0: 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 atch */.#define
49b0: 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 SQLITE_MISUSE
49c0: 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 21 /* Libra
49d0: 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 ry used incorrec
49e0: 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 tly */.#define S
49f0: 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 QLITE_NOLFS
4a00: 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 22 /* Uses O
4a10: 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 S features not s
4a20: 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 upported on host
4a30: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4a40: 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 TE_AUTH 2
4a50: 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 3 /* Authoriza
4a60: 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 tion denied */.#
4a70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f define SQLITE_FO
4a80: 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 2f RMAT 24 /
4a90: 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 * Auxiliary data
4aa0: 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f base format erro
4ab0: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c r */.#define SQL
4ac0: 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 ITE_RANGE
4ad0: 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 25 /* 2nd para
4ae0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
4af0: 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e _bind out of ran
4b00: 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ge */.#define SQ
4b10: 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 LITE_NOTADB
4b20: 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 26 /* File op
4b30: 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 ened that is not
4b40: 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 a database file
4b50: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4b60: 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 TE_ROW 1
4b70: 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 00 /* sqlite3_s
4b80: 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 tep() has anothe
4b90: 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 r row ready */.#
4ba0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f define SQLITE_DO
4bb0: 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f NE 101 /
4bc0: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 * sqlite3_step()
4bd0: 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 has finished ex
4be0: 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e ecuting */./* en
4bf0: 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 d-of-error-codes
4c00: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */../*.** CAPI3
4c10: 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 REF: Extended Re
4c20: 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 30 32 sult Codes {H102
4c30: 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 20} <S10700>.**
4c40: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e KEYWORDS: {exten
4c50: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20 ded error code}
4c60: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 {extended error
4c70: 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 codes}.** KEYWOR
4c80: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 DS: {extended re
4c90: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65 sult code} {exte
4ca0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
4cb0: 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 s}.**.** In its
4cc0: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 default configur
4cd0: 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 ation, SQLite AP
4ce0: 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 I routines retur
4cf0: 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65 n one of 26 inte
4d00: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f ger.** [SQLITE_O
4d10: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 K | result codes
4d20: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 ]. However, exp
4d30: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 erience has show
4d40: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a n that many of.*
4d50: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 * these result c
4d60: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 odes are too coa
4d70: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 rse-grained. Th
4d80: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 ey do not provid
4d90: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 e as.** much inf
4da0: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 ormation about p
4db0: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 roblems as progr
4dc0: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b ammers might lik
4dd0: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 e. In an effort
4de0: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 to.** address t
4df0: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 his, newer versi
4e00: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 ons of SQLite (v
4e10: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 ersion 3.3.8 and
4e20: 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a later) include.
4e30: 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 ** support for a
4e40: 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 dditional result
4e50: 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 codes that prov
4e60: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 ide more detaile
4e70: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a d information.**
4e80: 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 about errors. T
4e90: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 he extended resu
4ea0: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61 lt codes are ena
4eb0: 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 bled or disabled
4ec0: 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 .** on a per dat
4ed0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
4ee0: 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 basis using the
4ef0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 .** [sqlite3_ext
4f00: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 ended_result_cod
4f10: 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a es()] API..**.**
4f20: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61 Some of the ava
4f30: 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20 ilable extended
4f40: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 result codes are
4f50: 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a listed here..**
4f60: 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20 One may expect
4f70: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 the number of ex
4f80: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
4f90: 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61 des will be expa
4fa0: 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e nd.** over time.
4fb0: 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 Software that
4fc0: 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65 uses extended re
4fd0: 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c sult codes shoul
4fe0: 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73 d expect.** to s
4ff0: 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f ee new result co
5000: 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65 des in future re
5010: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
5020: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 ..**.** The SQLI
5030: 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64 TE_OK result cod
5040: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20 e will never be
5050: 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69 extended. It wi
5060: 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 ll always.** be
5070: 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2a exactly zero..**
5080: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
5090: 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 33 7d 20 54 **.** {H10223} T
50a0: 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 he symbolic name
50b0: 20 66 6f 72 20 61 6e 20 65 78 74 65 6e 64 65 64 for an extended
50c0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 73 68 61 result code sha
50d0: 6c 6c 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 ll contains.**
50e0: 20 20 20 20 20 20 20 20 61 20 72 65 6c 61 74 65 a relate
50f0: 64 20 70 72 69 6d 61 72 79 20 72 65 73 75 6c 74 d primary result
5100: 20 63 6f 64 65 20 61 73 20 61 20 70 72 65 66 69 code as a prefi
5110: 78 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 34 x..**.** {H10224
5120: 7d 20 50 72 69 6d 61 72 79 20 72 65 73 75 6c 74 } Primary result
5130: 20 63 6f 64 65 20 6e 61 6d 65 73 20 73 68 61 6c code names shal
5140: 6c 20 63 6f 6e 74 61 69 6e 20 61 20 73 69 6e 67 l contain a sing
5150: 6c 65 20 22 5f 22 20 63 68 61 72 61 63 74 65 72 le "_" character
5160: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 35 7d ..**.** {H10225}
5170: 20 45 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 Extended result
5180: 20 63 6f 64 65 20 6e 61 6d 65 73 20 73 68 61 6c code names shal
5190: 6c 20 63 6f 6e 74 61 69 6e 20 74 77 6f 20 6f 72 l contain two or
51a0: 20 6d 6f 72 65 20 22 5f 22 20 63 68 61 72 61 63 more "_" charac
51b0: 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 ters..**.** {H10
51c0: 32 32 36 7d 20 54 68 65 20 6e 75 6d 65 72 69 63 226} The numeric
51d0: 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 65 78 74 value of an ext
51e0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
51f0: 65 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 20 e shall contain
5200: 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
5210: 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 6f 66 numeric value of
5220: 20 69 74 73 20 63 6f 72 72 65 73 70 6f 6e 64 69 its correspondi
5230: 6e 67 20 70 72 69 6d 61 72 79 20 72 65 73 75 6c ng primary resul
5240: 74 20 63 6f 64 65 20 69 6e 0a 2a 2a 20 20 20 20 t code in.**
5250: 20 20 20 20 20 20 69 74 73 20 6c 65 61 73 74 20 its least
5260: 73 69 67 6e 69 66 69 63 61 6e 74 20 38 20 62 69 significant 8 bi
5270: 74 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ts..*/.#define S
5280: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 QLITE_IOERR_READ
5290: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 (S
52a0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 QLITE_IOERR | (1
52b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
52c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 LITE_IOERR_SHORT
52d0: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51 _READ (SQ
52e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c LITE_IOERR | (2<
52f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5300: 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 ITE_IOERR_WRITE
5310: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
5320: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c ITE_IOERR | (3<<
5330: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5340: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 TE_IOERR_FSYNC
5350: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
5360: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 TE_IOERR | (4<<8
5370: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5380: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e E_IOERR_DIR_FSYN
5390: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 C (SQLIT
53a0: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 E_IOERR | (5<<8)
53b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
53c0: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 _IOERR_TRUNCATE
53d0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
53e0: 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 _IOERR | (6<<8))
53f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5400: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 IOERR_FSTAT
5410: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5420: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a IOERR | (7<<8)).
5430: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5440: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 OERR_UNLOCK
5450: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
5460: 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 OERR | (8<<8)).#
5470: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
5480: 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 ERR_RDLOCK
5490: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
54a0: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 ERR | (9<<8)).#d
54b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
54c0: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 RR_DELETE
54d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
54e0: 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 RR | (10<<8)).#d
54f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5500: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 RR_BLOCKED
5510: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
5520: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 RR | (11<<8)).#d
5530: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5540: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 RR_NOMEM
5550: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
5560: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 RR | (12<<8)).#d
5570: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5580: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 RR_ACCESS
5590: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
55a0: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 RR | (13<<8)).#d
55b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
55c0: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 RR_CHECKRESERVED
55d0: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 LOCK (SQLITE_IOE
55e0: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 RR | (14<<8)).#d
55f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5600: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 RR_LOCK
5610: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
5620: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 RR | (15<<8)).#d
5630: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5640: 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 RR_CLOSE
5650: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
5660: 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 RR | (16<<8)).#d
5670: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5680: 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 RR_DIR_CLOSE
5690: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
56a0: 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 0a 2f RR | (17<<8))../
56b0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
56c0: 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 lags For File Op
56d0: 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 20 7b 48 en Operations {H
56e0: 31 30 32 33 30 7d 20 3c 48 31 31 31 32 30 3e 20 10230} <H11120>
56f0: 3c 48 31 32 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <H12700>.**.** T
5700: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 hese bit values
5710: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 are intended for
5720: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 use in the.** 3
5730: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
5740: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 the [sqlite3_ope
5750: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 n_v2()] interfac
5760: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 e and.** in the
5770: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 4th parameter to
5780: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f the xOpen metho
5790: 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c d of the.** [sql
57a0: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
57b0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
57c0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c ITE_OPEN_READONL
57d0: 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 Y 0x0000
57e0: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 0001.#define SQL
57f0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 ITE_OPEN_READWRI
5800: 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 TE 0x0000
5810: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 0002.#define SQL
5820: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 ITE_OPEN_CREATE
5830: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
5840: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 0004.#define SQL
5850: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f ITE_OPEN_DELETEO
5860: 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 NCLOSE 0x0000
5870: 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 0008.#define SQL
5880: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 ITE_OPEN_EXCLUSI
5890: 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 VE 0x0000
58a0: 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0010.#define SQL
58b0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 ITE_OPEN_MAIN_DB
58c0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
58d0: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0100.#define SQL
58e0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 ITE_OPEN_TEMP_DB
58f0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
5900: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0200.#define SQL
5910: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 ITE_OPEN_TRANSIE
5920: 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 NT_DB 0x0000
5930: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0400.#define SQL
5940: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f ITE_OPEN_MAIN_JO
5950: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 URNAL 0x0000
5960: 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0800.#define SQL
5970: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f ITE_OPEN_TEMP_JO
5980: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 URNAL 0x0000
5990: 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 1000.#define SQL
59a0: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 ITE_OPEN_SUBJOUR
59b0: 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 NAL 0x0000
59c0: 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 2000.#define SQL
59d0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f ITE_OPEN_MASTER_
59e0: 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 JOURNAL 0x0000
59f0: 34 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 4000.#define SQL
5a00: 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 ITE_OPEN_NOMUTEX
5a10: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
5a20: 38 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 8000.#define SQL
5a30: 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 ITE_OPEN_FULLMUT
5a40: 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 EX 0x0001
5a50: 30 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 0000../*.** CAPI
5a60: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 3REF: Device Cha
5a70: 72 61 63 74 65 72 69 73 74 69 63 73 20 7b 48 31 racteristics {H1
5a80: 30 32 34 30 7d 20 3c 48 31 31 31 32 30 3e 0a 2a 0240} <H11120>.*
5a90: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 *.** The xDevice
5aa0: 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65 74 Capabilities met
5ab0: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 hod of the [sqli
5ac0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a te3_io_methods].
5ad0: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e ** object return
5ae0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 s an integer whi
5af0: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f ch is a vector o
5b00: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62 f the these.** b
5b10: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 it values expres
5b20: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 sing I/O charact
5b30: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 eristics of the
5b40: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 mass storage.**
5b50: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 device that hold
5b60: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 s the file that
5b70: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f the [sqlite3_io_
5b80: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 methods].** refe
5b90: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 rs to..**.** The
5ba0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
5bb0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 OMIC property me
5bc0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 ans that all wri
5bd0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 tes of.** any si
5be0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 ze are atomic.
5bf0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
5c00: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 _ATOMICnnn value
5c10: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 s.** mean that w
5c20: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 rites of blocks
5c30: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 that are nnn byt
5c40: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a es in size and.*
5c50: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f * are aligned to
5c60: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 an address whic
5c70: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 h is an integer
5c80: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e multiple of.** n
5c90: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 nn are atomic.
5ca0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
5cb0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c _SAFE_APPEND val
5cc0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 ue means.** that
5cd0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 when data is ap
5ce0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 pended to a file
5cf0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 , the data is ap
5d00: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 pended.** first
5d10: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 then the size of
5d20: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 the file is ext
5d30: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 ended, never the
5d40: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 other.** way ar
5d50: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 ound. The SQLIT
5d60: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 E_IOCAP_SEQUENTI
5d70: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e AL property mean
5d80: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d s that.** inform
5d90: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e ation is written
5da0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 to disk in the
5db0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 same order as ca
5dc0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 lls.** to xWrite
5dd0: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ()..*/.#define S
5de0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
5df0: 49 43 20 20 20 20 20 20 20 20 20 20 30 78 30 30 IC 0x00
5e00: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 000001.#define S
5e10: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
5e20: 49 43 35 31 32 20 20 20 20 20 20 20 30 78 30 30 IC512 0x00
5e30: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 000002.#define S
5e40: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
5e50: 49 43 31 4b 20 20 20 20 20 20 20 20 30 78 30 30 IC1K 0x00
5e60: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 000004.#define S
5e70: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
5e80: 49 43 32 4b 20 20 20 20 20 20 20 20 30 78 30 30 IC2K 0x00
5e90: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 000008.#define S
5ea0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
5eb0: 49 43 34 4b 20 20 20 20 20 20 20 20 30 78 30 30 IC4K 0x00
5ec0: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 000010.#define S
5ed0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
5ee0: 49 43 38 4b 20 20 20 20 20 20 20 20 30 78 30 30 IC8K 0x00
5ef0: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 000020.#define S
5f00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
5f10: 49 43 31 36 4b 20 20 20 20 20 20 20 30 78 30 30 IC16K 0x00
5f20: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 000040.#define S
5f30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
5f40: 49 43 33 32 4b 20 20 20 20 20 20 20 30 78 30 30 IC32K 0x00
5f50: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 000080.#define S
5f60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
5f70: 49 43 36 34 4b 20 20 20 20 20 20 20 30 78 30 30 IC64K 0x00
5f80: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 000100.#define S
5f90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 QLITE_IOCAP_SAFE
5fa0: 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78 30 30 _APPEND 0x00
5fb0: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 000200.#define S
5fc0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 QLITE_IOCAP_SEQU
5fd0: 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78 30 30 ENTIAL 0x00
5fe0: 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 000400../*.** CA
5ff0: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 PI3REF: File Loc
6000: 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 48 31 30 king Levels {H10
6010: 32 35 30 7d 20 3c 48 31 31 31 32 30 3e 20 3c 48 250} <H11120> <H
6020: 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 11310>.**.** SQL
6030: 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 ite uses one of
6040: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 these integer va
6050: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f lues as the seco
6060: 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 nd.** argument t
6070: 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 o calls it makes
6080: 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 to the xLock()
6090: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 and xUnlock() me
60a0: 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b thods.** of an [
60b0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
60c0: 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 ds] object..*/.#
60d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f define SQLITE_LO
60e0: 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 CK_NONE
60f0: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 0.#define SQLIT
6100: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 E_LOCK_SHARED
6110: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 1.#define S
6120: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 QLITE_LOCK_RESER
6130: 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 VED 2.#defi
6140: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 ne SQLITE_LOCK_P
6150: 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 ENDING 3.#
6160: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f define SQLITE_LO
6170: 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 CK_EXCLUSIVE
6180: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 4../*.** CAPI3R
6190: 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 EF: Synchronizat
61a0: 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 20 7b ion Type Flags {
61b0: 48 31 30 32 36 30 7d 20 3c 48 31 31 31 32 30 3e H10260} <H11120>
61c0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 .**.** When SQLi
61d0: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 te invokes the x
61e0: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 Sync() method of
61f0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f an.** [sqlite3_
6200: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 io_methods] obje
6210: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d ct it uses a com
6220: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 bination of.** t
6230: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c hese integer val
6240: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e ues as the secon
6250: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a d argument..**.*
6260: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 * When the SQLIT
6270: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 E_SYNC_DATAONLY
6280: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 flag is used, it
6290: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a means that the.
62a0: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f ** sync operatio
62b0: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 n only needs to
62c0: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 flush data to ma
62d0: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f ss storage. Ino
62e0: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f de.** informatio
62f0: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c n need not be fl
6300: 75 73 68 65 64 2e 20 54 68 65 20 53 51 4c 49 54 ushed. The SQLIT
6310: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 66 6c E_SYNC_NORMAL fl
6320: 61 67 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 ag means.** to u
6330: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 se normal fsync(
6340: 29 20 73 65 6d 61 6e 74 69 63 73 2e 20 54 68 65 ) semantics. The
6350: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c SQLITE_SYNC_FUL
6360: 4c 20 66 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a 20 L flag means.**
6370: 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 to use Mac OS X
6380: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 style fullsync i
6390: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 nstead of fsync(
63a0: 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 )..*/.#define SQ
63b0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c LITE_SYNC_NORMAL
63c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 0x00002.
63d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
63e0: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 YNC_FULL
63f0: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 0x00003.#defin
6400: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 e SQLITE_SYNC_DA
6410: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 TAONLY 0x00
6420: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 010../*.** CAPI3
6430: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 REF: OS Interfac
6440: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 e Open File Hand
6450: 6c 65 20 7b 48 31 31 31 31 30 7d 20 3c 53 32 30 le {H11110} <S20
6460: 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 110>.**.** An [s
6470: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a qlite3_file] obj
6480: 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 ect represents a
6490: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 n open file in t
64a0: 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 66 61 he OS.** interfa
64b0: 63 65 20 6c 61 79 65 72 2e 20 20 49 6e 64 69 76 ce layer. Indiv
64c0: 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 idual OS interfa
64d0: 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ce implementatio
64e0: 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 ns will.** want
64f0: 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 to subclass this
6500: 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e object by appen
6510: 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 ding additional
6520: 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 fields.** for th
6530: 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 eir own use. Th
6540: 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 e pMethods entry
6550: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
6560: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f an.** [sqlite3_
6570: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 io_methods] obje
6580: 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 ct that defines
6590: 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 methods for perf
65a0: 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 orming.** I/O op
65b0: 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 erations on the
65c0: 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 open file..*/.ty
65d0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
65e0: 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 ite3_file sqlite
65f0: 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 3_file;.struct s
6600: 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 qlite3_file {.
6610: 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c const struct sql
6620: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 ite3_io_methods
6630: 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d *pMethods; /* M
6640: 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 ethods for an op
6650: 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f en file */.};../
6660: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
6670: 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 S Interface File
6680: 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 Virtual Methods
6690: 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 32 30 7d Object {H11120}
66a0: 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 <S20110>.**.**
66b0: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 Every file opene
66c0: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 d by the [sqlite
66d0: 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74 3_vfs] xOpen met
66e0: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e hod populates an
66f0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c .** [sqlite3_fil
6700: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d e] object (or, m
6710: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 ore commonly, a
6720: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a subclass of the.
6730: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 ** [sqlite3_file
6740: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 ] object) with a
6750: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
6760: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
6770: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 object..** This
6780: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 object defines t
6790: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 he methods used
67a0: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f to perform vario
67b0: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a us operations.**
67c0: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 against the ope
67d0: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 n file represent
67e0: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 ed by the [sqlit
67f0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e e3_file] object.
6800: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 .**.** The flags
6810: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 argument to xSy
6820: 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 nc may be one of
6830: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f [SQLITE_SYNC_NO
6840: 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c RMAL] or.** [SQL
6850: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 ITE_SYNC_FULL].
6860: 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 The first choic
6870: 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 e is the normal
6880: 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 fsync()..** The
6890: 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 second choice is
68a0: 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c a Mac OS X styl
68b0: 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 e fullsync. The
68c0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 [SQLITE_SYNC_DA
68d0: 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 TAONLY].** flag
68e0: 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 may be ORed in t
68f0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 o indicate that
6900: 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 only the data of
6910: 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 the file.** and
6920: 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e not its inode n
6930: 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 eeds to be synce
6940: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 d..**.** The int
6950: 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 eger values to x
6960: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f Lock() and xUnlo
6970: 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a ck() are one of.
6980: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
6990: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e [SQLITE_LOCK_NON
69a0: 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c E],.** <li> [SQL
69b0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d ITE_LOCK_SHARED]
69c0: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ,.** <li> [SQLIT
69d0: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d E_LOCK_RESERVED]
69e0: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ,.** <li> [SQLIT
69f0: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c E_LOCK_PENDING],
6a00: 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c or.** <li> [SQL
6a10: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 ITE_LOCK_EXCLUSI
6a20: 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a VE]..** </ul>.**
6a30: 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 xLock() increas
6a40: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e es the lock. xUn
6a50: 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 lock() decreases
6a60: 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 the lock..** Th
6a70: 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 e xCheckReserved
6a80: 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 Lock() method ch
6a90: 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 ecks whether any
6aa0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
6ab0: 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 tion,.** either
6ac0: 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 in this process
6ad0: 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 or in some other
6ae0: 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c process, is hol
6af0: 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c ding a RESERVED,
6b00: 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 .** PENDING, or
6b10: 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f EXCLUSIVE lock o
6b20: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 n the file. It
6b30: 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 returns true.**
6b40: 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 if such a lock e
6b50: 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 xists and false
6b60: 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a otherwise..**.**
6b70: 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f The xFileContro
6b80: 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 l() method is a
6b90: 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 generic interfac
6ba0: 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 e that allows cu
6bb0: 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c stom.** VFS impl
6bc0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 ementations to d
6bd0: 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 irectly control
6be0: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 an open file usi
6bf0: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ng the.** [sqlit
6c00: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
6c10: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 )] interface. T
6c20: 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 he second "op" a
6c30: 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a rgument is an.**
6c40: 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e integer opcode.
6c50: 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 The third argu
6c60: 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 ment is a generi
6c70: 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 c pointer intend
6c80: 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 ed to.** point t
6c90: 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68 o a structure th
6ca0: 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 at may contain a
6cb0: 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 rguments or spac
6cc0: 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a e in which to.**
6cd0: 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 write return va
6ce0: 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c lues. Potential
6cf0: 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 uses for xFileC
6d00: 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 ontrol() might b
6d10: 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 e.** functions t
6d20: 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e o enable blockin
6d30: 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d g locks with tim
6d40: 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 eouts, to change
6d50: 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 the.** locking
6d60: 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 strategy (for ex
6d70: 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 ample to use dot
6d80: 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f -file locks), to
6d90: 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 inquire.** abou
6da0: 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 t the status of
6db0: 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 a lock, or to br
6dc0: 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e eak stale locks.
6dd0: 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 The SQLite.**
6de0: 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c core reserves al
6df0: 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 l opcodes less t
6e00: 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 han 100 for its
6e10: 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 own use..** A [S
6e20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b QLITE_FCNTL_LOCK
6e30: 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 STATE | list of
6e40: 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 opcodes] less th
6e50: 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 an 100 is availa
6e60: 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 ble..** Applicat
6e70: 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 ions that define
6e80: 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 a custom xFileC
6e90: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 ontrol method sh
6ea0: 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 ould use opcodes
6eb0: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e .** greater than
6ec0: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 100 to avoid co
6ed0: 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 nflicts..**.** T
6ee0: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 he xSectorSize()
6ef0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 method returns
6f00: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 the sector size
6f10: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 of the.** device
6f20: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 that underlies
6f30: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 the file. The s
6f40: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 ector size is th
6f50: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 e.** minimum wri
6f60: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 te that can be p
6f70: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 erformed without
6f80: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f disturbing.** o
6f90: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 ther bytes in th
6fa0: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 e file. The xDe
6fb0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 viceCharacterist
6fc0: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 ics().** method
6fd0: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 returns a bit ve
6fe0: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 ctor describing
6ff0: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 behaviors of the
7000: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 .** underlying d
7010: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c evice:.**.** <ul
7020: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 >.** <li> [SQLIT
7030: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a E_IOCAP_ATOMIC].
7040: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
7050: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d IOCAP_ATOMIC512]
7060: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
7070: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d _IOCAP_ATOMIC1K]
7080: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
7090: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d _IOCAP_ATOMIC2K]
70a0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
70b0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d _IOCAP_ATOMIC4K]
70c0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
70d0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d _IOCAP_ATOMIC8K]
70e0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
70f0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b _IOCAP_ATOMIC16K
7100: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
7110: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 E_IOCAP_ATOMIC32
7120: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
7130: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 TE_IOCAP_ATOMIC6
7140: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 4K].** <li> [SQL
7150: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 ITE_IOCAP_SAFE_A
7160: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b PPEND].** <li> [
7170: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 SQLITE_IOCAP_SEQ
7180: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c UENTIAL].** </ul
7190: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 >.**.** The SQLI
71a0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 TE_IOCAP_ATOMIC
71b0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 property means t
71c0: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f hat all writes o
71d0: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 f.** any size ar
71e0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 e atomic. The S
71f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
7200: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 ICnnn values.**
7210: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 mean that writes
7220: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 of blocks that
7230: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e are nnn bytes in
7240: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 size and.** are
7250: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 aligned to an a
7260: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 ddress which is
7270: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 an integer multi
7280: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 ple of.** nnn ar
7290: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 e atomic. The S
72a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 QLITE_IOCAP_SAFE
72b0: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 _APPEND value me
72c0: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e ans.** that when
72d0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 data is appende
72e0: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 d to a file, the
72f0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 data is appende
7300: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 d.** first then
7310: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
7320: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 file is extended
7330: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 , never the othe
7340: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e r.** way around.
7350: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 The SQLITE_IOC
7360: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 AP_SEQUENTIAL pr
7370: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 operty means tha
7380: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e t.** information
7390: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 is written to d
73a0: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 isk in the same
73b0: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a order as calls.*
73c0: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a * to xWrite()..*
73d0: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 *.** If xRead()
73e0: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 returns SQLITE_I
73f0: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 OERR_SHORT_READ
7400: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c it must also fil
7410: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 l.** in the unre
7420: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 ad portions of t
7430: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a he buffer with z
7440: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 eros. A VFS tha
7450: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 t.** fails to ze
7460: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 ro-fill short re
7470: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 ads might seem t
7480: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 o work. However
7490: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 ,.** failure to
74a0: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 zero-fill short
74b0: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 reads will event
74c0: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a ually lead to.**
74d0: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 database corrup
74e0: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 tion..*/.typedef
74f0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
7500: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 io_methods sqlit
7510: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 e3_io_methods;.s
7520: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f truct sqlite3_io
7530: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 _methods {. int
7540: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 iVersion;. int
7550: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 (*xClose)(sqlit
7560: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 e3_file*);. int
7570: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 (*xRead)(sqlite
7580: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 3_file*, void*,
7590: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 int iAmt, sqlite
75a0: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 3_int64 iOfst);.
75b0: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 int (*xWrite)(
75c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 sqlite3_file*, c
75d0: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 onst void*, int
75e0: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e iAmt, sqlite3_in
75f0: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e t64 iOfst);. in
7600: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 t (*xTruncate)(s
7610: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 qlite3_file*, sq
7620: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 lite3_int64 size
7630: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 );. int (*xSync
7640: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
7650: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 int flags);. i
7660: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 nt (*xFileSize)(
7670: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 sqlite3_file*, s
7680: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 qlite3_int64 *pS
7690: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c ize);. int (*xL
76a0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ock)(sqlite3_fil
76b0: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 e*, int);. int
76c0: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 (*xUnlock)(sqlit
76d0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a e3_file*, int);.
76e0: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 int (*xCheckRe
76f0: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 servedLock)(sqli
7700: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a te3_file*, int *
7710: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 pResOut);. int
7720: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 (*xFileControl)(
7730: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
7740: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 nt op, void *pAr
7750: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 g);. int (*xSec
7760: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 torSize)(sqlite3
7770: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 _file*);. int (
7780: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 *xDeviceCharacte
7790: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 ristics)(sqlite3
77a0: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41 64 _file*);. /* Ad
77b0: 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 ditional methods
77c0: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e may be added in
77d0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
77e0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.};../*.** CA
77f0: 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 PI3REF: Standard
7800: 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 File Control Op
7810: 63 6f 64 65 73 20 7b 48 31 31 33 31 30 7d 20 3c codes {H11310} <
7820: 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S30800>.**.** Th
7830: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 ese integer cons
7840: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 tants are opcode
7850: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 s for the xFileC
7860: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a ontrol method.**
7870: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
7880: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a _io_methods] obj
7890: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 ect and for the
78a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
78b0: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 ntrol()].** inte
78c0: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 rface..**.** The
78d0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c [SQLITE_FCNTL_L
78e0: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 OCKSTATE] opcode
78f0: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 is used for deb
7900: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a ugging. This.**
7910: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 opcode causes t
7920: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 he xFileControl
7930: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 method to write
7940: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 the current stat
7950: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b e of.** the lock
7960: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 (one of [SQLITE
7970: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 _LOCK_NONE], [SQ
7980: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 LITE_LOCK_SHARED
7990: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f ],.** [SQLITE_LO
79a0: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 CK_RESERVED], [S
79b0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 QLITE_LOCK_PENDI
79c0: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f NG], or [SQLITE_
79d0: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 LOCK_EXCLUSIVE])
79e0: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 .** into an inte
79f0: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72 ger that the pAr
7a00: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 g argument point
7a10: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 s to. This capab
7a20: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 ility.** is used
7a30: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 during testing
7a40: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 and only needs t
7a50: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 o be supported w
7a60: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a hen SQLITE_TEST.
7a70: 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a ** is defined..*
7a80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
7a90: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 _FCNTL_LOCKSTATE
7aa0: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 1.#defin
7ab0: 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 e SQLITE_GET_LOC
7ac0: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 KPROXYFILE
7ad0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
7ae0: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 _SET_LOCKPROXYFI
7af0: 4c 45 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e LE 3.#defin
7b00: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 e SQLITE_LAST_ER
7b10: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 RNO
7b20: 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 4../*.** CAPI3RE
7b30: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 20 F: Mutex Handle
7b40: 7b 48 31 37 31 31 30 7d 20 3c 53 32 30 31 33 30 {H17110} <S20130
7b50: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 >.**.** The mute
7b60: 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 x module within
7b70: 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b SQLite defines [
7b80: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 sqlite3_mutex] t
7b90: 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 o be an.** abstr
7ba0: 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d act type for a m
7bb0: 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 utex object. Th
7bc0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 e SQLite core ne
7bd0: 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 ver looks.** at
7be0: 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 the internal rep
7bf0: 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 resentation of a
7c00: 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 n [sqlite3_mutex
7c10: 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 ]. It only.** d
7c20: 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 eals with pointe
7c30: 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 rs to the [sqlit
7c40: 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 e3_mutex] object
7c50: 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 ..**.** Mutexes
7c60: 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e are created usin
7c70: 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 g [sqlite3_mutex
7c80: 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 _alloc()]..*/.ty
7c90: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
7ca0: 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 ite3_mutex sqlit
7cb0: 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a e3_mutex;../*.**
7cc0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e CAPI3REF: OS In
7cd0: 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 20 7b terface Object {
7ce0: 48 31 31 31 34 30 7d 20 3c 53 32 30 31 30 30 3e H11140} <S20100>
7cf0: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e .**.** An instan
7d00: 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 ce of the sqlite
7d10: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 3_vfs object def
7d20: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 ines the interfa
7d30: 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 ce between.** th
7d40: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e e SQLite core an
7d50: 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 d the underlying
7d60: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 operating syste
7d70: 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a m. The "vfs".**
7d80: 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 in the name of
7d90: 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 the object stand
7da0: 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 s for "virtual f
7db0: 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a ile system"..**.
7dc0: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 ** The value of
7dd0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 the iVersion fie
7de0: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 ld is initially
7df0: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 1 but may be lar
7e00: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 ger in.** future
7e10: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
7e20: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c ite. Additional
7e30: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 fields may be a
7e40: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a ppended to this.
7e50: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 ** object when t
7e60: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 he iVersion valu
7e70: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 e is increased.
7e80: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 Note that the s
7e90: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 tructure.** of t
7ea0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f he sqlite3_vfs o
7eb0: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e bject changes in
7ec0: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e the transaction
7ed0: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 between.** SQLi
7ee0: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 te version 3.5.9
7ef0: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 and 3.6.0 and y
7f00: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 et the iVersion
7f10: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a field was not.**
7f20: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a modified..**.**
7f30: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 The szOsFile fi
7f40: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 eld is the size
7f50: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 of the subclasse
7f60: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d d [sqlite3_file]
7f70: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 .** structure us
7f80: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 ed by this VFS.
7f90: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 mxPathname is t
7fa0: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 he maximum lengt
7fb0: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 h of.** a pathna
7fc0: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a me in this VFS..
7fd0: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 **.** Registered
7fe0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a sqlite3_vfs obj
7ff0: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e ects are kept on
8000: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 a linked list f
8010: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 ormed by.** the
8020: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 pNext pointer.
8030: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 The [sqlite3_vfs
8040: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 _register()].**
8050: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 and [sqlite3_vfs
8060: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 _unregister()] i
8070: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 nterfaces manage
8080: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e this list.** in
8090: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 a thread-safe w
80a0: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 ay. The [sqlite
80b0: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 3_vfs_find()] in
80c0: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 terface.** searc
80d0: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e hes the list. N
80e0: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 either the appli
80f0: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 cation code nor
8100: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 the VFS.** imple
8110: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 mentation should
8120: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 use the pNext p
8130: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 ointer..**.** Th
8140: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 e pNext field is
8150: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 the only field
8160: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 in the sqlite3_v
8170: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 fs.** structure
8180: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c that SQLite will
8190: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 ever modify. S
81a0: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 QLite will only
81b0: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 access.** or mod
81c0: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 ify this field w
81d0: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 hile holding a p
81e0: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 articular static
81f0: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 mutex..** The a
8200: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
8210: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 d never modify a
8220: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 nything within t
8230: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a he sqlite3_vfs.*
8240: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 * object once th
8250: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 e object has bee
8260: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a n registered..**
8270: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 .** The zName fi
8280: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 eld holds the na
8290: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f me of the VFS mo
82a0: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 dule. The name
82b0: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 must.** be uniqu
82c0: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 e across all VFS
82d0: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 modules..**.**
82e0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 67 75 61 72 SQLite will guar
82f0: 61 6e 74 65 65 20 74 68 61 74 20 74 68 65 20 7a antee that the z
8300: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 Filename paramet
8310: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 er to xOpen.** i
8320: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 s either a NULL
8330: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e pointer or strin
8340: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 g obtained.** fr
8350: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 om xFullPathname
8360: 28 29 2e 20 20 53 51 4c 69 74 65 20 66 75 72 74 (). SQLite furt
8370: 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 her guarantees t
8380: 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e hat.** the strin
8390: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 g will be valid
83a0: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e and unchanged un
83b0: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a til xClose() is.
83c0: 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 ** called. Becau
83d0: 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f se of the previo
83e0: 75 73 20 73 65 6e 74 65 6e 73 65 2c 0a 2a 2a 20 us sentense,.**
83f0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c the [sqlite3_fil
8400: 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 e] can safely st
8410: 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f ore a pointer to
8420: 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 the.** filename
8430: 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 if it needs to
8440: 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c remember the fil
8450: 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 ename for some r
8460: 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 eason..** If the
8470: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d zFilename param
8480: 65 74 65 72 20 69 73 20 78 4f 70 65 6e 20 69 73 eter is xOpen is
8490: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
84a0: 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 then xOpen.** mu
84b0: 73 74 20 69 6e 76 69 74 65 20 69 74 73 20 6f 77 st invite its ow
84c0: 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 n temporary name
84d0: 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 for the file.
84e0: 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a Whenever the .**
84f0: 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d xFilename param
8500: 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 eter is NULL it
8510: 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 will also be the
8520: 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a case that the.*
8530: 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 * flags paramete
8540: 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b r will include [
8550: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 SQLITE_OPEN_DELE
8560: 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a TEONCLOSE]..**.*
8570: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 * The flags argu
8580: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 ment to xOpen()
8590: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 includes all bit
85a0: 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 s set in.** the
85b0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 flags argument t
85c0: 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f o [sqlite3_open_
85d0: 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 v2()]. Or if [s
85e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a qlite3_open()].*
85f0: 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 * or [sqlite3_op
8600: 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c en16()] is used,
8610: 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c then flags incl
8620: 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a udes at least.**
8630: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 [SQLITE_OPEN_RE
8640: 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 ADWRITE] | [SQLI
8650: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e TE_OPEN_CREATE].
8660: 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 .** If xOpen()
8670: 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 opens a file rea
8680: 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 d-only then it s
8690: 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 ets *pOutFlags t
86a0: 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 o.** include [SQ
86b0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e LITE_OPEN_READON
86c0: 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 LY]. Other bits
86d0: 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d in *pOutFlags m
86e0: 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a ay be set..**.**
86f0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 SQLite will als
8700: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 o add one of the
8710: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 following flags
8720: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a to the xOpen().
8730: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 ** call, dependi
8740: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 ng on the object
8750: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a being opened:.*
8760: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
8770: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
8780: 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e MAIN_DB].** <li>
8790: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d [SQLITE_OPEN_M
87a0: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 AIN_JOURNAL].**
87b0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
87c0: 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c EN_TEMP_DB].** <
87d0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
87e0: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a N_TEMP_JOURNAL].
87f0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
8800: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f _OPEN_TRANSIENT_
8810: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 DB].** <li> [SQ
8820: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 LITE_OPEN_SUBJOU
8830: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b RNAL].** <li> [
8840: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 SQLITE_OPEN_MAST
8850: 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c ER_JOURNAL].** <
8860: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 /ul>.**.** The f
8870: 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e ile I/O implemen
8880: 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 tation can use t
8890: 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 he object type f
88a0: 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 lags to.** chang
88b0: 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 e the way it dea
88c0: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 ls with files.
88d0: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 For example, an
88e0: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 application.** t
88f0: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 hat does not car
8900: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 e about crash re
8910: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 covery or rollba
8920: 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a ck might make.**
8930: 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a the open of a j
8940: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f ournal file a no
8950: 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 -op. Writes to
8960: 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 this journal wou
8970: 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f ld.** also be no
8980: 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 -ops, and any at
8990: 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 tempt to read th
89a0: 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 e journal would
89b0: 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 return.** SQLITE
89c0: 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 _IOERR. Or the
89d0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d implementation m
89e0: 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 ight recognize t
89f0: 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a hat a database.*
8a00: 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 * file will be d
8a10: 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 oing page-aligne
8a20: 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 d sector reads a
8a30: 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 nd writes in a r
8a40: 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 andom.** order a
8a50: 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f nd set up its I/
8a60: 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f O subsystem acco
8a70: 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 rdingly..**.** S
8a80: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f QLite might also
8a90: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 add one of the
8aa0: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 following flags
8ab0: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 to the xOpen met
8ac0: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a hod:.**.** <ul>.
8ad0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
8ae0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f OPEN_DELETEONCLO
8af0: 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c SE].** <li> [SQL
8b00: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 ITE_OPEN_EXCLUSI
8b10: 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a VE].** </ul>.**.
8b20: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f ** The [SQLITE_O
8b30: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 PEN_DELETEONCLOS
8b40: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 E] flag means th
8b50: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 e file should be
8b60: 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e .** deleted when
8b70: 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 it is closed.
8b80: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e The [SQLITE_OPEN
8b90: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a _DELETEONCLOSE].
8ba0: 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 ** will be set f
8bb0: 6f 72 20 54 45 4d 50 20 20 64 61 74 61 62 61 73 or TEMP databas
8bc0: 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 61 6e 64 es, journals and
8bd0: 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61 6c 73 for subjournals
8be0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c ..**.** The [SQL
8bf0: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 ITE_OPEN_EXCLUSI
8c00: 56 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 VE] flag means t
8c10: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 he file should b
8c20: 65 20 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f 72 20 e opened.** for
8c30: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 exclusive access
8c40: 2e 20 20 54 68 69 73 20 66 6c 61 67 20 69 73 20 . This flag is
8c50: 73 65 74 20 66 6f 72 20 61 6c 6c 20 66 69 6c 65 set for all file
8c60: 73 20 65 78 63 65 70 74 0a 2a 2a 20 66 6f 72 20 s except.** for
8c70: 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 the main databas
8c80: 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41 74 e file..**.** At
8c90: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 least szOsFile
8ca0: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 bytes of memory
8cb0: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 are allocated by
8cc0: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f SQLite.** to ho
8cd0: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 ld the [sqlite3
8ce0: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 _file] structure
8cf0: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 passed as the t
8d00: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 hird.** argument
8d10: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 to xOpen. The
8d20: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 xOpen method doe
8d30: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a s not have to.**
8d40: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 allocate the st
8d50: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 ructure; it shou
8d60: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 ld just fill it
8d70: 69 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c in..**.** The fl
8d80: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ags argument to
8d90: 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 xAccess() may be
8da0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f [SQLITE_ACCESS_
8db0: 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 EXISTS].** to te
8dc0: 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 st for the exist
8dd0: 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 ence of a file,
8de0: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 or [SQLITE_ACCES
8df0: 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a S_READWRITE] to.
8e00: 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 ** test whether
8e10: 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 a file is readab
8e20: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c le and writable,
8e30: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 or [SQLITE_ACCE
8e40: 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 SS_READ].** to t
8e50: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 est whether a fi
8e60: 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 le is at least r
8e70: 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 eadable. The f
8e80: 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 ile can be a.**
8e90: 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a directory..**.**
8ea0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 SQLite will alw
8eb0: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 ays allocate at
8ec0: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 least mxPathname
8ed0: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 +1 bytes for the
8ee0: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 .** output buffe
8ef0: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e r xFullPathname.
8f00: 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 The exact size
8f10: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 of the output b
8f20: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f uffer.** is also
8f30: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 passed as a par
8f40: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 ameter to both
8f50: 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 methods. If the
8f60: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a output buffer.**
8f70: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e is not large en
8f80: 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 ough, [SQLITE_CA
8f90: 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 NTOPEN] should b
8fa0: 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 e returned. Sinc
8fb0: 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e e this is.** han
8fc0: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 dled as a fatal
8fd0: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c error by SQLite,
8fe0: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 vfs implementat
8ff0: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 ions should ende
9000: 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 avor.** to preve
9010: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 nt this by setti
9020: 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f ng mxPathname to
9030: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 a sufficiently
9040: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a large value..**.
9050: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 ** The xRandomne
9060: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 ss(), xSleep(),
9070: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 and xCurrentTime
9080: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a () interfaces.**
9090: 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c are not strictl
90a0: 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 y a part of the
90b0: 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 filesystem, but
90c0: 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c they are.** incl
90d0: 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 uded in the VFS
90e0: 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f structure for co
90f0: 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 mpleteness..** T
9100: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 he xRandomness()
9110: 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 function attemp
9120: 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 ts to return nBy
9130: 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 tes bytes.** of
9140: 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e good-quality ran
9150: 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 domness into zOu
9160: 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 t. The return v
9170: 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 alue is.** the a
9180: 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 ctual number of
9190: 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e bytes of randomn
91a0: 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a ess obtained..**
91b0: 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 The xSleep() me
91c0: 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 thod causes the
91d0: 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 calling thread t
91e0: 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a o sleep for at.*
91f0: 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 * least the numb
9200: 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e er of microsecon
9210: 64 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78 ds given. The x
9220: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a CurrentTime().**
9230: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 method returns
9240: 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d a Julian Day Num
9250: 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 ber for the curr
9260: 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d ent date and tim
9270: 65 2e 0a 2a 2a 0a 2a 2f 0a 74 79 70 65 64 65 66 e..**.*/.typedef
9280: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
9290: 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b vfs sqlite3_vfs;
92a0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
92b0: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 vfs {. int iVer
92c0: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 sion;
92d0: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 /* Structure ve
92e0: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a rsion number */.
92f0: 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 int szOsFile;
9300: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 /* Si
9310: 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 ze of subclassed
9320: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f sqlite3_file */
9330: 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d . int mxPathnam
9340: 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d e; /* M
9350: 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 aximum file path
9360: 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 name length */.
9370: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e sqlite3_vfs *pN
9380: 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 ext; /* Nex
9390: 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 t registered VFS
93a0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
93b0: 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f *zName; /
93c0: 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 * Name of this v
93d0: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 irtual file syst
93e0: 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 em */. void *pA
93f0: 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 ppData;
9400: 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 /* Pointer to a
9410: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 pplication-speci
9420: 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e fic data */. in
9430: 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 t (*xOpen)(sqlit
9440: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 e3_vfs*, const c
9450: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 har *zName, sqli
9460: 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 te3_file*,.
9470: 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c int fl
9480: 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c ags, int *pOutFl
9490: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 ags);. int (*xD
94a0: 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 elete)(sqlite3_v
94b0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 fs*, const char
94c0: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 *zName, int sync
94d0: 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 Dir);. int (*xA
94e0: 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 ccess)(sqlite3_v
94f0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 fs*, const char
9500: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 *zName, int flag
9510: 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 s, int *pResOut)
9520: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 ;. int (*xFullP
9530: 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 athname)(sqlite3
9540: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
9550: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f r *zName, int nO
9560: 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b ut, char *zOut);
9570: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 . void *(*xDlOp
9580: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a en)(sqlite3_vfs*
9590: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 , const char *zF
95a0: 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 ilename);. void
95b0: 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c (*xDlError)(sql
95c0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e ite3_vfs*, int n
95d0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 Byte, char *zErr
95e0: 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 Msg);. void (*(
95f0: 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 *xDlSym)(sqlite3
9600: 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e _vfs*,void*, con
9610: 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c st char *zSymbol
9620: 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 ))(void);. void
9630: 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c (*xDlClose)(sql
9640: 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a ite3_vfs*, void*
9650: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 );. int (*xRand
9660: 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f omness)(sqlite3_
9670: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c vfs*, int nByte,
9680: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 char *zOut);.
9690: 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 int (*xSleep)(sq
96a0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 lite3_vfs*, int
96b0: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 microseconds);.
96c0: 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 int (*xCurrentT
96d0: 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ime)(sqlite3_vfs
96e0: 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 *, double*);. i
96f0: 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 nt (*xGetLastErr
9700: 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a or)(sqlite3_vfs*
9710: 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a , int, char *);.
9720: 20 20 2f 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 /* New fields
9730: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 may be appended
9740: 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f in figure versio
9750: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f ns. The iVersio
9760: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c n. ** value wil
9770: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e l increment when
9780: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e ever this happen
9790: 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 s. */.};../*.**
97a0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 CAPI3REF: Flags
97b0: 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20 for the xAccess
97c0: 56 46 53 20 6d 65 74 68 6f 64 20 7b 48 31 31 31 VFS method {H111
97d0: 39 30 7d 20 3c 48 31 31 31 34 30 3e 0a 2a 2a 0a 90} <H11140>.**.
97e0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 ** These integer
97f0: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 constants can b
9800: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 e used as the th
9810: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ird parameter to
9820: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 .** the xAccess
9830: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 method of an [sq
9840: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 lite3_vfs] objec
9850: 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65 79 20 64 t. {END} They d
9860: 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 etermine.** what
9870: 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 kind of permiss
9880: 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 ions the xAccess
9890: 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 method is looki
98a0: 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 ng for..** With
98b0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 SQLITE_ACCESS_EX
98c0: 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 ISTS, the xAcces
98d0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 s method.** simp
98e0: 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 ly checks whethe
98f0: 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 r the file exist
9900: 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 s..** With SQLIT
9910: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 E_ACCESS_READWRI
9920: 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 TE, the xAccess
9930: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 method.** checks
9940: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c whether the fil
9950: 65 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 e is both readab
9960: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e le and writable.
9970: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f .** With SQLITE_
9980: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 ACCESS_READ, the
9990: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a xAccess method.
99a0: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 ** checks whethe
99b0: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 r the file is re
99c0: 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 adable..*/.#defi
99d0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 ne SQLITE_ACCESS
99e0: 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 _EXISTS 0.#de
99f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 fine SQLITE_ACCE
9a00: 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23 SS_READWRITE 1.#
9a10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 define SQLITE_AC
9a20: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 CESS_READ 2
9a30: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
9a40: 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 : Initialize The
9a50: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 SQLite Library
9a60: 7b 48 31 30 31 33 30 7d 20 3c 53 32 30 30 30 30 {H10130} <S20000
9a70: 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 ><S30100>.**.**
9a80: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 The sqlite3_init
9a90: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 ialize() routine
9aa0: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 initializes the
9ab0: 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 .** SQLite libra
9ac0: 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 ry. The sqlite3
9ad0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 _shutdown() rout
9ae0: 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 ine.** deallocat
9af0: 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 es any resources
9b00: 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 that were alloc
9b10: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f ated by sqlite3_
9b20: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a initialize()..**
9b30: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 .** A call to sq
9b40: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
9b50: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 () is an "effect
9b60: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 ive" call if it
9b70: 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 is.** the first
9b80: 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 time sqlite3_ini
9b90: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 tialize() is inv
9ba0: 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 oked during the
9bb0: 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 lifetime of.** t
9bc0: 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 he process, or i
9bd0: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 f it is the firs
9be0: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 t time sqlite3_i
9bf0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 nitialize() is i
9c00: 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 nvoked.** follow
9c10: 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 ing a call to sq
9c20: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
9c30: 2e 20 20 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 . Only an effec
9c40: 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 tive call.** of
9c50: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
9c60: 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e ze() does any in
9c70: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 itialization. A
9c80: 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a ll other calls.*
9c90: 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e * are harmless n
9ca0: 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f o-ops..**.** Amo
9cb0: 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c ng other things,
9cc0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
9cd0: 69 7a 65 28 29 20 73 68 61 6c 6c 20 69 6e 76 6f ize() shall invo
9ce0: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 ke.** sqlite3_os
9cf0: 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 _init(). Simila
9d00: 72 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 68 75 rly, sqlite3_shu
9d10: 74 64 6f 77 6e 28 29 0a 2a 2a 20 73 68 61 6c 6c tdown().** shall
9d20: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f invoke sqlite3_
9d30: 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 os_end()..**.**
9d40: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 The sqlite3_init
9d50: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 ialize() routine
9d60: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
9d70: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e _OK] on success.
9d80: 0a 2a 2a 20 49 66 20 66 6f 72 20 73 6f 6d 65 20 .** If for some
9d90: 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f reason, sqlite3_
9da0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 initialize() is
9db0: 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 unable to initia
9dc0: 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 lize.** the libr
9dd0: 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 ary (perhaps it
9de0: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c is unable to all
9df0: 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 ocate a needed r
9e00: 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 esource such.**
9e10: 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 as a mutex) it r
9e20: 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 eturns an [error
9e30: 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 code] other tha
9e40: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a n [SQLITE_OK]..*
9e50: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
9e60: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f _initialize() ro
9e70: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 utine is called
9e80: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 internally by ma
9e90: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 ny other.** SQLi
9ea0: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f te interfaces so
9eb0: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 that an applica
9ec0: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 tion usually doe
9ed0: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a s not need to.**
9ee0: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f invoke sqlite3_
9ef0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 initialize() dir
9f00: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d ectly. For exam
9f10: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ple, [sqlite3_op
9f20: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 en()].** calls s
9f30: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
9f40: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 e() so the SQLit
9f50: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 e library will b
9f60: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a e automatically.
9f70: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 ** initialized w
9f80: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 hen [sqlite3_ope
9f90: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 n()] is called i
9fa0: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 f it has not be
9fb0: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 initialized.** a
9fc0: 6c 72 65 61 64 79 2e 20 20 48 6f 77 65 76 65 72 lready. However
9fd0: 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 , if SQLite is c
9fe0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 ompiled with the
9ff0: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 [SQLITE_OMIT_AU
a000: 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 TOINIT].** compi
a010: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 le-time option,
a020: 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 then the automat
a030: 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 ic calls to sqli
a040: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
a050: 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 .** are omitted
a060: 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 and the applicat
a070: 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 ion must call sq
a080: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
a090: 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 () directly.** p
a0a0: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e rior to using an
a0b0: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 y other SQLite i
a0c0: 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d nterface. For m
a0d0: 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 aximum portabili
a0e0: 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 ty,.** it is rec
a0f0: 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 ommended that ap
a100: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 plications alway
a110: 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 s invoke sqlite3
a120: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a _initialize().**
a130: 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 directly prior
a140: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 to using any oth
a150: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 er SQLite interf
a160: 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c ace. Future rel
a170: 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 eases.** of SQLi
a180: 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 te may require t
a190: 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 his. In other w
a1a0: 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 ords, the behavi
a1b0: 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 or exhibited.**
a1c0: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 when SQLite is c
a1d0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 ompiled with [SQ
a1e0: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e LITE_OMIT_AUTOIN
a1f0: 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 IT] might become
a200: 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 the.** default
a210: 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 behavior in some
a220: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 future release
a230: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a of SQLite..**.**
a240: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f The sqlite3_os_
a250: 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 init() routine d
a260: 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 oes operating-sy
a270: 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a stem specific.**
a280: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 initialization
a290: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 of the SQLite li
a2a0: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 brary. The sqli
a2b0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 te3_os_end().**
a2c0: 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 routine undoes t
a2d0: 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c he effect of sql
a2e0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 ite3_os_init().
a2f0: 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a Typical tasks.*
a300: 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 * performed by t
a310: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e hese routines in
a320: 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e clude allocation
a330: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e or deallocation
a340: 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 .** of static re
a350: 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c sources, initial
a360: 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 ization of globa
a370: 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 l variables,.**
a380: 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 setting up a def
a390: 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 ault [sqlite3_vf
a3a0: 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 s] module, or se
a3b0: 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 tting up.** a de
a3c0: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 fault configurat
a3d0: 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ion using [sqlit
a3e0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a e3_config()]..**
a3f0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
a400: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 ion should never
a410: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 invoke either s
a420: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
a430: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f .** or sqlite3_o
a440: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 s_end() directly
a450: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 . The applicati
a460: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 on should only i
a470: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 nvoke.** sqlite3
a480: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e _initialize() an
a490: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f d sqlite3_shutdo
a4a0: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 wn(). The sqlit
a4b0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 e3_os_init().**
a4c0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c interface is cal
a4d0: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c led automaticall
a4e0: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 y by sqlite3_ini
a4f0: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a tialize() and.**
a500: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
a510: 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 ) is called by s
a520: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
a530: 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a ). Appropriate.
a540: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
a550: 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f ns for sqlite3_o
a560: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c s_init() and sql
a570: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a ite3_os_end().**
a580: 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 are built into
a590: 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 SQLite when it i
a5a0: 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 75 s compiled for u
a5b0: 6e 69 78 2c 20 77 69 6e 64 6f 77 73 2c 20 6f 72 nix, windows, or
a5c0: 20 6f 73 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 62 os/2..** When b
a5d0: 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 uilt for other p
a5e0: 6c 61 74 66 6f 72 6d 73 20 28 75 73 69 6e 67 20 latforms (using
a5f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f the [SQLITE_OS_O
a600: 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d THER=1] compile-
a610: 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 time.** option)
a620: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
a630: 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 must supply a su
a640: 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 itable implement
a650: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c ation for.** sql
a660: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 ite3_os_init() a
a670: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e nd sqlite3_os_en
a680: 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 d(). An applica
a690: 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a tion-supplied.**
a6a0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
a6b0: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e of sqlite3_os_in
a6c0: 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f it() or sqlite3_
a6d0: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 os_end().** must
a6e0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
a6f0: 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 OK] on success a
a700: 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 nd some other [e
a710: 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a rror code] upon.
a720: 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 ** failure..*/.i
a730: 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 nt sqlite3_initi
a740: 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 alize(void);.int
a750: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
a760: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c n(void);.int sql
a770: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 ite3_os_init(voi
a780: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f d);.int sqlite3_
a790: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f os_end(void);../
a7a0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
a7b0: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 onfiguring The S
a7c0: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b 48 QLite Library {H
a7d0: 31 34 31 30 30 7d 20 3c 53 32 30 30 30 30 3e 3c 14100} <S20000><
a7e0: 53 33 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 S30200>.** EXPER
a7f0: 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 IMENTAL.**.** Th
a800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 e sqlite3_config
a810: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
a820: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f used to make glo
a830: 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f bal configuratio
a840: 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 n.** changes to
a850: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 SQLite in order
a860: 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 to tune SQLite t
a870: 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e o the specific n
a880: 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 eeds of.** the a
a890: 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 pplication. The
a8a0: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 default configu
a8b0: 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d ration is recomm
a8c0: 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a ended for most.*
a8d0: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 * applications a
a8e0: 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 nd so this routi
a8f0: 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f ne is usually no
a900: 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 t necessary. It
a910: 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 is.** provided
a920: 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 to support rare
a930: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 applications wit
a940: 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e h unusual needs.
a950: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
a960: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 e3_config() inte
a970: 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 rface is not thr
a980: 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 eadsafe. The ap
a990: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 plication.** mus
a9a0: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f t insure that no
a9b0: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e other SQLite in
a9c0: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 terfaces are inv
a9d0: 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a oked by other.**
a9e0: 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 threads while s
a9f0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
aa00: 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 is running. Fur
aa10: 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 thermore, sqlite
aa20: 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 3_config().** ma
aa30: 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 y only be invoke
aa40: 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 d prior to libra
aa50: 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f ry initializatio
aa60: 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 n using.** [sqli
aa70: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
aa80: 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 ] or after shutd
aa90: 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f own by [sqlite3_
aaa0: 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 shutdown()]..**
aab0: 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 Note, however, t
aac0: 68 61 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 hat sqlite3_conf
aad0: 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c ig() can be call
aae0: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 ed as part of th
aaf0: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e.** implementat
ab00: 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 ion of an applic
ab10: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 ation-defined [s
ab20: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
ab30: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 ]..**.** The fir
ab40: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 st argument to s
ab50: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
ab60: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a is an integer.**
ab70: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
ab80: 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63 SINGLETHREAD | c
ab90: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
aba0: 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d ion] that determ
abb0: 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f ines.** what pro
abc0: 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 perty of SQLite
abd0: 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 is to be configu
abe0: 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 red. Subsequent
abf0: 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 arguments.** va
ac00: 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 ry depending on
ac10: 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 the [SQLITE_CONF
ac20: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 IG_SINGLETHREAD
ac30: 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 | configuration
ac40: 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 option].** in th
ac50: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
ac60: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 63 ..**.** When a c
ac70: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
ac80: 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 ion is set, sqli
ac90: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 te3_config() ret
aca0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d urns [SQLITE_OK]
acb0: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 74 69 ..** If the opti
acc0: 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 on is unknown or
acd0: 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c SQLite is unabl
ace0: 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 e to set the opt
acf0: 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 ion.** then this
ad00: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
ad10: 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 a non-zero [err
ad20: 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 or code]..**.**
ad30: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
ad40: 2a 20 7b 48 31 34 31 30 33 7d 20 41 20 73 75 63 * {H14103} A suc
ad50: 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 cessful invocati
ad60: 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 63 on of [sqlite3_c
ad70: 6f 6e 66 69 67 28 29 5d 20 73 68 61 6c 6c 20 72 onfig()] shall r
ad80: 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 eturn.**
ad90: 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a [SQLITE_OK]..*
ada0: 2a 0a 2a 2a 20 7b 48 31 34 31 30 36 7d 20 54 68 *.** {H14106} Th
adb0: 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 e [sqlite3_confi
adc0: 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 g()] interface s
add0: 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c hall return [SQL
ade0: 49 54 45 5f 4d 49 53 55 53 45 5d 0a 2a 2a 20 20 ITE_MISUSE].**
adf0: 20 20 20 20 20 20 20 20 69 66 20 69 74 20 69 73 if it is
ae00: 20 69 6e 76 6f 6b 65 64 20 69 6e 20 62 65 74 77 invoked in betw
ae10: 65 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 een calls to [sq
ae20: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
ae30: 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 ()] and.**
ae40: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 [sqlite3_shu
ae50: 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 tdown()]..**.**
ae60: 7b 48 31 34 31 32 30 7d 20 41 20 73 75 63 63 65 {H14120} A succe
ae70: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 ssful call to [s
ae80: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b qlite3_config]([
ae90: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 SQLITE_CONFIG_SI
aea0: 4e 47 4c 45 54 48 52 45 41 44 5d 29 0a 2a 2a 20 NGLETHREAD]).**
aeb0: 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 73 shall s
aec0: 65 74 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b et the default [
aed0: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
aee0: 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 to Single-thread
aef0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 32 33 7d ..**.** {H14123}
af00: 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 A successful ca
af10: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ll to [sqlite3_c
af20: 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 onfig]([SQLITE_C
af30: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 ONFIG_MULTITHREA
af40: 44 5d 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 D]).**
af50: 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 64 65 shall set the de
af60: 66 61 75 6c 74 20 5b 74 68 72 65 61 64 69 6e 67 fault [threading
af70: 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d mode] to Multi-
af80: 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 thread..**.** {H
af90: 31 34 31 32 36 7d 20 41 20 73 75 63 63 65 73 73 14126} A success
afa0: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ful call to [sql
afb0: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 ite3_config]([SQ
afc0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 LITE_CONFIG_SERI
afd0: 41 4c 49 5a 45 44 5d 29 0a 2a 2a 20 20 20 20 20 ALIZED]).**
afe0: 20 20 20 20 20 73 68 61 6c 6c 20 73 65 74 20 74 shall set t
aff0: 68 65 20 64 65 66 61 75 6c 74 20 5b 74 68 72 65 he default [thre
b000: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 ading mode] to S
b010: 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a erialized..**.**
b020: 20 7b 48 31 34 31 32 39 7d 20 41 20 73 75 63 63 {H14129} A succ
b030: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b essful call to [
b040: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 sqlite3_config](
b050: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
b060: 55 54 45 58 5d 2c 58 29 0a 2a 2a 20 20 20 20 20 UTEX],X).**
b070: 20 20 20 20 20 77 68 65 72 65 20 58 20 69 73 20 where X is
b080: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
b090: 69 6e 69 74 69 61 6c 69 7a 65 64 20 5b 73 71 6c initialized [sql
b0a0: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
b0b0: 64 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ds].**
b0c0: 6f 62 6a 65 63 74 20 73 68 61 6c 6c 20 63 61 75 object shall cau
b0d0: 73 65 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e se all subsequen
b0e0: 74 20 6d 75 74 65 78 20 6f 70 65 72 61 74 69 6f t mutex operatio
b0f0: 6e 73 20 70 65 72 66 6f 72 6d 65 64 0a 2a 2a 20 ns performed.**
b100: 20 20 20 20 20 20 20 20 20 62 79 20 53 51 4c 69 by SQLi
b110: 74 65 20 74 6f 20 75 73 65 20 74 68 65 20 6d 75 te to use the mu
b120: 74 65 78 20 6d 65 74 68 6f 64 73 20 74 68 61 74 tex methods that
b130: 20 77 65 72 65 20 70 72 65 73 65 6e 74 20 69 6e were present in
b140: 20 58 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 X.** d
b150: 75 72 69 6e 67 20 74 68 65 20 63 61 6c 6c 20 74 uring the call t
b160: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 o [sqlite3_confi
b170: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 g()]..**.** {H14
b180: 31 33 32 7d 20 41 20 73 75 63 63 65 73 73 66 75 132} A successfu
b190: 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 l call to [sqlit
b1a0: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 e3_config]([SQLI
b1b0: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 TE_CONFIG_GETMUT
b1c0: 45 58 5d 2c 58 29 0a 2a 2a 20 20 20 20 20 20 20 EX],X).**
b1d0: 20 20 20 77 68 65 72 65 20 58 20 69 73 20 61 20 where X is a
b1e0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 pointer to an [s
b1f0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
b200: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 0a 2a 2a hods] object .**
b210: 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 shall
b220: 6f 76 65 72 77 72 69 74 65 20 74 68 65 20 63 6f overwrite the co
b230: 6e 74 65 6e 74 20 6f 66 20 5b 73 71 6c 69 74 65 ntent of [sqlite
b240: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 3_mutex_methods]
b250: 20 6f 62 6a 65 63 74 0a 2a 2a 20 20 20 20 20 20 object.**
b260: 20 20 20 20 77 69 74 68 20 74 68 65 20 6d 75 74 with the mut
b270: 65 78 20 6d 65 74 68 6f 64 73 20 63 75 72 72 65 ex methods curre
b280: 6e 74 6c 79 20 69 6e 20 75 73 65 20 62 79 20 53 ntly in use by S
b290: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 QLite..**.** {H1
b2a0: 34 31 33 35 7d 20 41 20 73 75 63 63 65 73 73 66 4135} A successf
b2b0: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 ul call to [sqli
b2c0: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c te3_config]([SQL
b2d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f ITE_CONFIG_MALLO
b2e0: 43 5d 2c 4d 29 0a 2a 2a 20 20 20 20 20 20 20 20 C],M).**
b2f0: 20 20 77 68 65 72 65 20 4d 20 69 73 20 61 20 70 where M is a p
b300: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 69 ointer to an ini
b310: 74 69 61 6c 69 7a 65 64 20 5b 73 71 6c 69 74 65 tialized [sqlite
b320: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 3_mem_methods].*
b330: 2a 20 20 20 20 20 20 20 20 20 20 6f 62 6a 65 63 * objec
b340: 74 20 73 68 61 6c 6c 20 63 61 75 73 65 20 61 6c t shall cause al
b350: 6c 20 73 75 62 73 65 71 75 65 6e 74 20 6d 65 6d l subsequent mem
b360: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f ory allocation o
b370: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 20 20 20 perations.**
b380: 20 20 20 20 20 20 70 65 72 66 6f 72 6d 65 64 20 performed
b390: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 by SQLite to use
b3a0: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 74 68 61 the methods tha
b3b0: 74 20 77 65 72 65 20 70 72 65 73 65 6e 74 20 69 t were present i
b3c0: 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4d n .** M
b3d0: 20 64 75 72 69 6e 67 20 74 68 65 20 63 61 6c 6c during the call
b3e0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e to [sqlite3_con
b3f0: 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 fig()]..**.** {H
b400: 31 34 31 33 38 7d 20 41 20 73 75 63 63 65 73 73 14138} A success
b410: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ful call to [sql
b420: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 ite3_config]([SQ
b430: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
b440: 41 4c 4c 4f 43 5d 2c 4d 29 0a 2a 2a 20 20 20 20 ALLOC],M).**
b450: 20 20 20 20 20 20 77 68 65 72 65 20 4d 20 69 73 where M is
b460: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
b470: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 [sqlite3_mem_me
b480: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 73 68 thods] object sh
b490: 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 all.**
b4a0: 6f 76 65 72 77 72 69 74 65 20 74 68 65 20 63 6f overwrite the co
b4b0: 6e 74 65 6e 74 20 6f 66 20 5b 73 71 6c 69 74 65 ntent of [sqlite
b4c0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 6f 3_mem_methods] o
b4d0: 62 6a 65 63 74 20 77 69 74 68 20 0a 2a 2a 20 20 bject with .**
b4e0: 20 20 20 20 20 20 20 20 74 68 65 20 6d 65 6d 6f the memo
b4f0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6d 65 ry allocation me
b500: 74 68 6f 64 73 20 63 75 72 72 65 6e 74 6c 79 20 thods currently
b510: 69 6e 20 75 73 65 20 62 79 0a 2a 2a 20 20 20 20 in use by.**
b520: 20 20 20 20 20 20 53 51 4c 69 74 65 2e 0a 2a 2a SQLite..**
b530: 0a 2a 2a 20 7b 48 31 34 31 34 31 7d 20 41 20 73 .** {H14141} A s
b540: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 uccessful call t
b550: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 o [sqlite3_confi
b560: 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 g]([SQLITE_CONFI
b570: 47 5f 4d 45 4d 53 54 41 54 55 53 5d 2c 31 29 0a G_MEMSTATUS],1).
b580: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c ** shal
b590: 6c 20 65 6e 61 62 6c 65 20 74 68 65 20 6d 65 6d l enable the mem
b5a0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 ory allocation s
b5b0: 74 61 74 75 73 20 63 6f 6c 6c 65 63 74 69 6f 6e tatus collection
b5c0: 20 6c 6f 67 69 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48 logic..**.** {H
b5d0: 31 34 31 34 34 7d 20 41 20 73 75 63 63 65 73 73 14144} A success
b5e0: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ful call to [sql
b5f0: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 ite3_config]([SQ
b600: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 LITE_CONFIG_MEMS
b610: 54 41 54 55 53 5d 2c 30 29 0a 2a 2a 20 20 20 20 TATUS],0).**
b620: 20 20 20 20 20 20 73 68 61 6c 6c 20 64 69 73 61 shall disa
b630: 62 6c 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 ble the memory a
b640: 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 75 73 llocation status
b650: 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6c 6f 67 69 collection logi
b660: 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 34 37 c..**.** {H14147
b670: 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c } The memory all
b680: 6f 63 61 74 69 6f 6e 20 73 74 61 74 75 73 20 63 ocation status c
b690: 6f 6c 6c 65 63 74 69 6f 6e 20 6c 6f 67 69 63 20 ollection logic
b6a0: 73 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 20 shall be.**
b6b0: 20 20 20 20 20 65 6e 61 62 6c 65 64 20 62 79 20 enabled by
b6c0: 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b default..**.** {
b6d0: 48 31 34 31 35 30 7d 20 41 20 73 75 63 63 65 73 H14150} A succes
b6e0: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 sful call to [sq
b6f0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 lite3_config]([S
b700: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 QLITE_CONFIG_SCR
b710: 41 54 43 48 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20 ATCH],S,Z,N).**
b720: 20 20 20 20 20 20 20 20 20 77 68 65 72 65 20 5a where Z
b730: 20 61 6e 64 20 4e 20 61 72 65 20 6e 6f 6e 2d 6e and N are non-n
b740: 65 67 61 74 69 76 65 20 69 6e 74 65 67 65 72 73 egative integers
b750: 20 61 6e 64 20 0a 2a 2a 20 20 20 20 20 20 20 20 and .**
b760: 20 20 53 20 69 73 20 61 20 70 6f 69 6e 74 65 72 S is a pointer
b770: 20 74 6f 20 61 6e 20 61 6c 69 67 6e 65 64 20 6d to an aligned m
b780: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 6e 6f 74 emory buffer not
b790: 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 less than.**
b7a0: 20 20 20 20 20 20 20 5a 2a 4e 20 62 79 74 65 73 Z*N bytes
b7b0: 20 69 6e 20 73 69 7a 65 20 73 68 61 6c 6c 20 63 in size shall c
b7c0: 61 75 73 65 20 53 20 74 6f 20 62 65 20 75 73 65 ause S to be use
b7d0: 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 d by the.**
b7e0: 20 20 20 20 20 5b 73 63 72 61 74 63 68 20 6d 65 [scratch me
b7f0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 mory allocator]
b800: 66 6f 72 20 61 73 20 6d 61 6e 79 20 61 73 20 4e for as many as N
b810: 20 73 69 6d 75 6c 61 74 61 6e 65 6f 75 73 0a 2a simulataneous.*
b820: 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 * alloc
b830: 61 74 69 6f 6e 73 20 65 61 63 68 20 6f 66 20 73 ations each of s
b840: 69 7a 65 20 28 5a 20 26 20 7e 37 29 2e 0a 2a 2a ize (Z & ~7)..**
b850: 0a 2a 2a 20 7b 48 31 34 31 35 33 7d 20 41 20 73 .** {H14153} A s
b860: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 uccessful call t
b870: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 o [sqlite3_confi
b880: 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 g]([SQLITE_CONFI
b890: 47 5f 53 43 52 41 54 43 48 5d 2c 53 2c 5a 2c 4e G_SCRATCH],S,Z,N
b8a0: 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 ).** wh
b8b0: 65 72 65 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 ere S is a NULL
b8c0: 70 6f 69 6e 74 65 72 20 73 68 61 6c 6c 20 64 69 pointer shall di
b8d0: 73 61 62 6c 65 20 74 68 65 0a 2a 2a 20 20 20 20 sable the.**
b8e0: 20 20 20 20 20 20 5b 73 63 72 61 74 63 68 20 6d [scratch m
b8f0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d emory allocator]
b900: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 35 36 7d ..**.** {H14156}
b910: 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 A successful ca
b920: 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 ll to.**
b930: 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 [sqlite3_confi
b940: 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 g]([SQLITE_CONFI
b950: 47 5f 50 41 47 45 43 41 43 48 45 5d 2c 53 2c 5a G_PAGECACHE],S,Z
b960: 2c 4e 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ,N).**
b970: 77 68 65 72 65 20 5a 20 61 6e 64 20 4e 20 61 72 where Z and N ar
b980: 65 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 69 e non-negative i
b990: 6e 74 65 67 65 72 73 20 61 6e 64 20 0a 2a 2a 20 ntegers and .**
b9a0: 20 20 20 20 20 20 20 20 20 53 20 69 73 20 61 20 S is a
b9b0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 6c pointer to an al
b9c0: 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 igned memory buf
b9d0: 66 65 72 20 6e 6f 74 20 6c 65 73 73 20 74 68 61 fer not less tha
b9e0: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5a 2a n.** Z*
b9f0: 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 N bytes in size
ba00: 73 68 61 6c 6c 20 63 61 75 73 65 20 53 20 74 6f shall cause S to
ba10: 20 62 65 20 75 73 65 64 20 62 79 20 74 68 65 0a be used by the.
ba20: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 61 67 ** [pag
ba30: 65 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c ecache memory al
ba40: 6c 6f 63 61 74 6f 72 5d 20 66 6f 72 20 61 73 20 locator] for as
ba50: 6d 61 6e 79 20 61 73 20 4e 20 73 69 6d 75 6c 61 many as N simula
ba60: 74 61 6e 65 6f 75 73 0a 2a 2a 20 20 20 20 20 20 taneous.**
ba70: 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 allocations
ba80: 65 61 63 68 20 6f 66 20 73 69 7a 65 20 28 5a 20 each of size (Z
ba90: 26 20 7e 37 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 & ~7)..**.** {H1
baa0: 34 31 35 39 7d 20 41 20 73 75 63 63 65 73 73 66 4159} A successf
bab0: 75 6c 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 ul call to.**
bac0: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
bad0: 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f config]([SQLITE_
bae0: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 CONFIG_PAGECACHE
baf0: 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 20 20 ],S,Z,N).**
bb00: 20 20 20 20 20 77 68 65 72 65 20 53 20 69 73 20 where S is
bb10: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 73 a NULL pointer s
bb20: 68 61 6c 6c 20 64 69 73 61 62 6c 65 20 74 68 65 hall disable the
bb30: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 61 .** [pa
bb40: 67 65 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 gecache memory a
bb50: 6c 6c 6f 63 61 74 6f 72 5d 2e 0a 2a 2a 0a 2a 2a llocator]..**.**
bb60: 20 7b 48 31 34 31 36 32 7d 20 41 20 73 75 63 63 {H14162} A succ
bb70: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b essful call to [
bb80: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 sqlite3_config](
bb90: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 [SQLITE_CONFIG_H
bba0: 45 41 50 5d 2c 48 2c 5a 2c 4e 29 0a 2a 2a 20 20 EAP],H,Z,N).**
bbb0: 20 20 20 20 20 20 20 20 77 68 65 72 65 20 5a 20 where Z
bbc0: 61 6e 64 20 4e 20 61 72 65 20 6e 6f 6e 2d 6e 65 and N are non-ne
bbd0: 67 61 74 69 76 65 20 69 6e 74 65 67 65 72 73 20 gative integers
bbe0: 61 6e 64 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 and .**
bbf0: 20 48 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 H is a pointer
bc00: 74 6f 20 61 6e 20 61 6c 69 67 6e 65 64 20 6d 65 to an aligned me
bc10: 6d 6f 72 79 20 62 75 66 66 65 72 20 6e 6f 74 20 mory buffer not
bc20: 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 20 less than.**
bc30: 20 20 20 20 20 20 5a 20 62 79 74 65 73 20 69 6e Z bytes in
bc40: 20 73 69 7a 65 20 73 68 61 6c 6c 20 65 6e 61 62 size shall enab
bc50: 6c 65 20 74 68 65 20 5b 6d 65 6d 73 79 73 35 5d le the [memsys5]
bc60: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
bc70: 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e r.** an
bc80: 64 20 63 61 75 73 65 20 69 74 20 74 6f 20 75 73 d cause it to us
bc90: 65 20 62 75 66 66 65 72 20 53 20 61 73 20 69 74 e buffer S as it
bca0: 73 20 6d 65 6d 6f 72 79 20 73 6f 75 72 63 65 20 s memory source
bcb0: 61 6e 64 20 74 6f 20 75 73 65 0a 2a 2a 20 20 20 and to use.**
bcc0: 20 20 20 20 20 20 20 61 20 6d 69 6e 69 6d 75 6d a minimum
bcd0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 allocation size
bce0: 20 6f 66 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 of N..**.** {H1
bcf0: 34 31 36 35 7d 20 41 20 73 75 63 63 65 73 73 66 4165} A successf
bd00: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 ul call to [sqli
bd10: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c te3_config]([SQL
bd20: 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d ITE_CONFIG_HEAP]
bd30: 2c 48 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 20 20 20 ,H,Z,N).**
bd40: 20 20 20 20 77 68 65 72 65 20 48 20 69 73 20 61 where H is a
bd50: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 73 68 NULL pointer sh
bd60: 61 6c 6c 20 64 69 73 61 62 6c 65 20 74 68 65 0a all disable the.
bd70: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 6d 65 6d ** [mem
bd80: 73 79 73 35 5d 20 6d 65 6d 6f 72 79 20 61 6c 6c sys5] memory all
bd90: 6f 63 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ocator..**.** {H
bda0: 31 34 31 36 38 7d 20 41 20 73 75 63 63 65 73 73 14168} A success
bdb0: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ful call to [sql
bdc0: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 ite3_config]([SQ
bdd0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b LITE_CONFIG_LOOK
bde0: 41 53 49 44 45 5d 2c 5a 2c 4e 29 0a 2a 2a 20 20 ASIDE],Z,N).**
bdf0: 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 63 61 shall ca
be00: 75 73 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 use the default
be10: 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 [lookaside memor
be20: 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e y allocator] con
be30: 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 20 20 figuration.**
be40: 20 20 20 20 20 20 20 66 6f 72 20 6e 65 77 20 5b for new [
be50: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
be60: 69 6f 6e 73 5d 20 74 6f 20 62 65 20 4e 20 73 6c ions] to be N sl
be70: 6f 74 73 20 6f 66 20 5a 20 62 79 74 65 73 20 65 ots of Z bytes e
be80: 61 63 68 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 ach..*/.SQLITE_E
be90: 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 XPERIMENTAL int
bea0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 sqlite3_config(i
beb0: 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a nt, ...);../*.**
bec0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 CAPI3REF: Confi
bed0: 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f gure database co
bee0: 6e 6e 65 63 74 69 6f 6e 73 20 20 7b 48 31 34 32 nnections {H142
bef0: 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 00} <S20000>.**
bf00: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a EXPERIMENTAL.**.
bf10: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 ** The sqlite3_d
bf20: 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 b_config() inter
bf30: 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 face is used to
bf40: 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 make configurati
bf50: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f on.** changes to
bf60: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e a [database con
bf70: 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 nection]. The i
bf80: 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 nterface is simi
bf90: 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 lar to.** [sqlit
bfa0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 e3_config()] exc
bfb0: 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61 ept that the cha
bfc0: 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 nges apply to a
bfd0: 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 single.** [datab
bfe0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
bff0: 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 (specified in th
c000: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
c010: 29 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 ). The.** sqlit
c020: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 e3_db_config() i
c030: 6e 74 65 72 66 61 63 65 20 63 61 6e 20 6f 6e 6c nterface can onl
c040: 79 20 62 65 20 75 73 65 64 20 69 6d 6d 65 64 69 y be used immedi
c050: 61 74 65 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74 ately after.** t
c060: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
c070: 65 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 ection is create
c080: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
c090: 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 _open()],.** [sq
c0a0: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c lite3_open16()],
c0b0: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 or [sqlite3_ope
c0c0: 6e 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a n_v2()]. .**.**
c0d0: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 The second argu
c0e0: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f ment to sqlite3_
c0f0: 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e db_config(D,V,..
c100: 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f .) is the.** co
c110: 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 nfiguration verb
c120: 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f - an integer co
c130: 64 65 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 de that indicate
c140: 73 20 77 68 61 74 0a 2a 2a 20 61 73 70 65 63 74 s what.** aspect
c150: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 of the [databas
c160: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 e connection] is
c170: 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 being configure
c180: 64 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63 d..** The only c
c190: 68 6f 69 63 65 20 66 6f 72 20 74 68 69 73 20 76 hoice for this v
c1a0: 61 6c 75 65 20 69 73 20 5b 53 51 4c 49 54 45 5f alue is [SQLITE_
c1b0: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 DBCONFIG_LOOKASI
c1c0: 44 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62 DE]..** New verb
c1d0: 73 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20 s are likely to
c1e0: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 be added in futu
c1f0: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 re releases of S
c200: 51 4c 69 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69 QLite..** Additi
c210: 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 64 onal arguments d
c220: 65 70 65 6e 64 20 6f 6e 20 74 68 65 20 76 65 72 epend on the ver
c230: 62 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 b..**.** INVARIA
c240: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 32 NTS:.**.** {H142
c250: 30 33 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 03} A call to [s
c260: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
c270: 28 44 2c 56 2c 2e 2e 2e 29 5d 20 73 68 61 6c 6c (D,V,...)] shall
c280: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
c290: 4f 4b 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 OK].**
c2a0: 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 if and only if t
c2b0: 68 65 20 63 61 6c 6c 20 69 73 20 73 75 63 63 65 he call is succe
c2c0: 73 73 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ssful..**.** {H1
c2d0: 34 32 30 36 7d 20 49 66 20 6f 6e 65 20 6f 72 20 4206} If one or
c2e0: 6d 6f 72 65 20 73 6c 6f 74 73 20 6f 66 20 74 68 more slots of th
c2f0: 65 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d e [lookaside mem
c300: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 66 ory allocator] f
c310: 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b or.** [
c320: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
c330: 69 6f 6e 5d 20 44 20 61 72 65 20 69 6e 20 75 73 ion] D are in us
c340: 65 2c 20 74 68 65 6e 20 61 20 63 61 6c 6c 20 74 e, then a call t
c350: 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 o.** [s
c360: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
c370: 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 44 42 43 4f ](D,[SQLITE_DBCO
c380: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c NFIG_LOOKASIDE],
c390: 2e 2e 2e 29 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 ...) shall.**
c3a0: 20 20 20 20 20 20 20 66 61 69 6c 20 77 69 74 68 fail with
c3b0: 20 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 an [SQLITE_BUSY
c3c0: 5d 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 0a 2a ] return code..*
c3d0: 2a 0a 2a 2a 20 7b 48 31 34 32 30 39 7d 20 41 20 *.** {H14209} A
c3e0: 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 successful call
c3f0: 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 to .**
c400: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 [sqlite3_db_conf
c410: 69 67 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 44 42 ig](D,[SQLITE_DB
c420: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
c430: 5d 2c 42 2c 5a 2c 4e 29 20 77 68 65 72 65 0a 2a ],B,Z,N) where.*
c440: 2a 20 20 20 20 20 20 20 20 20 20 44 20 69 73 20 * D is
c450: 61 6e 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 an open [databas
c460: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e e connection] an
c470: 64 20 5a 20 61 6e 64 20 4e 20 61 72 65 20 70 6f d Z and N are po
c480: 73 69 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 sitive.**
c490: 20 20 20 69 6e 74 65 67 65 72 73 20 61 6e 64 20 integers and
c4a0: 42 20 69 73 20 61 6e 20 61 6c 69 67 6e 65 64 20 B is an aligned
c4b0: 62 75 66 66 65 72 20 61 74 20 6c 65 61 73 74 20 buffer at least
c4c0: 5a 2a 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a Z*N bytes in siz
c4d0: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 e.** sh
c4e0: 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20 5b 6c all cause the [l
c4f0: 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 ookaside memory
c500: 61 6c 6c 6f 63 61 74 6f 72 5d 20 66 6f 72 20 44 allocator] for D
c510: 20 74 6f 20 75 73 65 20 62 75 66 66 65 72 20 42 to use buffer B
c520: 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 .** wi
c530: 74 68 20 4e 20 73 6c 6f 74 73 20 6f 66 20 5a 20 th N slots of Z
c540: 62 79 74 65 73 20 65 61 63 68 2e 0a 2a 2a 0a 2a bytes each..**.*
c550: 2a 20 7b 48 31 34 32 31 32 7d 20 41 20 73 75 63 * {H14212} A suc
c560: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 cessful call to
c570: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
c580: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 5d lite3_db_config]
c590: 28 44 2c 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e (D,[SQLITE_DBCON
c5a0: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 42 FIG_LOOKASIDE],B
c5b0: 2c 5a 2c 4e 29 20 77 68 65 72 65 0a 2a 2a 20 20 ,Z,N) where.**
c5c0: 20 20 20 20 20 20 20 20 44 20 69 73 20 61 6e 20 D is an
c5d0: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 open [database c
c5e0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5a onnection] and Z
c5f0: 20 61 6e 64 20 4e 20 61 72 65 20 70 6f 73 69 74 and N are posit
c600: 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ive.**
c610: 69 6e 74 65 67 65 72 73 20 61 6e 64 20 42 20 69 integers and B i
c620: 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 73 s NULL pointer s
c630: 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65 0a 2a hall cause the.*
c640: 2a 20 20 20 20 20 20 20 20 20 20 5b 6c 6f 6f 6b * [look
c650: 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c aside memory all
c660: 6f 63 61 74 6f 72 5d 20 66 6f 72 20 44 20 74 6f ocator] for D to
c670: 20 61 20 6f 62 74 61 69 6e 20 5a 2a 4e 20 62 79 a obtain Z*N by
c680: 74 65 20 62 75 66 66 65 72 0a 2a 2a 20 20 20 20 te buffer.**
c690: 20 20 20 20 20 20 66 72 6f 6d 20 74 68 65 20 70 from the p
c6a0: 72 69 6d 61 72 79 20 6d 65 6d 6f 72 79 20 61 6c rimary memory al
c6b0: 6c 6f 63 61 74 6f 72 20 61 6e 64 20 75 73 65 20 locator and use
c6c0: 74 68 61 74 20 62 75 66 66 65 72 0a 2a 2a 20 20 that buffer.**
c6d0: 20 20 20 20 20 20 20 20 77 69 74 68 20 4e 20 6c with N l
c6e0: 6f 6f 6b 61 73 69 64 65 20 73 6c 6f 74 73 20 6f ookaside slots o
c6f0: 66 20 5a 20 62 79 74 65 73 20 65 61 63 68 2e 0a f Z bytes each..
c700: 2a 2a 0a 2a 2a 20 7b 48 31 34 32 31 35 7d 20 41 **.** {H14215} A
c710: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c successful call
c720: 20 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 to .**
c730: 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e [sqlite3_db_con
c740: 66 69 67 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 44 fig](D,[SQLITE_D
c750: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 BCONFIG_LOOKASID
c760: 45 5d 2c 42 2c 5a 2c 4e 29 20 77 68 65 72 65 0a E],B,Z,N) where.
c770: 2a 2a 20 20 20 20 20 20 20 20 20 20 44 20 69 73 ** D is
c780: 20 61 6e 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 an open [databa
c790: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 se connection] a
c7a0: 6e 64 20 5a 20 61 6e 64 20 4e 20 61 72 65 20 7a nd Z and N are z
c7b0: 65 72 6f 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 ero shall.**
c7c0: 20 20 20 20 20 20 64 69 73 61 62 6c 65 20 74 68 disable th
c7d0: 65 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d e [lookaside mem
c7e0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 66 ory allocator] f
c7f0: 6f 72 20 44 2e 0a 2a 2a 0a 2a 2a 0a 2a 2f 0a 53 or D..**.**.*/.S
c800: 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 QLITE_EXPERIMENT
c810: 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 AL int sqlite3_d
c820: 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 b_config(sqlite3
c830: 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b *, int op, ...);
c840: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
c850: 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 : Memory Allocat
c860: 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48 31 ion Routines {H1
c870: 30 31 35 35 7d 20 3c 53 32 30 31 32 30 3e 0a 2a 0155} <S20120>.*
c880: 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
c890: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 *.** An instance
c8a0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 of this object
c8b0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 defines the inte
c8c0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 rface between SQ
c8d0: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d Lite.** and low-
c8e0: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c level memory all
c8f0: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 ocation routines
c900: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a ..**.** This obj
c910: 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f ect is used in o
c920: 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e nly one place in
c930: 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 the SQLite inte
c940: 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e rface..** A poin
c950: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e ter to an instan
c960: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 ce of this objec
c970: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e t is the argumen
c980: 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 t to.** [sqlite3
c990: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 _config()] when
c9a0: 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f the configuratio
c9b0: 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b n option is.** [
c9c0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 SQLITE_CONFIG_MA
c9d0: 4c 4c 4f 43 5d 2e 20 20 42 79 20 63 72 65 61 74 LLOC]. By creat
c9e0: 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 ing an instance
c9f0: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a of this object.*
ca00: 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 * and passing it
ca10: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e to [sqlite3_con
ca20: 66 69 67 28 29 5d 20 64 75 72 69 6e 67 20 63 6f fig()] during co
ca30: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 0a nfiguration, an.
ca40: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 ** application c
ca50: 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c an specify an al
ca60: 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 ternative memory
ca70: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 allocation subs
ca80: 79 73 74 65 6d 0a 2a 2a 20 66 6f 72 20 53 51 4c ystem.** for SQL
ca90: 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 ite to use for a
caa0: 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 ll of its dynami
cab0: 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a c memory needs..
cac0: 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 **.** Note that
cad0: 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 SQLite comes wit
cae0: 68 20 61 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d h a built-in mem
caf0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 ory allocator th
cb00: 61 74 20 69 73 0a 2a 2a 20 70 65 72 66 65 63 74 at is.** perfect
cb10: 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 ly adequate for
cb20: 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 the overwhelming
cb30: 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 majority of app
cb40: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 lications.** and
cb50: 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 that this objec
cb60: 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c t is only useful
cb70: 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 to a tiny minor
cb80: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 ity of applicati
cb90: 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 ons.** with spec
cba0: 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 ialized memory a
cbb0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 llocation requir
cbc0: 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 ements. This ob
cbd0: 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 ject is.** also
cbe0: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 used during test
cbf0: 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e ing of SQLite in
cc00: 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 order to specif
cc10: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 y an alternative
cc20: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 .** memory alloc
cc30: 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 ator that simula
cc40: 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f tes memory out-o
cc50: 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 f-memory conditi
cc60: 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 ons in.** order
cc70: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 to verify that S
cc80: 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 QLite recovers g
cc90: 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 racefully from s
cca0: 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e uch.** condition
ccb0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 s..**.** The xMa
ccc0: 6c 6c 6f 63 2c 20 78 46 72 65 65 2c 20 61 6e 64 lloc, xFree, and
ccd0: 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 xRealloc method
cce0: 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 s must work like
ccf0: 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 the.** malloc()
cd00: 2c 20 66 72 65 65 28 29 2c 20 61 6e 64 20 72 65 , free(), and re
cd10: 61 6c 6c 6f 63 28 29 20 66 75 6e 63 74 69 6f 6e alloc() function
cd20: 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 s from the stand
cd30: 61 72 64 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a ard library..**.
cd40: 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 ** xSize should
cd50: 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 return the alloc
cd60: 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d ated size of a m
cd70: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
cd80: 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f .** previously o
cd90: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 btained from xMa
cda0: 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 lloc or xRealloc
cdb0: 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 . The allocated
cdc0: 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 size.** is alwa
cdd0: 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 ys at least as b
cde0: 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 ig as the reques
cdf0: 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 ted size but may
ce00: 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a be larger..**.*
ce10: 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d * The xRoundup m
ce20: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 ethod returns wh
ce30: 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 at would be the
ce40: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f allocated size o
ce50: 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c f.** a memory al
ce60: 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 location given a
ce70: 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 particular requ
ce80: 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 ested size. Mos
ce90: 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f t memory.** allo
cea0: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 cators round up
ceb0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
cec0: 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 ns at least to t
ced0: 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 he next multiple
cee0: 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 .** of 8. Some
cef0: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 allocators round
cf00: 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 up to a larger
cf10: 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 multiple or to a
cf20: 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 0a power of 2..**.
cf30: 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 ** The xInit met
cf40: 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 hod initializes
cf50: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 the memory alloc
cf60: 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d ator. (For exam
cf70: 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 ple,.** it might
cf80: 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 allocate any re
cf90: 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 quire mutexes or
cfa0: 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 initialize inte
cfb0: 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 rnal data.** str
cfc0: 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 uctures. The xS
cfd0: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 hutdown method i
cfe0: 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 s invoked (indir
cff0: 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 ectly) by.** [sq
d000: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
d010: 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 ] and should dea
d020: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f llocate any reso
d030: 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a urces acquired.*
d040: 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 * by xInit. The
d050: 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 pAppData pointe
d060: 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 r is used as the
d070: 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 only parameter
d080: 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 to.** xInit and
d090: 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2f 0a 74 79 xShutdown..*/.ty
d0a0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
d0b0: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
d0c0: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 sqlite3_mem_met
d0d0: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c hods;.struct sql
d0e0: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
d0f0: 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 {. void *(*xMa
d100: 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 lloc)(int);
d110: 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c /* Memory al
d120: 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f location functio
d130: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 n */. void (*xF
d140: 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 ree)(void*);
d150: 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 /* Free a
d160: 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e prior allocation
d170: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 */. void *(*xR
d180: 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e ealloc)(void*,in
d190: 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 t); /* Resize a
d1a0: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a n allocation */.
d1b0: 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 int (*xSize)(v
d1c0: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 oid*);
d1d0: 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 /* Return the s
d1e0: 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 ize of an alloca
d1f0: 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a tion */. int (*
d200: 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 xRoundup)(int);
d210: 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e /* Roun
d220: 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a d up request siz
d230: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 e to allocation
d240: 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a size */. int (*
d250: 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 xInit)(void*);
d260: 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 /* Init
d270: 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 ialize the memor
d280: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 y allocator */.
d290: 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 void (*xShutdow
d2a0: 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 n)(void*);
d2b0: 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 /* Deinitialize
d2c0: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 the memory alloc
d2d0: 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a ator */. void *
d2e0: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 pAppData;
d2f0: 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 /* Argu
d300: 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 ment to xInit()
d310: 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 and xShutdown()
d320: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.};../*.** CAP
d330: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 I3REF: Configura
d340: 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 48 31 tion Options {H1
d350: 30 31 36 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 0160} <S20000>.*
d360: 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
d370: 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 *.** These const
d380: 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 ants are the ava
d390: 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 ilable integer c
d3a0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
d3b0: 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e ions that.** can
d3c0: 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 be passed as th
d3d0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
d3e0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
d3f0: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 _config()] inter
d400: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 face..**.** New
d410: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
d420: 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 tions may be add
d430: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c ed in future rel
d440: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e eases of SQLite.
d450: 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e .** Existing con
d460: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
d470: 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 ns might be disc
d480: 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 ontinued. Appli
d490: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c cations.** shoul
d4a0: 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 d check the retu
d4b0: 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 rn code from [sq
d4c0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
d4d0: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 to make sure tha
d4e0: 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f t.** the call wo
d4f0: 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 rked. The [sqli
d500: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e te3_config()] in
d510: 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 terface will ret
d520: 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 urn a.** non-zer
d530: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 o [error code] i
d540: 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 f a discontinued
d550: 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 or unsupported
d560: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
d570: 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b tion.** is invok
d580: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a ed..**.** <dl>.*
d590: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
d5a0: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 FIG_SINGLETHREAD
d5b0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
d5c0: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 re are no argume
d5d0: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 nts to this opti
d5e0: 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e on. This option
d5f0: 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c disables.** all
d600: 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 mutexing and pu
d610: 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 ts SQLite into a
d620: 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 mode where it c
d630: 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a an only be used.
d640: 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 ** by a single t
d650: 68 72 65 61 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a hread.</dd>.**.*
d660: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
d670: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c FIG_MULTITHREAD<
d680: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 /dt>.** <dd>Ther
d690: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e e are no argumen
d6a0: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f ts to this optio
d6b0: 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 n. This option
d6c0: 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 disables.** mute
d6d0: 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 xing on [databas
d6e0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e e connection] an
d6f0: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
d700: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a ement] objects..
d710: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
d720: 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c on is responsibl
d730: 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e e for serializin
d740: 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b g access to.** [
d750: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
d760: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 ions] and [prepa
d770: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e red statements].
d780: 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 But other mute
d790: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c xes.** are enabl
d7a0: 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 ed so that SQLit
d7b0: 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 e will be safe t
d7c0: 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 o use in a multi
d7d0: 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 -threaded.** env
d7e0: 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 ironment as long
d7f0: 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 as no two threa
d800: 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 ds attempt to us
d810: 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 e the same.** [d
d820: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
d830: 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 on] at the same
d840: 74 69 6d 65 2e 20 20 53 65 65 20 74 68 65 20 5b time. See the [
d850: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 0a threading mode].
d860: 2a 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e ** documentation
d870: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 for additional
d880: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64 information.</dd
d890: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
d8a0: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c TE_CONFIG_SERIAL
d8b0: 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 IZED</dt>.** <dd
d8c0: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 >There are no ar
d8d0: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 guments to this
d8e0: 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 option. This op
d8f0: 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 tion enables.**
d900: 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c all mutexes incl
d910: 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 uding the recurs
d920: 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f ive.** mutexes o
d930: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e n [database conn
d940: 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 ection] and [pre
d950: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
d960: 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 objects..** In
d970: 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 this mode (which
d980: 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 is the default
d990: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 when SQLite is c
d9a0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 ompiled with.**
d9b0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
d9c0: 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 FE=1]) the SQLit
d9d0: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 e library will i
d9e0: 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 tself serialize
d9f0: 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 access.** to [da
da00: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
da10: 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 ns] and [prepare
da20: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f d statements] so
da30: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 that the.** app
da40: 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 lication is free
da50: 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 to use the same
da60: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
da70: 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a ction] or the.**
da80: 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 same [prepared
da90: 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 statement] in di
daa0: 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 fferent threads
dab0: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 at the same time
dac0: 2e 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 ..** See the [th
dad0: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f reading mode] do
dae0: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 cumentation for
daf0: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 additional infor
db00: 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a mation.</dd>.**.
db10: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ** <dt>SQLITE_CO
db20: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e NFIG_MALLOC</dt>
db30: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 .** <dd>This opt
db40: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
db50: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 le argument whic
db60: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 h is a pointer t
db70: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 o an.** instance
db80: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
db90: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 _mem_methods] st
dba0: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 ructure. The ar
dbb0: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 gument specifies
dbc0: 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 .** alternative
dbd0: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 low-level memory
dbe0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 allocation rout
dbf0: 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 ines to be used
dc00: 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 in place of.** t
dc10: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
dc20: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 tion routines bu
dc30: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e ilt into SQLite.
dc40: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
dc50: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
dc60: 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 TMALLOC</dt>.**
dc70: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 <dd>This option
dc80: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
dc90: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
dca0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
dcb0: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 .** instance of
dcc0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d the [sqlite3_mem
dcd0: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 _methods] struct
dce0: 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 ure. The [sqlit
dcf0: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a e3_mem_methods].
dd00: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 ** structure is
dd10: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 filled with the
dd20: 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 currently define
dd30: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 d memory allocat
dd40: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a ion routines..**
dd50: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e This option can
dd60: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 be used to over
dd70: 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 load the default
dd80: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
dd90: 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 on.** routines w
dda0: 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 ith a wrapper th
ddb0: 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d at simulations m
ddc0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
ddd0: 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 failure or.** t
dde0: 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 racks memory usa
ddf0: 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e ge, for example.
de00: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
de10: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 SQLITE_CONFIG_ME
de20: 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 MSTATUS</dt>.**
de30: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 <dd>This option
de40: 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 takes single arg
de50: 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e ument of type in
de60: 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 t, interpreted a
de70: 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c s a .** boolean,
de80: 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f which enables o
de90: 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 r disables the c
dea0: 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d ollection of mem
deb0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a ory allocation .
dec0: 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 57 ** statistics. W
ded0: 68 65 6e 20 64 69 73 61 62 6c 65 64 2c 20 74 68 hen disabled, th
dee0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 e following SQLi
def0: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 te interfaces be
df00: 63 6f 6d 65 20 0a 2a 2a 20 6e 6f 6e 2d 6f 70 65 come .** non-ope
df10: 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c rational:.** <
df20: 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 ul>.** <li> [s
df30: 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 qlite3_memory_us
df40: 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 ed()].** <li>
df50: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
df60: 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 highwater()].**
df70: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f <li> [sqlite3_
df80: 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 soft_heap_limit(
df90: 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 )].** <li> [sq
dfa0: 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a lite3_status()].
dfb0: 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f ** </ul>.** </
dfc0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
dfd0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 LITE_CONFIG_SCRA
dfe0: 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TCH</dt>.** <dd>
dff0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 This option spec
e000: 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d ifies a static m
e010: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 emory buffer tha
e020: 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 t SQLite can use
e030: 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 for.** scratch
e040: 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61 memory. There a
e050: 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e re three argumen
e060: 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 74 ts: A pointer t
e070: 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20 74 68 o the memory, th
e080: 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 e.** size of eac
e090: 68 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 h scratch buffer
e0a0: 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e (sz), and the n
e0b0: 75 6d 62 65 72 20 6f 66 20 62 75 66 66 65 72 73 umber of buffers
e0c0: 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a (N). The sz.**
e0d0: 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 argument must b
e0e0: 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 e a multiple of
e0f0: 31 36 2e 20 54 68 65 20 73 7a 20 70 61 72 61 6d 16. The sz param
e100: 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61 eter should be a
e110: 20 66 65 77 20 62 79 74 65 73 0a 2a 2a 20 6c 61 few bytes.** la
e120: 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 61 63 rger than the ac
e130: 74 75 61 6c 20 73 63 72 61 74 63 68 20 73 70 61 tual scratch spa
e140: 63 65 20 72 65 71 75 69 72 65 64 20 64 75 65 20 ce required due
e150: 69 6e 74 65 72 6e 61 6c 20 6f 76 65 72 68 65 61 internal overhea
e160: 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 0a d..** The first.
e170: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 ** argument shou
e180: 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 ld point to an a
e190: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 llocation of at
e1a0: 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 least sz*N bytes
e1b0: 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 of memory..** S
e1c0: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e QLite will use n
e1d0: 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 o more than one
e1e0: 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 61 scratch buffer a
e1f0: 74 20 6f 6e 63 65 20 70 65 72 20 74 68 72 65 61 t once per threa
e200: 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c d, so.** N shoul
e210: 64 20 62 65 20 73 65 74 20 74 6f 20 74 68 65 20 d be set to the
e220: 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d expected maximum
e230: 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 number of threa
e240: 64 73 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 70 ds. The sz.** p
e250: 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 arameter should
e260: 62 65 20 36 20 74 69 6d 65 73 20 74 68 65 20 73 be 6 times the s
e270: 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 ize of the large
e280: 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 st database page
e290: 20 73 69 7a 65 2e 0a 2a 2a 20 53 63 72 61 74 63 size..** Scratc
e2a0: 68 20 62 75 66 66 65 72 73 20 61 72 65 20 75 73 h buffers are us
e2b0: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 ed as part of th
e2c0: 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65 20 e btree balance
e2d0: 6f 70 65 72 61 74 69 6f 6e 2e 20 20 49 66 0a 2a operation. If.*
e2e0: 2a 20 54 68 65 20 62 74 72 65 65 20 62 61 6c 61 * The btree bala
e2f0: 6e 63 65 72 20 6e 65 65 64 73 20 61 64 64 69 74 ncer needs addit
e300: 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 62 65 79 ional memory bey
e310: 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 ond what is prov
e320: 69 64 65 64 20 62 79 0a 2a 2a 20 73 63 72 61 74 ided by.** scrat
e330: 63 68 20 62 75 66 66 65 72 73 20 6f 72 20 69 66 ch buffers or if
e340: 20 6e 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 no scratch buff
e350: 65 72 20 73 70 61 63 65 20 69 73 20 73 70 65 63 er space is spec
e360: 69 66 69 65 64 2c 20 74 68 65 6e 20 53 51 4c 69 ified, then SQLi
e370: 74 65 0a 2a 2a 20 67 6f 65 73 20 74 6f 20 5b 73 te.** goes to [s
e380: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
e390: 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d to obtain the m
e3a0: 65 6d 6f 72 79 20 69 74 20 6e 65 65 64 73 2e 3c emory it needs.<
e3b0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
e3c0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 QLITE_CONFIG_PAG
e3d0: 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c ECACHE</dt>.** <
e3e0: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 dd>This option s
e3f0: 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 pecifies a stati
e400: 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 c memory buffer
e410: 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 that SQLite can
e420: 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 use for.** the d
e430: 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63 atabase page cac
e440: 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61 he with the defa
e450: 75 6c 74 20 70 61 67 65 20 63 61 63 68 65 20 69 ult page cache i
e460: 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e 20 20 0a mplemenation. .
e470: 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 ** This configur
e480: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 ation should not
e490: 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61 be used if an a
e4a0: 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
e4b0: 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 e page.** cache
e4c0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 implementation i
e4d0: 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 s loaded using t
e4e0: 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
e4f0: 5f 50 43 41 43 48 45 20 6f 70 74 69 6f 6e 2e 0a _PCACHE option..
e500: 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 ** There are thr
e510: 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 ee arguments to
e520: 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 this option: A p
e530: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a ointer to the.**
e540: 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a memory, the siz
e550: 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 e of each page b
e560: 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 uffer (sz), and
e570: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 the number of pa
e580: 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 ges (N)..** The
e590: 73 7a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 sz argument must
e5a0: 20 62 65 20 61 20 70 6f 77 65 72 20 6f 66 20 74 be a power of t
e5b0: 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 wo between 512 a
e5c0: 6e 64 20 33 32 37 36 38 2e 20 20 54 68 65 20 66 nd 32768. The f
e5d0: 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 irst.** argument
e5e0: 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f should point to
e5f0: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f an allocation o
e600: 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 f at least sz*N
e610: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e bytes of memory.
e620: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 .** SQLite will
e630: 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 use the memory p
e640: 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66 rovided by the f
e650: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
e660: 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 satisfy its.**
e670: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 memory needs for
e680: 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 the first N pag
e690: 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20 es that it adds
e6a0: 74 6f 20 63 61 63 68 65 2e 20 20 49 66 20 61 64 to cache. If ad
e6b0: 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 ditional.** page
e6c0: 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 cache memory is
e6d0: 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 needed beyond w
e6e0: 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 hat is provided
e6f0: 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 by this option,
e700: 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 then.** SQLite g
e710: 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f oes to [sqlite3_
e720: 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 malloc()] for th
e730: 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f e additional sto
e740: 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 rage space..** T
e750: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
e760: 6e 20 6d 69 67 68 74 20 75 73 65 20 6f 6e 65 20 n might use one
e770: 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 4e or more of the N
e780: 20 62 75 66 66 65 72 73 20 74 6f 20 68 6f 6c 64 buffers to hold
e790: 20 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 63 63 6f .** memory acco
e7a0: 75 6e 74 69 6e 67 20 69 6e 66 6f 72 6d 61 74 69 unting informati
e7b0: 6f 6e 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 on. </dd>.**.**
e7c0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
e7d0: 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c G_HEAP</dt>.** <
e7e0: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 dd>This option s
e7f0: 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 pecifies a stati
e800: 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 c memory buffer
e810: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c that SQLite will
e820: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 use.** for all
e830: 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d of its dynamic m
e840: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
e850: 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 needs beyond th
e860: 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 ose provided.**
e870: 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 for by [SQLITE_C
e880: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 ONFIG_SCRATCH] a
e890: 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 nd [SQLITE_CONFI
e8a0: 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a G_PAGECACHE]..**
e8b0: 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 There are three
e8c0: 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 20 70 6f arguments: A po
e8d0: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d inter to the mem
e8e0: 6f 72 79 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 ory, the number
e8f0: 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 of.** bytes in t
e900: 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 he memory buffer
e910: 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 , and the minimu
e920: 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a m allocation siz
e930: 65 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 66 69 e. If.** the fi
e940: 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 rst pointer (the
e950: 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 memory pointer)
e960: 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 is NULL, then S
e970: 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a QLite reverts.**
e980: 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 to using its de
e990: 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c fault memory all
e9a0: 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 ocator (the syst
e9b0: 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c em malloc() impl
e9c0: 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 ementation),.**
e9d0: 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f undoing any prio
e9e0: 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 r invocation of
e9f0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
ea00: 41 4c 4c 4f 43 5d 2e 20 20 49 66 20 74 68 65 0a ALLOC]. If the.
ea10: 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 ** memory pointe
ea20: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e r is not NULL an
ea30: 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 d either [SQLITE
ea40: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d _ENABLE_MEMSYS3]
ea50: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 or.** [SQLITE_E
ea60: 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 NABLE_MEMSYS5] a
ea70: 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e re defined, then
ea80: 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 the alternative
ea90: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 memory.** alloc
eaa0: 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 ator is engaged
eab0: 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 to handle all of
eac0: 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 SQLites memory
ead0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 allocation needs
eae0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
eaf0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d >SQLITE_CONFIG_M
eb00: 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 UTEX</dt>.** <dd
eb10: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b >This option tak
eb20: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
eb30: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 ment which is a
eb40: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a pointer to an.**
eb50: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 instance of the
eb60: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
eb70: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 methods] structu
eb80: 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e re. The argumen
eb90: 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 t specifies.** a
eba0: 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c lternative low-l
ebb0: 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 evel mutex routi
ebc0: 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 nes to be used i
ebd0: 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d n place.** the m
ebe0: 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 utex routines bu
ebf0: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e ilt into SQLite.
ec00: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
ec10: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
ec20: 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c TMUTEX</dt>.** <
ec30: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 dd>This option t
ec40: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
ec50: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 gument which is
ec60: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a a pointer to an.
ec70: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 ** instance of t
ec80: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 he [sqlite3_mute
ec90: 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 x_methods] struc
eca0: 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 ture. The.** [s
ecb0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
ecc0: 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 hods].** structu
ecd0: 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 re is filled wit
ece0: 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 h the currently
ecf0: 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f defined mutex ro
ed00: 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20 utines..** This
ed10: 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 option can be us
ed20: 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 ed to overload t
ed30: 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 he default mutex
ed40: 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 allocation.** r
ed50: 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 outines with a w
ed60: 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 rapper used to t
ed70: 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 rack mutex usage
ed80: 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 for performance
ed90: 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 .** profiling or
eda0: 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 testing, for ex
edb0: 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a ample.</dd>.**.*
edc0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
edd0: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 FIG_LOOKASIDE</d
ede0: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f t>.** <dd>This o
edf0: 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 ption takes two
ee00: 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 arguments that d
ee10: 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 etermine the def
ee20: 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 ault.** memory a
ee30: 6c 6c 63 61 74 69 6f 6e 20 6c 6f 6f 6b 61 73 69 llcation lookasi
ee40: 64 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e de optimization.
ee50: 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 The first argu
ee60: 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 ment is the.** s
ee70: 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b ize of each look
ee80: 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f aside buffer slo
ee90: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 t and the second
eea0: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
eeb0: 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 f.** slots alloc
eec0: 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 ated to each dat
eed0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
eee0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
eef0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 >SQLITE_CONFIG_P
ef00: 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 CACHE</dt>.** <d
ef10: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 d>This option ta
ef20: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 kes a single arg
ef30: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 ument which is a
ef40: 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 pointer to.** a
ef50: 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 n [sqlite3_pcach
ef60: 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 e_methods] objec
ef70: 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 t. This object
ef80: 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e specifies the in
ef90: 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 terface.** to a
efa0: 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 custom page cach
efb0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
efc0: 2e 20 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 . SQLite makes
efd0: 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a a copy of the.**
efe0: 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73 object and uses
eff0: 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61 63 it for page cac
f000: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
f010: 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a tions.</dd>.**.*
f020: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
f030: 46 49 47 5f 47 45 54 50 43 41 43 48 45 3c 2f 64 FIG_GETPCACHE</d
f040: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f t>.** <dd>This o
f050: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
f060: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 ngle argument wh
f070: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ich is a pointer
f080: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 to an.** [sqlit
f090: 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 e3_pcache_method
f0a0: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 s] object. SQLi
f0b0: 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65 te copies of the
f0c0: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 current.** page
f0d0: 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 cache implement
f0e0: 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 ation into that
f0f0: 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a object.</dd>.**.
f100: 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 ** </dl>.*/.#def
f110: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
f120: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 G_SINGLETHREAD
f130: 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 1 /* nil */.#de
f140: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
f150: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 IG_MULTITHREAD
f160: 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 2 /* nil */.#d
f170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
f180: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 FIG_SERIALIZED
f190: 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 3 /* nil */.#
f1a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
f1b0: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 NFIG_MALLOC
f1c0: 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 4 /* sqlite3
f1d0: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f _mem_methods* */
f1e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
f1f0: 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 CONFIG_GETMALLOC
f200: 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 5 /* sqlit
f210: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 e3_mem_methods*
f220: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
f230: 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 E_CONFIG_SCRATCH
f240: 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 6 /* voi
f250: 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 d*, int sz, int
f260: 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c N */.#define SQL
f270: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 ITE_CONFIG_PAGEC
f280: 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 ACHE 7 /* v
f290: 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e oid*, int sz, in
f2a0: 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 t N */.#define S
f2b0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 QLITE_CONFIG_HEA
f2c0: 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a P 8 /*
f2d0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 void*, int nByt
f2e0: 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 e, int min */.#d
f2f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
f300: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 FIG_MEMSTATUS
f310: 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 9 /* boolean
f320: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
f330: 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 E_CONFIG_MUTEX
f340: 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 10 /* sql
f350: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
f360: 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ds* */.#define S
f370: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
f380: 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a MUTEX 11 /*
f390: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d sqlite3_mutex_m
f3a0: 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 ethods* */./* pr
f3b0: 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f eviously SQLITE_
f3c0: 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f CONFIG_CHUNKALLO
f3d0: 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f C 12 which is no
f3e0: 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 w unused. */ .#d
f3f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
f400: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 FIG_LOOKASIDE
f410: 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 13 /* int int
f420: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
f430: 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 E_CONFIG_PCACHE
f440: 20 20 20 20 20 20 31 34 20 20 2f 2a 20 73 71 6c 14 /* sql
f450: 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 ite3_pcache_meth
f460: 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ods* */.#define
f470: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
f480: 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f TPCACHE 15 /
f490: 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 * sqlite3_pcache
f4a0: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 0a 2f 2a _methods* */../*
f4b0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
f4c0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 nfiguration Opti
f4d0: 6f 6e 73 20 7b 48 31 30 31 37 30 7d 20 3c 53 32 ons {H10170} <S2
f4e0: 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 0000>.** EXPERIM
f4f0: 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ENTAL.**.** Thes
f500: 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 e constants are
f510: 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e the available in
f520: 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 teger configurat
f530: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 ion options that
f540: 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 .** can be passe
f550: 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 d as the second
f560: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
f570: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 [sqlite3_db_conf
f580: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e ig()] interface.
f590: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 .**.** New confi
f5a0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 guration options
f5b0: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e may be added in
f5c0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
f5d0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 of SQLite..** E
f5e0: 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 xisting configur
f5f0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 ation options mi
f600: 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e ght be discontin
f610: 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f ued. Applicatio
f620: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 ns.** should che
f630: 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f ck the return co
f640: 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 de from [sqlite3
f650: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f _db_config()] to
f660: 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a make sure that.
f670: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b ** the call work
f680: 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 ed. The [sqlite
f690: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 3_db_config()] i
f6a0: 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 nterface will re
f6b0: 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 turn a.** non-ze
f6c0: 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 ro [error code]
f6d0: 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 if a discontinue
f6e0: 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 d or unsupported
f6f0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
f700: 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f ption.** is invo
f710: 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a ked..**.** <dl>.
f720: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 ** <dt>SQLITE_DB
f730: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
f740: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 </dt>.** <dd>Thi
f750: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 s option takes t
f760: 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 hree additional
f770: 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 arguments that d
f780: 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a etermine the .**
f790: 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f [lookaside memo
f7a0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f ry allocator] co
f7b0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 nfiguration for
f7c0: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
f7d0: 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 nnection]..** Th
f7e0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
f7f0: 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61 (the third para
f800: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 meter to [sqlite
f810: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 3_db_config()] i
f820: 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 s a.** pointer t
f830: 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 o a memory buffe
f840: 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f r to use for loo
f850: 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 20 20 kaside memory.
f860: 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 The first.** arg
f870: 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 4e 55 4c ument may be NUL
f880: 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 L in which case
f890: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f SQLite will allo
f8a0: 63 61 74 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 cate the lookasi
f8b0: 64 65 0a 2a 2a 20 62 75 66 66 65 72 20 69 74 73 de.** buffer its
f8c0: 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 elf using [sqlit
f8d0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 e3_malloc()]. T
f8e0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
f8f0: 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a nt is the.** siz
f900: 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 e of each lookas
f910: 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 ide buffer slot
f920: 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 61 72 and the third ar
f930: 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 gument is the nu
f940: 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 mber of.** slots
f950: 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 . The size of t
f960: 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 he buffer in the
f970: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
f980: 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 must be greater
f990: 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c than.** or equal
f9a0: 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 to the product
f9b0: 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e of the second an
f9c0: 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 d third argument
f9d0: 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f s.</dd>.**.** </
f9e0: 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 dl>.*/.#define S
f9f0: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c QLITE_DBCONFIG_L
fa00: 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 30 30 31 OOKASIDE 1001
fa10: 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 /* void* int i
fa20: 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 nt */.../*.** CA
fa30: 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f PI3REF: Enable O
fa40: 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 r Disable Extend
fa50: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 ed Result Codes
fa60: 7b 48 31 32 32 30 30 7d 20 3c 53 31 30 37 30 30 {H12200} <S10700
fa70: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 >.**.** The sqli
fa80: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 te3_extended_res
fa90: 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 ult_codes() rout
faa0: 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 ine enables or d
fab0: 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b isables the.** [
fac0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
fad0: 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f codes] feature o
fae0: 66 20 53 51 4c 69 74 65 2e 20 54 68 65 20 65 78 f SQLite. The ex
faf0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a tended result.**
fb00: 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 codes are disab
fb10: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 led by default f
fb20: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f or historical co
fb30: 6d 70 61 74 69 62 69 6c 69 74 79 20 63 6f 6e 73 mpatibility cons
fb40: 69 64 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a iderations..**.*
fb50: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
fb60: 0a 2a 2a 20 7b 48 31 32 32 30 31 7d 20 45 61 63 .** {H12201} Eac
fb70: 68 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 h new [database
fb80: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 68 61 6c connection] shal
fb90: 6c 20 68 61 76 65 20 74 68 65 0a 2a 2a 20 20 20 l have the.**
fba0: 20 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64 [extended
fbb0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 result codes] f
fbc0: 65 61 74 75 72 65 20 64 69 73 61 62 6c 65 64 20 eature disabled
fbd0: 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a by default..**.*
fbe0: 2a 20 7b 48 31 32 32 30 32 7d 20 54 68 65 20 5b * {H12202} The [
fbf0: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
fc00: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 44 2c _result_codes(D,
fc10: 46 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 F)] interface sh
fc20: 61 6c 6c 20 65 6e 61 62 6c 65 0a 2a 2a 20 20 20 all enable.**
fc30: 20 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64 [extended
fc40: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 result codes] f
fc50: 6f 72 20 74 68 65 20 20 5b 64 61 74 61 62 61 73 or the [databas
fc60: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a e connection] D.
fc70: 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 74 ** if t
fc80: 68 65 20 46 20 70 61 72 61 6d 65 74 65 72 20 69 he F parameter i
fc90: 73 20 74 72 75 65 2c 20 6f 72 20 64 69 73 61 62 s true, or disab
fca0: 6c 65 20 74 68 65 6d 20 69 66 20 46 20 69 73 20 le them if F is
fcb0: 66 61 6c 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 false..*/.int sq
fcc0: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 lite3_extended_r
fcd0: 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 esult_codes(sqli
fce0: 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 te3*, int onoff)
fcf0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
fd00: 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 F: Last Insert R
fd10: 6f 77 69 64 20 7b 48 31 32 32 32 30 7d 20 3c 53 owid {H12220} <S
fd20: 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 45 61 63 10700>.**.** Eac
fd30: 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 h entry in an SQ
fd40: 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 Lite table has a
fd50: 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 unique 64-bit s
fd60: 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 igned.** integer
fd70: 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 key called the
fd80: 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 [ROWID | "rowid"
fd90: 5d 2e 20 54 68 65 20 72 6f 77 69 64 20 69 73 20 ]. The rowid is
fda0: 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 always available
fdb0: 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c .** as an undecl
fdc0: 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 ared column name
fdd0: 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 d ROWID, OID, or
fde0: 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 _ROWID_ as long
fdf0: 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d as those.** nam
fe00: 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 es are not also
fe10: 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 used by explicit
fe20: 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 ly declared colu
fe30: 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74 68 65 20 74 mns. If.** the t
fe40: 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d able has a colum
fe50: 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 n of type [INTEG
fe60: 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 ER PRIMARY KEY]
fe70: 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e then that column
fe80: 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 .** is another a
fe90: 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 lias for the row
fea0: 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 id..**.** This r
feb0: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 outine returns t
fec0: 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 he [rowid] of th
fed0: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a e most recent.**
fee0: 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 successful [INS
fef0: 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 ERT] into the da
ff00: 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 tabase from the
ff10: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
ff20: 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 tion].** in the
ff30: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 first argument.
ff40: 20 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 If no successfu
ff50: 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 l [INSERT]s.** h
ff60: 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 ave ever occurre
ff70: 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61 d on that databa
ff80: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a se connection, z
ff90: 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e ero is returned.
ffa0: 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 5b 49 4e .**.** If an [IN
ffb0: 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 SERT] occurs wit
ffc0: 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74 hin a trigger, t
ffd0: 68 65 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 hen the [rowid]
ffe0: 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a of the inserted.
fff0: 2a 2a 20 72 6f 77 20 69 73 20 72 65 74 75 72 6e ** row is return
10000 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 ed by this routi
10010 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 ne as long as th
10020 65 20 74 72 69 67 67 65 72 20 69 73 20 72 75 6e e trigger is run
10030 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 ning..** But onc
10040 65 20 74 68 65 20 74 72 69 67 67 65 72 20 74 65 e the trigger te
10050 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61 rminates, the va
10060 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 lue returned by
10070 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 this routine.**
10080 72 65 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c reverts to the l
10090 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74 ast value insert
100a0 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 ed before the tr
100b0 69 67 67 65 72 20 66 69 72 65 64 2e 0a 2a 2a 0a igger fired..**.
100c0 2a 2a 20 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 ** An [INSERT] t
100d0 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f hat fails due to
100e0 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 a constraint vi
100f0 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 olation is not a
10100 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b .** successful [
10110 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 INSERT] and does
10120 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 not change the
10130 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
10140 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e y this.** routin
10150 65 2e 20 20 54 68 75 73 20 49 4e 53 45 52 54 20 e. Thus INSERT
10160 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 OR FAIL, INSERT
10170 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 OR IGNORE, INSER
10180 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a T OR ROLLBACK,.*
10190 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 * and INSERT OR
101a0 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 ABORT make no ch
101b0 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 anges to the ret
101c0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 urn value of thi
101d0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 s.** routine whe
101e0 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f n their insertio
101f0 6e 20 66 61 69 6c 73 2e 20 20 57 68 65 6e 20 49 n fails. When I
10200 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 NSERT OR REPLACE
10210 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 .** encounters a
10220 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c constraint viol
10230 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e ation, it does n
10240 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a ot fail. The.**
10250 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 INSERT continue
10260 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 s to completion
10270 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 after deleting r
10280 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a ows that caused.
10290 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e ** the constrain
102a0 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 t problem so INS
102b0 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 ERT OR REPLACE w
102c0 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 ill always chang
102d0 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 e.** the return
102e0 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e value of this in
102f0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 46 terface..**.** F
10300 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 or the purposes
10310 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c of this routine,
10320 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 an [INSERT] is
10330 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a considered to.**
10340 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 be successful e
10350 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 ven if it is sub
10360 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 sequently rolled
10370 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 back..**.** INV
10380 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
10390 48 31 32 32 32 31 7d 20 54 68 65 20 5b 73 71 6c H12221} The [sql
103a0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 ite3_last_insert
103b0 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e 63 74 69 _rowid()] functi
103c0 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 0a on shall return.
103d0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
103e0 5b 72 6f 77 69 64 5d 0a 2a 2a 20 20 20 20 20 20 [rowid].**
103f0 20 20 20 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 of the most
10400 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 recent successfu
10410 6c 20 5b 49 4e 53 45 52 54 5d 20 70 65 72 66 6f l [INSERT] perfo
10420 72 6d 65 64 20 6f 6e 20 74 68 65 20 73 61 6d 65 rmed on the same
10430 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 .** [da
10440 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
10450 6e 5d 20 61 6e 64 20 77 69 74 68 69 6e 20 74 68 n] and within th
10460 65 20 73 61 6d 65 20 6f 72 20 68 69 67 68 65 72 e same or higher
10470 20 6c 65 76 65 6c 0a 2a 2a 20 20 20 20 20 20 20 level.**
10480 20 20 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 trigger conte
10490 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66 20 74 xt, or zero if t
104a0 68 65 72 65 20 68 61 76 65 20 62 65 65 6e 20 6e here have been n
104b0 6f 20 71 75 61 6c 69 66 79 69 6e 67 0a 2a 2a 20 o qualifying.**
104c0 20 20 20 20 20 20 20 20 20 5b 49 4e 53 45 52 54 [INSERT
104d0 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a ] statements..**
104e0 0a 2a 2a 20 7b 48 31 32 32 32 33 7d 20 54 68 65 .** {H12223} The
104f0 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 [sqlite3_last_i
10500 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 66 nsert_rowid()] f
10510 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65 unction shall re
10520 74 75 72 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 turn the.**
10530 20 20 20 20 20 73 61 6d 65 20 76 61 6c 75 65 20 same value
10540 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d when called from
10550 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 the same trigge
10560 72 20 63 6f 6e 74 65 78 74 0a 2a 2a 20 20 20 20 r context.**
10570 20 20 20 20 20 20 69 6d 6d 65 64 69 61 74 65 6c immediatel
10580 79 20 62 65 66 6f 72 65 20 61 6e 64 20 61 66 74 y before and aft
10590 65 72 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e er a [ROLLBACK].
105a0 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f .**.** ASSUMPTIO
105b0 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 33 NS:.**.** {A1223
105c0 32 7d 20 49 66 20 61 20 73 65 70 61 72 61 74 65 2} If a separate
105d0 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 thread performs
105e0 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 a new [INSERT]
105f0 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 on the same.**
10600 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65 database
10610 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c connection whil
10620 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c e the [sqlite3_l
10630 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 ast_insert_rowid
10640 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ()].**
10650 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e function is runn
10660 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 ing and thus cha
10670 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e nges the last in
10680 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a sert [rowid],.**
10690 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 then t
106a0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
106b0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 d by [sqlite3_la
106c0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 st_insert_rowid(
106d0 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 )] is.**
106e0 20 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 unpredictable
106f0 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 and might not eq
10700 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f ual either the o
10710 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a ld or the new.**
10720 20 20 20 20 20 20 20 20 20 20 6c 61 73 74 20 69 last i
10730 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a nsert [rowid]..*
10740 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 /.sqlite3_int64
10750 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 sqlite3_last_ins
10760 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 ert_rowid(sqlite
10770 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 3*);../*.** CAPI
10780 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 3REF: Count The
10790 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d Number Of Rows M
107a0 6f 64 69 66 69 65 64 20 7b 48 31 32 32 34 30 7d odified {H12240}
107b0 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S10600>.**.**
107c0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 This function re
107d0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
107e0 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 of database row
107f0 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e s that were chan
10800 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 ged.** or insert
10810 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 ed or deleted by
10820 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
10830 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c ly completed SQL
10840 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e statement.** on
10850 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
10860 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 onnection] speci
10870 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 fied by the firs
10880 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 t parameter..**
10890 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 Only changes tha
108a0 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 t are directly s
108b0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 pecified by the
108c0 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 [INSERT], [UPDAT
108d0 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 E],.** or [DELET
108e0 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 E] statement are
108f0 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c counted. Auxil
10900 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 iary changes cau
10910 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 sed by.** trigge
10920 72 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 rs are not count
10930 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c ed. Use the [sql
10940 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
10950 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a es()] function.*
10960 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f * to find the to
10970 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 tal number of ch
10980 61 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 anges including
10990 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 changes caused b
109a0 79 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a y triggers..**.*
109b0 2a 20 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 * A "row change"
109c0 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 is a change to
109d0 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 a single row of
109e0 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a a single table.*
109f0 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 * caused by an I
10a00 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f NSERT, DELETE, o
10a10 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 r UPDATE stateme
10a20 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a nt. Rows that.*
10a30 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 * are changed as
10a40 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 side effects of
10a50 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 REPLACE constra
10a60 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a int resolution,.
10a70 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f ** rollback, ABO
10a80 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 44 RT processing, D
10a90 52 4f 50 20 54 41 42 4c 45 2c 20 6f 72 20 62 79 ROP TABLE, or by
10aa0 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 any other.** me
10ab0 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 chanisms do not
10ac0 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74 20 count as direct
10ad0 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a row changes..**.
10ae0 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f ** A "trigger co
10af0 6e 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 ntext" is a scop
10b00 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 e of execution t
10b10 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a hat begins and.*
10b20 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 * ends with the
10b30 73 63 72 69 70 74 20 6f 66 20 61 20 74 72 69 67 script of a trig
10b40 67 65 72 2e 20 20 4d 6f 73 74 20 53 51 4c 20 73 ger. Most SQL s
10b50 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a tatements are.**
10b60 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 evaluated outsi
10b70 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 de of any trigge
10b80 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20 r. This is the
10b90 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 "top level".** t
10ba0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 rigger context.
10bb0 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69 If a trigger fi
10bc0 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 res from the top
10bd0 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 level, a.** new
10be0 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 trigger context
10bf0 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 is entered for
10c00 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 the duration of
10c10 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 that one.** trig
10c20 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 ger. Subtrigger
10c30 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 s create subcont
10c40 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 exts for their d
10c50 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43 uration..**.** C
10c60 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
10c70 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 exec()] or [sqli
10c80 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 te3_step()] recu
10c90 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 rsively does.**
10ca0 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 not create a new
10cb0 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 trigger context
10cc0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e ..**.** This fun
10cd0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 ction returns th
10ce0 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 e number of dire
10cf0 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 ct row changes i
10d00 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 n the.** most re
10d10 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 cent INSERT, UPD
10d20 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 ATE, or DELETE s
10d30 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 tatement within
10d40 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 the same.** trig
10d50 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a ger context..**.
10d60 2a 2a 20 54 68 75 73 2c 20 77 68 65 6e 20 63 61 ** Thus, when ca
10d70 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f lled from the to
10d80 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 p level, this fu
10d90 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 nction returns t
10da0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 he.** number of
10db0 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d changes in the m
10dc0 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 ost recent INSER
10dd0 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 T, UPDATE, or DE
10de0 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 LETE.** that als
10df0 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 o occurred at th
10e00 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 57 69 e top level. Wi
10e10 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 thin the body of
10e20 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 a trigger,.** t
10e30 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 he sqlite3_chang
10e40 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 es() interface c
10e50 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 an be called to
10e60 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 find the number
10e70 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e of.** changes in
10e80 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
10e90 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 ly completed INS
10ea0 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 ERT, UPDATE, or
10eb0 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d DELETE.** statem
10ec0 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 ent within the b
10ed0 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 ody of the same
10ee0 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 trigger..** Howe
10ef0 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 ver, the number
10f00 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f returned does no
10f10 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 t include change
10f20 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 s.** caused by s
10f30 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 ubtriggers since
10f40 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 those have thei
10f50 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 0a 2a r own context..*
10f60 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c *.** SQLite impl
10f70 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 ements the comma
10f80 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 nd "DELETE FROM
10f90 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61 table" without a
10fa0 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a WHERE clause.**
10fb0 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 by dropping and
10fc0 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20 recreating the
10fd0 74 61 62 6c 65 2e 20 20 44 6f 69 6e 67 20 73 6f table. Doing so
10fe0 20 69 73 20 6d 75 63 68 20 66 61 73 74 65 72 20 is much faster
10ff0 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 than going.** th
11000 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 rough and deleti
11010 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c ng individual el
11020 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 ements from the
11030 74 61 62 6c 65 2e 20 20 42 65 63 61 75 73 65 20 table. Because
11040 6f 66 20 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d of this.** optim
11050 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c ization, the del
11060 65 74 69 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54 etions in "DELET
11070 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72 E FROM table" ar
11080 65 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65 e not row change
11090 73 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f s and.** will no
110a0 74 20 62 65 20 63 6f 75 6e 74 65 64 20 62 79 20 t be counted by
110b0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e the sqlite3_chan
110c0 67 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65 ges() or [sqlite
110d0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 3_total_changes(
110e0 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c )].** functions,
110f0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 regardless of t
11100 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 he number of ele
11110 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 65 20 ments that were
11120 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e originally.** in
11130 20 74 68 65 20 74 61 62 6c 65 2e 20 20 54 6f 20 the table. To
11140 67 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 get an accurate
11150 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d count of the num
11160 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 ber of rows dele
11170 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c ted, use.** "DEL
11180 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 ETE FROM table W
11190 48 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e HERE 1" instead.
111a0 20 20 4f 72 20 72 65 63 6f 6d 70 69 6c 65 20 75 Or recompile u
111b0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c sing the.** [SQL
111c0 49 54 45 5f 4f 4d 49 54 5f 54 52 55 4e 43 41 54 ITE_OMIT_TRUNCAT
111d0 45 5f 4f 50 54 49 4d 49 5a 41 54 49 4f 4e 5d 20 E_OPTIMIZATION]
111e0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
111f0 69 6f 6e 20 74 6f 20 64 69 73 61 62 6c 65 20 74 ion to disable t
11200 68 65 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 he.** optimizati
11210 6f 6e 20 6f 6e 20 61 6c 6c 20 71 75 65 72 69 65 on on all querie
11220 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 s..**.** INVARIA
11230 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 NTS:.**.** {H122
11240 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 41} The [sqlite3
11250 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 _changes()] func
11260 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72 tion shall retur
11270 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a n the number of.
11280 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 77 20 ** row
11290 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 changes caused b
112a0 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e y the most recen
112b0 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 t INSERT, UPDATE
112c0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 ,.** or
112d0 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e DELETE statemen
112e0 74 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 t on the same da
112f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
11300 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 n and.**
11310 20 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d within the sam
11320 65 20 6f 72 20 68 69 67 68 65 72 20 74 72 69 67 e or higher trig
11330 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20 ger context, or
11340 7a 65 72 6f 20 69 66 20 74 68 65 72 65 20 68 61 zero if there ha
11350 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e ve.** n
11360 6f 74 20 62 65 65 6e 20 61 6e 79 20 71 75 61 6c ot been any qual
11370 69 66 79 69 6e 67 20 72 6f 77 20 63 68 61 6e 67 ifying row chang
11380 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 34 es..**.** {H1224
11390 33 7d 20 53 74 61 74 65 6d 65 6e 74 73 20 6f 66 3} Statements of
113a0 20 74 68 65 20 66 6f 72 6d 20 22 44 45 4c 45 54 the form "DELET
113b0 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d 65 E FROM tablename
113c0 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20 20 " with no.**
113d0 20 20 20 20 20 20 57 48 45 52 45 20 63 6c 61 75 WHERE clau
113e0 73 65 20 73 68 61 6c 6c 20 63 61 75 73 65 20 73 se shall cause s
113f0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 ubsequent calls
11400 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b to.** [
11410 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 sqlite3_changes(
11420 29 5d 20 74 6f 20 72 65 74 75 72 6e 20 7a 65 72 )] to return zer
11430 6f 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 o, regardless of
11440 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
11450 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 number of rows
11460 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68 originally in th
11470 65 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41 e table..**.** A
11480 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a SSUMPTIONS:.**.*
11490 2a 20 7b 41 31 32 32 35 32 7d 20 49 66 20 61 20 * {A12252} If a
114a0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 separate thread
114b0 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e makes changes on
114c0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
114d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se connection.**
114e0 20 20 20 20 20 20 20 20 20 20 77 68 69 6c 65 20 while
114f0 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 [sqlite3_changes
11500 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 ()] is running t
11510 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 hen the value re
11520 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 turned.**
11530 20 20 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 is unpredicta
11540 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e ble and not mean
11550 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 ingful..*/.int s
11560 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 qlite3_changes(s
11570 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
11580 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c CAPI3REF: Total
11590 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 Number Of Rows
115a0 4d 6f 64 69 66 69 65 64 20 7b 48 31 32 32 36 30 Modified {H12260
115b0 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a } <S10600>.**.**
115c0 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 This function r
115d0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
115e0 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 r of row changes
115f0 20 63 61 75 73 65 64 20 62 79 20 49 4e 53 45 52 caused by INSER
11600 54 2c 0a 2a 2a 20 55 50 44 41 54 45 20 6f 72 20 T,.** UPDATE or
11610 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 DELETE statement
11620 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74 s since the [dat
11630 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
11640 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a ] was opened..**
11650 20 54 68 65 20 63 6f 75 6e 74 20 69 6e 63 6c 75 The count inclu
11660 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 20 des all changes
11670 66 72 6f 6d 20 61 6c 6c 20 74 72 69 67 67 65 72 from all trigger
11680 20 63 6f 6e 74 65 78 74 73 2e 20 20 48 6f 77 65 contexts. Howe
11690 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e ver,.** the coun
116a0 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 t does not inclu
116b0 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 de changes used
116c0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 52 45 50 to implement REP
116d0 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 73 LACE constraints
116e0 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b ,.** do rollback
116f0 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65 s or ABORT proce
11700 73 73 69 6e 67 2c 20 6f 72 20 44 52 4f 50 20 74 ssing, or DROP t
11710 61 62 6c 65 20 70 72 6f 63 65 73 73 69 6e 67 2e able processing.
11720 0a 2a 2a 20 54 68 65 20 63 68 61 6e 67 65 73 20 .** The changes
11730 61 72 65 20 63 6f 75 6e 74 65 64 20 61 73 20 73 are counted as s
11740 6f 6f 6e 20 61 73 20 74 68 65 20 73 74 61 74 65 oon as the state
11750 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 ment that makes
11760 74 68 65 6d 20 69 73 0a 2a 2a 20 63 6f 6d 70 6c them is.** compl
11770 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 eted (when the s
11780 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 tatement handle
11790 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 is passed to [sq
117a0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f lite3_reset()] o
117b0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 r.** [sqlite3_fi
117c0 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a nalize()])..**.*
117d0 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 * SQLite impleme
117e0 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 nts the command
117f0 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 "DELETE FROM tab
11800 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20 57 48 le" without a WH
11810 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79 ERE clause.** by
11820 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65 dropping and re
11830 63 72 65 61 74 69 6e 67 20 74 68 65 20 74 61 62 creating the tab
11840 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75 le. (This is mu
11850 63 68 20 66 61 73 74 65 72 20 74 68 61 6e 20 67 ch faster than g
11860 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 oing.** through
11870 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 and deleting ind
11880 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 ividual elements
11890 20 66 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e from the table.
118a0 29 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 ) Because of th
118b0 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 is.** optimizati
118c0 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74 69 6f 6e on, the deletion
118d0 73 20 69 6e 20 22 44 45 4c 45 54 45 20 46 52 4f s in "DELETE FRO
118e0 4d 20 74 61 62 6c 65 22 20 61 72 65 20 6e 6f 74 M table" are not
118f0 20 72 6f 77 20 63 68 61 6e 67 65 73 20 61 6e 64 row changes and
11900 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 .** will not be
11910 63 6f 75 6e 74 65 64 20 62 79 20 74 68 65 20 73 counted by the s
11920 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 qlite3_changes()
11930 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 or [sqlite3_tot
11940 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a al_changes()].**
11950 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72 65 67 61 functions, rega
11960 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75 rdless of the nu
11970 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 mber of elements
11980 20 74 68 61 74 20 77 65 72 65 20 6f 72 69 67 69 that were origi
11990 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68 65 20 nally.** in the
119a0 74 61 62 6c 65 2e 20 20 54 6f 20 67 65 74 20 61 table. To get a
119b0 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74 n accurate count
119c0 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f of the number o
119d0 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 f rows deleted,
119e0 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 use.** "DELETE F
119f0 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 ROM table WHERE
11a00 31 22 20 69 6e 73 74 65 61 64 2e 20 20 20 4f 72 1" instead. Or
11a10 20 72 65 63 6f 6d 70 69 6c 65 20 75 73 69 6e 67 recompile using
11a20 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
11a30 4f 4d 49 54 5f 54 52 55 4e 43 41 54 45 5f 4f 50 OMIT_TRUNCATE_OP
11a40 54 49 4d 49 5a 41 54 49 4f 4e 5d 20 63 6f 6d 70 TIMIZATION] comp
11a50 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
11a60 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 0a 2a to disable the.*
11a70 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 6f * optimization o
11a80 6e 20 61 6c 6c 20 71 75 65 72 69 65 73 2e 0a 2a n all queries..*
11a90 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 *.** See also th
11aa0 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 e [sqlite3_chang
11ab0 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e es()] interface.
11ac0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
11ad0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 36 31 S:.**.** {H12261
11ae0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 } The [sqlite3_t
11af0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 otal_changes()]
11b00 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61 returns the tota
11b10 6c 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 l number.**
11b20 20 20 20 20 20 6f 66 20 72 6f 77 20 63 68 61 6e of row chan
11b30 67 65 73 20 63 61 75 73 65 64 20 62 79 20 49 4e ges caused by IN
11b40 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 61 6e SERT, UPDATE, an
11b50 64 2f 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 20 d/or DELETE.**
11b60 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e statemen
11b70 74 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b ts on the same [
11b80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
11b90 69 6f 6e 5d 2c 20 69 6e 20 61 6e 79 0a 2a 2a 20 ion], in any.**
11ba0 20 20 20 20 20 20 20 20 20 74 72 69 67 67 65 72 trigger
11bb0 20 63 6f 6e 74 65 78 74 2c 20 73 69 6e 63 65 20 context, since
11bc0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
11bd0 6e 65 63 74 69 6f 6e 20 77 61 73 20 63 72 65 61 nection was crea
11be0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 ted..**.** {H122
11bf0 36 33 7d 20 53 74 61 74 65 6d 65 6e 74 73 20 6f 63} Statements o
11c00 66 20 74 68 65 20 66 6f 72 6d 20 22 44 45 4c 45 f the form "DELE
11c10 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d TE FROM tablenam
11c20 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20 e" with no.**
11c30 20 20 20 20 20 20 20 57 48 45 52 45 20 63 6c 61 WHERE cla
11c40 75 73 65 20 73 68 61 6c 6c 20 6e 6f 74 20 63 68 use shall not ch
11c50 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 ange the value r
11c60 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 eturned.**
11c70 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f by [sqlite3_
11c80 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d total_changes()]
11c90 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 ..**.** ASSUMPTI
11ca0 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 ONS:.**.** {A122
11cb0 36 34 7d 20 49 66 20 61 20 73 65 70 61 72 61 74 64} If a separat
11cc0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 e thread makes c
11cd0 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 hanges on the sa
11ce0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e me database conn
11cf0 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 ection.**
11d00 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 while [sqlite
11d10 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 3_total_changes(
11d20 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 )] is running th
11d30 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 en the value.**
11d40 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 65 returne
11d50 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 d is unpredictab
11d60 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 le and not meani
11d70 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ngful..*/.int sq
11d80 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e lite3_total_chan
11d90 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a ges(sqlite3*);..
11da0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
11db0 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 Interrupt A Long
11dc0 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 20 7b -Running Query {
11dd0 48 31 32 32 37 30 7d 20 3c 53 33 30 35 30 30 3e H12270} <S30500>
11de0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 .**.** This func
11df0 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 tion causes any
11e00 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 pending database
11e10 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 operation to ab
11e20 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 ort and.** retur
11e30 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 n at its earlies
11e40 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 t opportunity. T
11e50 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 his routine is t
11e60 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c ypically.** call
11e70 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 ed in response t
11e80 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 o a user action
11e90 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 such as pressing
11ea0 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 "Cancel".** or
11eb0 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 Ctrl-C where the
11ec0 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f user wants a lo
11ed0 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 ng query operati
11ee0 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d on to halt.** im
11ef0 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a mediately..**.**
11f00 20 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 It is safe to c
11f10 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 all this routine
11f20 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 from a thread d
11f30 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 ifferent from th
11f40 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 e.** thread that
11f50 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 is currently ru
11f60 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 nning the databa
11f70 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 se operation. B
11f80 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 ut it.** is not
11f90 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 safe to call thi
11fa0 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 s routine with a
11fb0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
11fc0 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 ction] that.** i
11fd0 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 s closed or migh
11fe0 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 t close before s
11ff0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
12000 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a () returns..**.*
12010 2a 20 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 * If an SQL oper
12020 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 ation is very ne
12030 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 arly finished at
12040 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a the time when.*
12050 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 * sqlite3_interr
12060 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c upt() is called,
12070 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e then it might n
12080 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 ot have an oppor
12090 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 tunity.** to be
120a0 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 interrupted and
120b0 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 might continue t
120c0 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a o completion..**
120d0 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f 70 65 72 61 .** An SQL opera
120e0 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 tion that is int
120f0 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 errupted will re
12100 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 turn [SQLITE_INT
12110 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 49 66 20 74 ERRUPT]..** If t
12120 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 he interrupted S
12130 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 QL operation is
12140 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 an INSERT, UPDAT
12150 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 E, or DELETE.**
12160 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 that is inside a
12170 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 n explicit trans
12180 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 action, then the
12190 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 entire transact
121a0 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 ion.** will be r
121b0 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d olled back autom
121c0 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 atically..**.**
121d0 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 A call to sqlite
121e0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 68 61 3_interrupt() ha
121f0 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 s no effect on S
12200 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a QL statements.**
12210 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 that are starte
12220 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f d after sqlite3_
12230 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 interrupt() retu
12240 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 rns..**.** INVAR
12250 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 IANTS:.**.** {H1
12260 32 32 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 2271} The [sqlit
12270 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 20 e3_interrupt()]
12280 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 66 interface will f
12290 6f 72 63 65 20 61 6c 6c 20 72 75 6e 6e 69 6e 67 orce all running
122a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c .** SQL
122b0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f statements asso
122c0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 ciated with the
122d0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f same database co
122e0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 nnection.**
122f0 20 20 20 20 20 74 6f 20 68 61 6c 74 20 61 66 74 to halt aft
12300 65 72 20 70 72 6f 63 65 73 73 69 6e 67 20 61 74 er processing at
12310 20 6d 6f 73 74 20 6f 6e 65 20 61 64 64 69 74 69 most one additi
12320 6f 6e 61 6c 20 72 6f 77 20 6f 66 20 64 61 74 61 onal row of data
12330 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 37 32 7d ..**.** {H12272}
12340 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 Any SQL stateme
12350 6e 74 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 nt that is inter
12360 72 75 70 74 65 64 20 62 79 20 5b 73 71 6c 69 74 rupted by [sqlit
12370 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a e3_interrupt()].
12380 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c ** will
12390 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
123a0 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 0a 2a INTERRUPT]..**.*
123b0 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a * ASSUMPTIONS:.*
123c0 2a 0a 2a 2a 20 7b 41 31 32 32 37 39 7d 20 49 66 *.** {A12279} If
123d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
123e0 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 nnection closes
123f0 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 while [sqlite3_i
12400 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20 nterrupt()].**
12410 20 20 20 20 20 20 20 20 69 73 20 72 75 6e 6e 69 is runni
12420 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e ng then bad thin
12430 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 gs will likely h
12440 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 appen..*/.void s
12450 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
12460 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
12470 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 ** CAPI3REF: Det
12480 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c ermine If An SQL
12490 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f Statement Is Co
124a0 6d 70 6c 65 74 65 20 7b 48 31 30 35 31 30 7d 20 mplete {H10510}
124b0 3c 53 37 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S70200>.**.** T
124c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
124d0 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6d e useful for com
124e0 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 mand-line input
124f0 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 to determine if
12500 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 the.** currently
12510 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 entered text se
12520 65 6d 73 20 74 6f 20 66 6f 72 6d 20 63 6f 6d 70 ems to form comp
12530 6c 65 74 65 20 61 20 53 51 4c 20 73 74 61 74 65 lete a SQL state
12540 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 ment or.** if ad
12550 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 ditional input i
12560 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 s needed before
12570 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 sending the text
12580 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 into.** SQLite
12590 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 54 68 for parsing. Th
125a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 ese routines ret
125b0 75 72 6e 20 74 72 75 65 20 69 66 20 74 68 65 20 urn true if the
125c0 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 input string.**
125d0 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 appears to be a
125e0 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 complete SQL sta
125f0 74 65 6d 65 6e 74 2e 20 20 41 20 73 74 61 74 65 tement. A state
12600 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 ment is judged t
12610 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 o be.** complete
12620 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 if it ends with
12630 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b a semicolon tok
12640 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 en and is not a
12650 66 72 61 67 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a fragment of a.**
12660 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 CREATE TRIGGER
12670 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 65 6d 69 statement. Semi
12680 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 colons that are
12690 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a embedded within.
126a0 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 ** string litera
126b0 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 ls or quoted ide
126c0 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 ntifier names or
126d0 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f comments are no
126e0 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 t.** independent
126f0 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 tokens (they ar
12700 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f e part of the to
12710 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 ken in which the
12720 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 y are.** embedde
12730 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e d) and thus do n
12740 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 ot count as a st
12750 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 atement terminat
12760 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 or..**.** These
12770 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 routines do not
12780 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 parse the SQL st
12790 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a atements thus.**
127a0 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 will not detect
127b0 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 syntactically i
127c0 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a ncorrect SQL..**
127d0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
127e0 2a 2a 0a 2a 2a 20 7b 48 31 30 35 31 31 7d 20 41 **.** {H10511} A
127f0 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 61 6c successful eval
12800 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 uation of [sqlit
12810 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6f e3_complete()] o
12820 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 r.** [s
12830 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 qlite3_complete1
12840 36 28 29 5d 20 66 75 6e 63 74 69 6f 6e 73 20 73 6()] functions s
12850 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 hall.**
12860 20 72 65 74 75 72 6e 20 61 20 6e 75 6d 65 72 69 return a numeri
12870 63 20 31 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 c 1 if and only
12880 69 66 20 74 68 65 20 6c 61 73 74 20 6e 6f 6e 2d if the last non-
12890 77 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 20 20 whitespace.**
128a0 20 20 20 20 20 20 20 74 6f 6b 65 6e 20 69 6e 20 token in
128b0 74 68 65 69 72 20 69 6e 70 75 74 20 69 73 20 61 their input is a
128c0 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 68 61 74 20 semicolon that
128d0 69 73 20 6e 6f 74 20 69 6e 20 62 65 74 77 65 65 is not in betwee
128e0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 n.** th
128f0 65 20 42 45 47 49 4e 20 61 6e 64 20 45 4e 44 20 e BEGIN and END
12900 6f 66 20 61 20 43 52 45 41 54 45 20 54 52 49 47 of a CREATE TRIG
12910 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a GER statement..*
12920 2a 0a 2a 2a 20 7b 48 31 30 35 31 32 7d 20 49 66 *.** {H10512} If
12930 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
12940 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 tion error occur
12950 73 20 64 75 72 69 6e 67 20 61 6e 20 69 6e 76 6f s during an invo
12960 63 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 cation.**
12970 20 20 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 63 of [sqlite3_c
12980 6f 6d 70 6c 65 74 65 28 29 5d 20 6f 72 20 5b 73 omplete()] or [s
12990 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 qlite3_complete1
129a0 36 28 29 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 6()] then the.**
129b0 20 20 20 20 20 20 20 20 20 20 72 6f 75 74 69 6e routin
129c0 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b e shall return [
129d0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a SQLITE_NOMEM]..*
129e0 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 *.** ASSUMPTIONS
129f0 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 30 35 31 32 7d :.**.** {A10512}
12a00 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 The input to [s
12a10 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 qlite3_complete(
12a20 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 )] must be a zer
12a30 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 o-terminated.**
12a40 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 20 73 UTF-8 s
12a50 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 tring..**.** {A1
12a60 30 35 31 33 7d 20 54 68 65 20 69 6e 70 75 74 20 0513} The input
12a70 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 to [sqlite3_comp
12a80 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 lete16()] must b
12a90 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 e a zero-termina
12aa0 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ted.**
12ab0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e UTF-16 string in
12ac0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
12ad0 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 er..*/.int sqlit
12ae0 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 e3_complete(cons
12af0 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e t char *sql);.in
12b00 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 t sqlite3_comple
12b10 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 te16(const void
12b20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 *sql);../*.** CA
12b30 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 PI3REF: Register
12b40 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 A Callback To H
12b50 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 andle SQLITE_BUS
12b60 59 20 45 72 72 6f 72 73 20 7b 48 31 32 33 31 30 Y Errors {H12310
12b70 7d 20 3c 53 34 30 34 30 30 3e 0a 2a 2a 0a 2a 2a } <S40400>.**.**
12b80 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 This routine se
12b90 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 ts a callback fu
12ba0 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 nction that migh
12bb0 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 t be invoked whe
12bc0 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 never.** an atte
12bd0 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f mpt is made to o
12be0 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 pen a database t
12bf0 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 able that anothe
12c00 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 r thread.** or p
12c10 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 rocess has locke
12c20 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 d..**.** If the
12c30 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 busy callback is
12c40 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c NULL, then [SQL
12c50 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 ITE_BUSY] or [SQ
12c60 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b LITE_IOERR_BLOCK
12c70 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e ED].** is return
12c80 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 ed immediately u
12c90 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 pon encountering
12ca0 20 74 68 65 20 6c 6f 63 6b 2e 20 49 66 20 74 68 the lock. If th
12cb0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a e busy callback.
12cc0 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 ** is not NULL,
12cd0 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 then the callbac
12ce0 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 k will be invoke
12cf0 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d d with two argum
12d00 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ents..**.** The
12d10 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
12d20 6f 20 74 68 65 20 68 61 6e 64 6c 65 72 20 69 73 o the handler is
12d30 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 a copy of the v
12d40 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 oid* pointer whi
12d50 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 ch.** is the thi
12d60 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 rd argument to s
12d70 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
12d80 6c 65 72 28 29 2e 20 20 54 68 65 20 73 65 63 6f ler(). The seco
12d90 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a nd argument to.*
12da0 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 63 61 * the handler ca
12db0 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 llback is the nu
12dc0 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 mber of times th
12dd0 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 at the busy hand
12de0 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 ler has.** been
12df0 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 invoked for this
12e00 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 locking event.
12e10 20 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 If the.** busy
12e20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
12e30 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 0, then no addi
12e40 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 tional attempts
12e50 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 are made to.** a
12e60 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 ccess the databa
12e70 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 se and [SQLITE_B
12e80 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f USY] or [SQLITE_
12e90 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 IOERR_BLOCKED] i
12ea0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 s returned..** I
12eb0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 f the callback r
12ec0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c eturns non-zero,
12ed0 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 then another at
12ee0 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 tempt.** is made
12ef0 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 to open the dat
12f00 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e abase for readin
12f10 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 g and the cycle
12f20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 repeats..**.** T
12f30 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 he presence of a
12f40 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f busy handler do
12f50 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 es not guarantee
12f60 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 that it will be
12f70 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e invoked.** when
12f80 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 there is lock c
12f90 6f 6e 74 65 6e 74 69 6f 6e 2e 20 49 66 20 53 51 ontention. If SQ
12fa0 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 Lite determines
12fb0 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 that invoking th
12fc0 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 e busy.** handle
12fd0 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 r could result i
12fe0 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 n a deadlock, it
12ff0 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 will go ahead a
13000 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 nd return [SQLIT
13010 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 E_BUSY].** or [S
13020 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 QLITE_IOERR_BLOC
13030 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 KED] instead of
13040 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 invoking the bus
13050 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f y handler..** Co
13060 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 nsider a scenari
13070 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 o where one proc
13080 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 ess is holding a
13090 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a read lock that.
130a0 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 ** it is trying
130b0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 to promote to a
130c0 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e reserved lock an
130d0 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 d.** a second pr
130e0 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 ocess is holding
130f0 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b a reserved lock
13100 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 that it is tryi
13110 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 ng.** to promote
13120 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 to an exclusive
13130 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 lock. The firs
13140 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 t process cannot
13150 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 proceed.** beca
13160 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 use it is blocke
13170 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 d by the second
13180 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 and the second p
13190 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a rocess cannot.**
131a0 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 proceed because
131b0 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 it is blocked b
131c0 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 y the first. If
131d0 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a both processes.
131e0 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 ** invoke the bu
131f0 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 sy handlers, nei
13200 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 ther will make a
13210 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 ny progress. Th
13220 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 erefore,.** SQLi
13230 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 te returns [SQLI
13240 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 TE_BUSY] for the
13250 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 first process,
13260 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 hoping that this
13270 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 .** will induce
13280 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 the first proces
13290 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 s to release its
132a0 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 read lock and a
132b0 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f llow.** the seco
132c0 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 nd process to pr
132d0 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 oceed..**.** The
132e0 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 default busy ca
132f0 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a llback is NULL..
13300 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 **.** The [SQLIT
13310 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 E_BUSY] error is
13320 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 converted to [S
13330 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 QLITE_IOERR_BLOC
13340 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c KED].** when SQL
13350 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 ite is in the mi
13360 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 ddle of a large
13370 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 transaction wher
13380 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 e all the.** cha
13390 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 nges will not fi
133a0 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 t into the in-me
133b0 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c mory cache. SQL
133c0 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 ite will.** alre
133d0 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 ady hold a RESER
133e0 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 VED lock on the
133f0 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 database file, b
13400 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 ut it needs.** t
13410 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c o promote this l
13420 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 ock to EXCLUSIVE
13430 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 so that it can
13440 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 spill cache.** p
13450 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 ages into the da
13460 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 tabase file with
13470 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 out harm to conc
13480 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 urrent.** reader
13490 73 2e 20 20 49 66 20 69 74 20 69 73 20 75 6e 61 s. If it is una
134a0 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 ble to promote t
134b0 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 he lock, then th
134c0 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 e in-memory.** c
134d0 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 ache will be lef
134e0 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 t in an inconsis
134f0 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 tent state and s
13500 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 o the error.** c
13510 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 ode is promoted
13520 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 from the relativ
13530 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 ely benign [SQLI
13540 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 TE_BUSY] to.** t
13550 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b he more severe [
13560 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f SQLITE_IOERR_BLO
13570 43 4b 45 44 5d 2e 20 20 54 68 69 73 20 65 72 72 CKED]. This err
13580 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f or code promotio
13590 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 n.** forces an a
135a0 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 utomatic rollbac
135b0 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 k of the changes
135c0 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 . See the.** <a
135d0 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f href="/cvstrac/
135e0 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f wiki?p=Corruptio
135f0 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 nFollowingBusyEr
13600 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 ror">.** Corrupt
13610 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 ionFollowingBusy
13620 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 Error</a> wiki p
13630 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 age for a discus
13640 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 sion of why.** t
13650 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 his is important
13660 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 ..**.** There ca
13670 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 n only be a sing
13680 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 le busy handler
13690 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 defined for each
136a0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
136b0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 nnection]. Sett
136c0 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 ing a new busy h
136d0 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e andler clears an
136e0 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 y.** previously
136f0 73 65 74 20 68 61 6e 64 6c 65 72 2e 20 20 4e 6f set handler. No
13700 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 te that calling
13710 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 [sqlite3_busy_ti
13720 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c meout()].** will
13730 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 also set or cle
13740 61 72 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ar the busy hand
13750 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 ler..**.** The b
13760 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f usy callback sho
13770 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 uld not take any
13780 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d actions which m
13790 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 odify the.** dat
137a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
137b0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 that invoked th
137c0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 e busy handler.
137d0 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e Any such action
137e0 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 s.** result in u
137f0 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f ndefined behavio
13800 72 2e 0a 2a 2a 20 0a 2a 2a 20 49 4e 56 41 52 49 r..** .** INVARI
13810 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 ANTS:.**.** {H12
13820 33 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 311} The [sqlite
13830 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 3_busy_handler(D
13840 2c 43 2c 41 29 5d 20 66 75 6e 63 74 69 6f 6e 20 ,C,A)] function
13850 73 68 61 6c 6c 20 72 65 70 6c 61 63 65 0a 2a 2a shall replace.**
13860 20 20 20 20 20 20 20 20 20 20 62 75 73 79 20 63 busy c
13870 61 6c 6c 62 61 63 6b 20 69 6e 20 74 68 65 20 5b allback in the [
13880 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
13890 69 6f 6e 5d 20 44 20 77 69 74 68 20 61 20 6e 65 ion] D with a ne
138a0 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 w.** a
138b0 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 new busy handler
138c0 20 43 20 61 6e 64 20 61 70 70 6c 69 63 61 74 69 C and applicati
138d0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 on data pointer
138e0 41 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 32 A..**.** {H12312
138f0 7d 20 4e 65 77 6c 79 20 63 72 65 61 74 65 64 20 } Newly created
13900 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
13910 74 69 6f 6e 73 5d 20 73 68 61 6c 6c 20 68 61 76 tions] shall hav
13920 65 20 61 20 62 75 73 79 0a 2a 2a 20 20 20 20 20 e a busy.**
13930 20 20 20 20 20 68 61 6e 64 6c 65 72 20 6f 66 20 handler of
13940 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 NULL..**.** {H12
13950 33 31 34 7d 20 57 68 65 6e 20 74 77 6f 20 6f 72 314} When two or
13960 20 6d 6f 72 65 20 5b 64 61 74 61 62 61 73 65 20 more [database
13970 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 73 68 61 connections] sha
13980 72 65 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 re a.**
13990 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 [sqlite3_enable
139a0 5f 73 68 61 72 65 64 5f 63 61 63 68 65 20 7c 20 _shared_cache |
139b0 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 5d 2c 0a 2a common cache],.*
139c0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62 * the b
139d0 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 usy handler for
139e0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
139f0 6e 65 63 74 69 6f 6e 20 63 75 72 72 65 6e 74 6c nection currentl
13a00 79 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 y using.**
13a10 20 20 20 20 74 68 65 20 63 61 63 68 65 20 73 68 the cache sh
13a20 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 all be invoked w
13a30 68 65 6e 20 74 68 65 20 63 61 63 68 65 20 65 6e hen the cache en
13a40 63 6f 75 6e 74 65 72 73 20 61 20 6c 6f 63 6b 2e counters a lock.
13a50 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 36 7d 20 .**.** {H12316}
13a60 49 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 If a busy handle
13a70 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 r callback retur
13a80 6e 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 ns zero, then th
13a90 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 e SQLite interfa
13aa0 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 ce.** t
13ab0 68 61 74 20 70 72 6f 76 6f 6b 65 64 20 74 68 65 hat provoked the
13ac0 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 20 73 locking event s
13ad0 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c hall return [SQL
13ae0 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a ITE_BUSY]..**.**
13af0 20 7b 48 31 32 33 31 38 7d 20 53 51 4c 69 74 65 {H12318} SQLite
13b00 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 73 20 74 shall invokes t
13b10 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 he busy handler
13b20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e with two argumen
13b30 74 73 20 77 68 69 63 68 0a 2a 2a 20 20 20 20 20 ts which.**
13b40 20 20 20 20 20 61 72 65 20 61 20 63 6f 70 79 20 are a copy
13b50 6f 66 20 74 68 65 20 70 6f 69 6e 74 65 72 20 73 of the pointer s
13b60 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 33 upplied by the 3
13b70 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a rd parameter to.
13b80 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
13b90 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 ite3_busy_handle
13ba0 72 28 29 5d 20 61 6e 64 20 61 20 63 6f 75 6e 74 r()] and a count
13bb0 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f of the number o
13bc0 66 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 f prior.**
13bd0 20 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 invocations
13be0 6f 66 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 of the busy hand
13bf0 6c 65 72 20 66 6f 72 20 74 68 65 20 73 61 6d 65 ler for the same
13c00 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 0a locking event..
13c10 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e **.** ASSUMPTION
13c20 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 33 31 39 S:.**.** {A12319
13c30 7d 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 } A busy handler
13c40 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 must not close
13c50 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
13c60 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 nection.**
13c70 20 20 20 20 6f 72 20 5b 70 72 65 70 61 72 65 64 or [prepared
13c80 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 statement] that
13c90 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 invoked the bus
13ca0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e y handler..*/.in
13cb0 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 t sqlite3_busy_h
13cc0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c andler(sqlite3*,
13cd0 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e int(*)(void*,in
13ce0 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a t), void*);../*.
13cf0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 ** CAPI3REF: Set
13d00 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 20 A Busy Timeout
13d10 7b 48 31 32 33 34 30 7d 20 3c 53 34 30 34 31 30 {H12340} <S40410
13d20 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 >.**.** This rou
13d30 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c tine sets a [sql
13d40 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 ite3_busy_handle
13d50 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 r | busy handler
13d60 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a ] that sleeps.**
13d70 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 for a specified
13d80 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 amount of time
13d90 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 when a table is
13da0 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 68 61 6e locked. The han
13db0 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 dler.** will sle
13dc0 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 ep multiple time
13dd0 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 s until at least
13de0 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e "ms" millisecon
13df0 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a ds of sleeping.*
13e00 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 * have accumulat
13e10 65 64 2e 20 7b 48 31 32 33 34 33 7d 20 41 66 74 ed. {H12343} Aft
13e20 65 72 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 er "ms" millisec
13e30 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 onds of sleeping
13e40 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 ,.** the handler
13e50 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 returns 0 which
13e60 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 causes [sqlite3
13e70 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 _step()] to retu
13e80 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 rn.** [SQLITE_BU
13e90 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 SY] or [SQLITE_I
13ea0 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a OERR_BLOCKED]..*
13eb0 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69 *.** Calling thi
13ec0 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 s routine with a
13ed0 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 n argument less
13ee0 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f than or equal to
13ef0 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f zero.** turns o
13f00 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 ff all busy hand
13f10 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 lers..**.** Ther
13f20 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 e can only be a
13f30 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 single busy hand
13f40 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 ler for a partic
13f50 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 ular.** [databas
13f60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e e connection] an
13f70 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 y any given mome
13f80 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 nt. If another
13f90 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 busy handler.**
13fa0 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 was defined (us
13fb0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 ing [sqlite3_bus
13fc0 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 y_handler()]) pr
13fd0 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a ior to calling.*
13fe0 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 * this routine,
13ff0 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 that other busy
14000 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 handler is clear
14010 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 ed..**.** INVARI
14020 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 ANTS:.**.** {H12
14030 33 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 341} The [sqlite
14040 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 3_busy_timeout()
14050 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c ] function shall
14060 20 6f 76 65 72 72 69 64 65 20 61 6e 79 20 70 72 override any pr
14070 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ior.**
14080 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 [sqlite3_busy_ti
14090 6d 65 6f 75 74 28 29 5d 20 6f 72 20 5b 73 71 6c meout()] or [sql
140a0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 ite3_busy_handle
140b0 72 28 29 5d 20 73 65 74 74 69 6e 67 0a 2a 2a 20 r()] setting.**
140c0 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20 on the
140d0 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 same [database c
140e0 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a onnection]..**.*
140f0 2a 20 7b 48 31 32 33 34 33 7d 20 49 66 20 74 68 * {H12343} If th
14100 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 e 2nd parameter
14110 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 to [sqlite3_busy
14120 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 20 6c _timeout()] is l
14130 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 ess than.**
14140 20 20 20 20 20 6f 72 20 65 71 75 61 6c 20 74 6f or equal to
14150 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 zero, then the
14160 62 75 73 79 20 68 61 6e 64 6c 65 72 20 73 68 61 busy handler sha
14170 6c 6c 20 62 65 20 63 6c 65 61 72 65 64 20 73 6f ll be cleared so
14180 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 that.**
14190 20 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 all subsequent
141a0 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 73 20 locking events
141b0 69 6d 6d 65 64 69 61 74 65 6c 79 20 72 65 74 75 immediately retu
141c0 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d rn [SQLITE_BUSY]
141d0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34 34 7d ..**.** {H12344}
141e0 20 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 If the 2nd para
141f0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 meter to [sqlite
14200 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 3_busy_timeout()
14210 5d 20 69 73 20 61 20 70 6f 73 69 74 69 76 65 0a ] is a positive.
14220 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 ** numb
14230 65 72 20 4e 2c 20 74 68 65 6e 20 61 20 62 75 73 er N, then a bus
14240 79 20 68 61 6e 64 6c 65 72 20 73 68 61 6c 6c 20 y handler shall
14250 62 65 20 73 65 74 20 74 68 61 74 20 72 65 70 65 be set that repe
14260 61 74 65 64 6c 79 20 63 61 6c 6c 73 0a 2a 2a 20 atedly calls.**
14270 20 20 20 20 20 20 20 20 20 74 68 65 20 78 53 6c the xSl
14280 65 65 70 28 29 20 6d 65 74 68 6f 64 20 69 6e 20 eep() method in
14290 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 the [sqlite3_vfs
142a0 20 7c 20 56 46 53 20 69 6e 74 65 72 66 61 63 65 | VFS interface
142b0 5d 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 20 20 20 ] until.**
142c0 20 20 20 20 65 69 74 68 65 72 20 74 68 65 20 6c either the l
142d0 6f 63 6b 20 63 6c 65 61 72 73 20 6f 72 20 75 6e ock clears or un
142e0 74 69 6c 20 74 68 65 20 63 75 6d 75 6c 61 74 69 til the cumulati
142f0 76 65 20 73 6c 65 65 70 20 74 69 6d 65 0a 2a 2a ve sleep time.**
14300 20 20 20 20 20 20 20 20 20 20 72 65 70 6f 72 74 report
14310 65 64 20 62 61 63 6b 20 62 79 20 78 53 6c 65 65 ed back by xSlee
14320 70 28 29 20 65 78 63 65 65 64 73 20 4e 20 6d 69 p() exceeds N mi
14330 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2f 0a 69 lliseconds..*/.i
14340 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f nt sqlite3_busy_
14350 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a timeout(sqlite3*
14360 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a , int ms);../*.*
14370 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 * CAPI3REF: Conv
14380 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 enience Routines
14390 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 For Running Que
143a0 72 69 65 73 20 7b 48 31 32 33 37 30 7d 20 3c 53 ries {H12370} <S
143b0 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 44 65 66 10000>.**.** Def
143c0 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 inition: A <b>re
143d0 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 sult table</b> i
143e0 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 s memory data st
143f0 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 ructure created
14400 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 by the.** [sqlit
14410 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 e3_get_table()]
14420 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 interface. A re
14430 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 sult table recor
14440 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 ds the.** comple
14450 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 te query results
14460 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 from one or mor
14470 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a e queries..**.**
14480 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 The table conce
14490 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 ptually has a nu
144a0 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 mber of rows and
144b0 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a columns. But.*
144c0 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 * these numbers
144d0 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 are not part of
144e0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 the result table
144f0 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a itself. These.
14500 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f ** numbers are o
14510 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 btained separate
14520 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 ly. Let N be th
14530 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 e number of rows
14540 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 .** and M be the
14550 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
14560 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 ns..**.** A resu
14570 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 lt table is an a
14580 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 rray of pointers
14590 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 to zero-termina
145a0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 ted UTF-8 string
145b0 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 s..** There are
145c0 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 (N+1)*M elements
145d0 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 in the array.
145e0 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e The first M poin
145f0 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f ters point.** to
14600 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
14610 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 strings that c
14620 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 ontain the names
14630 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e of the columns.
14640 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e .** The remainin
14650 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f g entries all po
14660 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 int to query res
14670 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 ults. NULL valu
14680 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 es result.** in
14690 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 NULL pointers.
146a0 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 All other values
146b0 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 are in their UT
146c0 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 F-8 zero-termina
146d0 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 ted.** string re
146e0 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 presentation as
146f0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c returned by [sql
14700 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
14710 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 ()]..**.** A res
14720 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 ult table might
14730 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f consist of one o
14740 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c r more memory al
14750 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 locations..** It
14760 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 is not safe to
14770 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 pass a result ta
14780 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 ble directly to
14790 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
147a0 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 ..** A result ta
147b0 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 ble should be de
147c0 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 allocated using
147d0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 [sqlite3_free_ta
147e0 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 ble()]..**.** As
147f0 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 an example of t
14800 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 he result table
14810 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 format, suppose
14820 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a a query result.*
14830 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a * is as follows:
14840 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
14850 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 te><pre>.**
14860 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c Name |
14870 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d Age.** -
14880 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
14890 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 ------.**
148a0 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 Alice | 4
148b0 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 3.** Bob
148c0 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 | 28.**
148d0 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 Cindy
148e0 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 | 21.** </pre
148f0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
14900 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 *.** There are t
14910 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 wo column (M==2)
14920 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 and three rows
14930 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 (N==3). Thus th
14940 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c e.** result tabl
14950 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e e has 8 entries.
14960 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 Suppose the re
14970 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 sult table is st
14980 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 ored.** in an ar
14990 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 ray names azResu
149a0 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 lt. Then azResu
149b0 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f lt holds this co
149c0 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c ntent:.**.** <bl
149d0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
149e0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
149f0 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 t[0] = "Name
14a00 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
14a10 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 esult[1] = "
14a20 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 Age";.**
14a30 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 azResult[2]
14a40 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 = "Alice";.**
14a50 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
14a60 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 1;3] = "43";.**
14a70 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
14a80 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a #91;4] = "Bob";.
14a90 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
14aa0 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 lt[5] = "28"
14ab0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
14ac0 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 sult[6] = "C
14ad0 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 indy";.**
14ae0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d azResult[7]
14af0 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 = "21";.** </pr
14b00 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a e></blockquote>.
14b10 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
14b20 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 3_get_table() fu
14b30 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 nction evaluates
14b40 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 one or more.**
14b50 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 semicolon-separa
14b60 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ted SQL statemen
14b70 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 ts in the zero-t
14b80 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a erminated UTF-8.
14b90 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 ** string of its
14ba0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 2nd parameter.
14bb0 20 49 74 20 72 65 74 75 72 6e 73 20 61 20 72 65 It returns a re
14bc0 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 sult table to th
14bd0 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 e.** pointer giv
14be0 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 en in its 3rd pa
14bf0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 rameter..**.** A
14c00 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69 6e 67 fter the calling
14c10 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20 66 69 function has fi
14c20 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 65 nished using the
14c30 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68 6f 75 result, it shou
14c40 6c 64 0a 2a 2a 20 70 61 73 73 20 74 68 65 20 70 ld.** pass the p
14c50 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 72 65 ointer to the re
14c60 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 73 71 sult table to sq
14c70 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 lite3_free_table
14c80 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a () in order to.*
14c90 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 * release the me
14ca0 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 mory that was ma
14cb0 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 lloced. Because
14cc0 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a of the way the.
14cd0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c ** [sqlite3_mall
14ce0 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 oc()] happens wi
14cf0 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 thin sqlite3_get
14d00 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 _table(), the ca
14d10 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f lling.** functio
14d20 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 n must not try t
14d30 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f o call [sqlite3_
14d40 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 free()] directly
14d50 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 . Only.** [sqli
14d60 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 te3_free_table()
14d70 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c ] is able to rel
14d80 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 ease the memory
14d90 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 properly and saf
14da0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ely..**.** The s
14db0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
14dc0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
14dd0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 implemented as a
14de0 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a wrapper around.
14df0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 ** [sqlite3_exec
14e00 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 ()]. The sqlite
14e10 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 3_get_table() ro
14e20 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 utine does not h
14e30 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f ave access.** to
14e40 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 any internal da
14e50 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 ta structures of
14e60 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 SQLite. It use
14e70 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 s only the publi
14e80 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 c.** interface d
14e90 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 efined here. As
14ea0 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 a consequence,
14eb0 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 errors that occu
14ec0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 r in the.** wrap
14ed0 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 per layer outsid
14ee0 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 e of the interna
14ef0 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 l [sqlite3_exec(
14f00 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a )] call are not.
14f10 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 ** reflected in
14f20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 subsequent calls
14f30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 to [sqlite3_err
14f40 63 6f 64 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 code()] or [sqli
14f50 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a te3_errmsg()]..*
14f60 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
14f70 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 31 7d 20 .**.** {H12371}
14f80 49 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 67 65 If a [sqlite3_ge
14f90 74 5f 74 61 62 6c 65 28 29 5d 20 66 61 69 6c 73 t_table()] fails
14fa0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
14fb0 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 tion, then.**
14fc0 20 20 20 20 20 20 20 69 74 20 73 68 61 6c 6c 20 it shall
14fd0 66 72 65 65 20 74 68 65 20 72 65 73 75 6c 74 20 free the result
14fe0 74 61 62 6c 65 20 75 6e 64 65 72 20 63 6f 6e 73 table under cons
14ff0 74 72 75 63 74 69 6f 6e 2c 20 61 62 6f 72 74 20 truction, abort
15000 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
15010 71 75 65 72 79 20 69 6e 20 70 72 6f 63 65 73 73 query in process
15020 2c 20 73 6b 69 70 20 61 6e 79 20 73 75 62 73 65 , skip any subse
15030 71 75 65 6e 74 20 71 75 65 72 69 65 73 2c 20 73 quent queries, s
15040 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 et the.**
15050 20 20 20 2a 70 61 7a 52 65 73 75 6c 74 20 6f 75 *pazResult ou
15060 74 70 75 74 20 70 6f 69 6e 74 65 72 20 74 6f 20 tput pointer to
15070 4e 55 4c 4c 20 61 6e 64 20 72 65 74 75 72 6e 20 NULL and return
15080 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a [SQLITE_NOMEM]..
15090 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 33 7d 20 49 **.** {H12373} I
150a0 66 20 74 68 65 20 70 6e 43 6f 6c 75 6d 6e 20 70 f the pnColumn p
150b0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c arameter to [sql
150c0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
150d0 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a ] is not NULL.**
150e0 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 61 then a
150f0 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f successful invo
15100 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 cation of [sqlit
15110 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 e3_get_table()]
15120 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 shall.**
15130 20 20 77 72 69 74 65 20 74 68 65 20 6e 75 6d 62 write the numb
15140 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
15150 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
15160 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 result set of t
15170 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a 70 he query into *p
15180 6e 43 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 7b nColumn..**.** {
15190 48 31 32 33 37 34 7d 20 49 66 20 74 68 65 20 70 H12374} If the p
151a0 6e 52 6f 77 20 70 61 72 61 6d 65 74 65 72 20 74 nRow parameter t
151b0 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 o [sqlite3_get_t
151c0 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e able()] is not N
151d0 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ULL.**
151e0 74 68 65 6e 20 61 20 73 75 63 63 65 73 73 66 75 then a successfu
151f0 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 l invocation of
15200 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 [sqlite3_get_tab
15210 6c 65 28 29 5d 20 73 68 61 6c 6c 0a 2a 2a 20 20 le()] shall.**
15220 20 20 20 20 20 20 20 20 77 72 69 74 65 73 20 74 writes t
15230 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 he number of row
15240 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 s in the.**
15250 20 20 20 20 20 72 65 73 75 6c 74 20 73 65 74 20 result set
15260 6f 66 20 74 68 65 20 71 75 65 72 79 20 69 6e 74 of the query int
15270 6f 20 2a 70 6e 52 6f 77 2e 0a 2a 2a 0a 2a 2a 20 o *pnRow..**.**
15280 7b 48 31 32 33 37 36 7d 20 41 20 73 75 63 63 65 {H12376} A succe
15290 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e ssful invocation
152a0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 of [sqlite3_get
152b0 5f 74 61 62 6c 65 28 29 5d 20 74 68 61 74 20 63 _table()] that c
152c0 6f 6d 70 75 74 65 73 0a 2a 2a 20 20 20 20 20 20 omputes.**
152d0 20 20 20 20 4e 20 72 6f 77 73 20 6f 66 20 72 65 N rows of re
152e0 73 75 6c 74 20 77 69 74 68 20 43 20 63 6f 6c 75 sult with C colu
152f0 6d 6e 73 20 70 65 72 20 72 6f 77 20 73 68 61 6c mns per row shal
15300 6c 20 6d 61 6b 65 20 2a 70 61 7a 52 65 73 75 6c l make *pazResul
15310 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f t.** po
15320 69 6e 74 20 74 6f 20 61 6e 20 61 72 72 61 79 20 int to an array
15330 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 28 of pointers to (
15340 4e 2b 31 29 2a 43 20 73 74 72 69 6e 67 73 20 77 N+1)*C strings w
15350 68 65 72 65 20 74 68 65 20 66 69 72 73 74 0a 2a here the first.*
15360 2a 20 20 20 20 20 20 20 20 20 20 43 20 73 74 72 * C str
15370 69 6e 67 73 20 61 72 65 20 63 6f 6c 75 6d 6e 20 ings are column
15380 6e 61 6d 65 73 20 61 73 20 6f 62 74 61 69 6e 65 names as obtaine
15390 64 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 d from.**
153a0 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 [sqlite3_colu
153b0 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 74 mn_name()] and t
153c0 68 65 20 72 65 73 74 20 61 72 65 20 63 6f 6c 75 he rest are colu
153d0 6d 6e 20 72 65 73 75 6c 74 20 76 61 6c 75 65 73 mn result values
153e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 74 .** obt
153f0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 ained from [sqli
15400 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
15410 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 )]..**.** {H1237
15420 39 7d 20 54 68 65 20 76 61 6c 75 65 73 20 69 6e 9} The values in
15430 20 74 68 65 20 70 61 7a 52 65 73 75 6c 74 20 61 the pazResult a
15440 72 72 61 79 20 72 65 74 75 72 6e 65 64 20 62 79 rray returned by
15450 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 [sqlite3_get_ta
15460 62 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 ble()].**
15470 20 20 20 73 68 61 6c 6c 20 72 65 6d 61 69 6e 20 shall remain
15480 76 61 6c 69 64 20 75 6e 74 69 6c 20 63 6c 65 61 valid until clea
15490 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f red by [sqlite3_
154a0 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a free_table()]..*
154b0 2a 0a 2a 2a 20 7b 48 31 32 33 38 32 7d 20 57 68 *.** {H12382} Wh
154c0 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 en an error occu
154d0 72 73 20 64 75 72 69 6e 67 20 65 76 61 6c 75 61 rs during evalua
154e0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 tion of [sqlite3
154f0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 0a 2a 2a _get_table()].**
15500 20 20 20 20 20 20 20 20 20 20 74 68 65 20 66 75 the fu
15510 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 73 65 74 nction shall set
15520 20 2a 70 61 7a 52 65 73 75 6c 74 20 74 6f 20 4e *pazResult to N
15530 55 4c 4c 2c 20 77 72 69 74 65 20 61 6e 20 65 72 ULL, write an er
15540 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 ror message.**
15550 20 20 20 20 20 20 20 20 69 6e 74 6f 20 6d 65 6d into mem
15560 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f ory obtained fro
15570 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f m [sqlite3_mallo
15580 63 28 29 5d 2c 20 6d 61 6b 65 0a 2a 2a 20 20 20 c()], make.**
15590 20 20 20 20 20 20 20 2a 2a 70 7a 45 72 72 6d 73 **pzErrms
155a0 67 20 70 6f 69 6e 74 20 74 6f 20 74 68 61 74 20 g point to that
155b0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2c 20 61 error message, a
155c0 6e 64 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 20 nd return a.**
155d0 20 20 20 20 20 20 20 20 61 70 70 72 6f 70 72 69 appropri
155e0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d ate [error code]
155f0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
15600 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 _get_table(. sq
15610 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
15620 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 /* An open d
15630 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e atabase */. con
15640 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 st char *zSql,
15650 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 /* SQL to be
15660 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 evaluated */. c
15670 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 har ***pazResult
15680 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 , /* Results
15690 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a of the query */.
156a0 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 int *pnRow,
156b0 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 /* Numbe
156c0 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 r of result rows
156d0 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f written here */
156e0 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e . int *pnColumn
156f0 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 , /* Numb
15700 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c er of result col
15710 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 umns written her
15720 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a e */. char **pz
15730 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 Errmsg /*
15740 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 Error msg writte
15750 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 n here */.);.voi
15760 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 d sqlite3_free_t
15770 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 able(char **resu
15780 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 lt);../*.** CAPI
15790 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 3REF: Formatted
157a0 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 String Printing
157b0 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 37 34 30 Functions {H1740
157c0 30 7d 20 3c 53 37 30 30 30 30 3e 3c 53 32 30 30 0} <S70000><S200
157d0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 00>.**.** These
157e0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 routines are wor
157f0 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 kalikes of the "
15800 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 printf()" family
15810 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a of functions.**
15820 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 from the standa
15830 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a rd C library..**
15840 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
15850 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 mprintf() and sq
15860 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 lite3_vmprintf()
15870 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 routines write
15880 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 their.** results
15890 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 into memory obt
158a0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 ained from [sqli
158b0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a te3_malloc()]..*
158c0 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 * The strings re
158d0 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 turned by these
158e0 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f two routines sho
158f0 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 uld be.** releas
15900 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 ed by [sqlite3_f
15910 72 65 65 28 29 5d 2e 20 20 42 6f 74 68 20 72 6f ree()]. Both ro
15920 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a utines return a.
15930 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 ** NULL pointer
15940 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c if [sqlite3_mall
15950 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 oc()] is unable
15960 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 to allocate enou
15970 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 gh.** memory to
15980 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 hold the resulti
15990 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a ng string..**.**
159a0 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 In sqlite3_snpr
159b0 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 intf() routine i
159c0 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e s similar to "sn
159d0 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a printf()" from.*
159e0 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 * the standard C
159f0 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 library. The r
15a00 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e esult is written
15a10 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 into the.** buf
15a20 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 fer supplied as
15a30 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
15a40 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 eter whose size
15a50 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 is given by.** t
15a60 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
15a70 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 er. Note that th
15a80 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a e order of the.*
15a90 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 * first two para
15aa0 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73 meters is revers
15ab0 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 ed from snprintf
15ac0 28 29 2e 20 20 54 68 69 73 20 69 73 20 61 6e 0a (). This is an.
15ad0 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 ** historical ac
15ae0 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e cident that cann
15af0 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 ot be fixed with
15b00 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 out breaking.**
15b10 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 backwards compat
15b20 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61 ibility. Note a
15b30 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 lso that sqlite3
15b40 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 _snprintf().** r
15b50 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
15b60 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 to its buffer i
15b70 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 nstead of the nu
15b80 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 mber of.** chara
15b90 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 cters actually w
15ba0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 ritten into the
15bb0 62 75 66 66 65 72 2e 20 20 57 65 20 61 64 6d 69 buffer. We admi
15bc0 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 t that.** the nu
15bd0 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 mber of characte
15be0 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 rs written would
15bf0 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 be a more usefu
15c00 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 l return.** valu
15c10 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 e but we cannot
15c20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 change the imple
15c30 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c mentation of sql
15c40 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a ite3_snprintf().
15c50 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 ** now without b
15c60 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 reaking compatib
15c70 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 ility..**.** As
15c80 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 long as the buff
15c90 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 er size is great
15ca0 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 er than zero, sq
15cb0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
15cc0 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 .** guarantees t
15cd0 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 hat the buffer i
15ce0 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 s always zero-te
15cf0 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20 66 rminated. The f
15d00 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 irst.** paramete
15d10 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 r "n" is the tot
15d20 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 al size of the b
15d30 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 uffer, including
15d40 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 space for.** th
15d50 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f e zero terminato
15d60 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 r. So the longe
15d70 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 st string that c
15d80 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 an be completely
15d90 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c .** written will
15da0 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 be n-1 characte
15db0 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 rs..**.** These
15dc0 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 routines all imp
15dd0 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 lement some addi
15de0 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e tional formattin
15df0 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 g.** options tha
15e00 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 t are useful for
15e10 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 constructing SQ
15e20 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a L statements..**
15e30 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 All of the usua
15e40 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 l printf() forma
15e50 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 tting options ap
15e60 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f ply. In additio
15e70 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 n, there.** is a
15e80 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 re "%q", "%Q", a
15e90 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e nd "%z" options.
15ea0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70 .**.** The %q op
15eb0 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 tion works like
15ec0 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 %s in that it su
15ed0 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c bstitutes a null
15ee0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 -terminated.** s
15ef0 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 tring from the a
15f00 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 rgument list. B
15f10 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c ut %q also doubl
15f20 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 es every '\'' ch
15f30 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 aracter..** %q i
15f40 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 s designed for u
15f50 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 se inside a stri
15f60 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 79 20 ng literal. By
15f70 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c doubling each '\
15f80 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 ''.** character
15f90 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 it escapes that
15fa0 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c character and al
15fb0 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e lows it to be in
15fc0 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 serted into.** t
15fd0 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a he string..**.**
15fe0 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 For example, as
15ff0 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 sume the string
16000 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 variable zText c
16010 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 ontains text as
16020 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c follows:.**.** <
16030 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
16040 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 .** char *zText
16050 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 = "It's a happy
16060 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 day!";.** </pre
16070 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
16080 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 *.** One can use
16090 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e this text in an
160a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 SQL statement a
160b0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a s follows:.**.**
160c0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
160d0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 e>.** char *zSQ
160e0 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 L = sqlite3_mpri
160f0 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f ntf("INSERT INTO
16100 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 table VALUES('%
16110 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a q')", zText);.**
16120 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 sqlite3_exec(d
16130 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 b, zSQL, 0, 0, 0
16140 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 );.** sqlite3_f
16150 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f ree(zSQL);.** </
16160 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
16170 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 >.**.** Because
16180 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 the %q format st
16190 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 ring is used, th
161a0 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 e '\'' character
161b0 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 in zText.** is
161c0 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 escaped and the
161d0 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 SQL generated is
161e0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a as follows:.**.
161f0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
16200 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 pre>.** INSERT
16210 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 INTO table1 VALU
16220 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 ES('It''s a happ
16230 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 y day!').** </pr
16240 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a e></blockquote>.
16250 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f **.** This is co
16260 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 rrect. Had we u
16270 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f sed %s instead o
16280 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 f %q, the genera
16290 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 ted SQL.** would
162a0 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b have looked lik
162b0 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 e this:.**.** <b
162c0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
162d0 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 ** INSERT INTO
162e0 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 table1 VALUES('I
162f0 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 t's a happy day!
16300 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 ');.** </pre></b
16310 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
16320 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 This second exa
16330 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 mple is an SQL s
16340 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 yntax error. As
16350 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 a general rule
16360 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c you should.** al
16370 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 ways use %q inst
16380 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 ead of %s when i
16390 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e nserting text in
163a0 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 to a string lite
163b0 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 ral..**.** The %
163c0 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c Q option works l
163d0 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74 ike %q except it
163e0 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c also adds singl
163f0 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a e quotes around.
16400 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f ** the outside o
16410 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 f the total stri
16420 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c ng. Additionall
16430 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 y, if the parame
16440 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 ter in the.** ar
16450 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 gument list is a
16460 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 NULL pointer, %
16470 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68 Q substitutes th
16480 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 e text "NULL" (w
16490 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 ithout.** single
164a0 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c 61 63 quotes) in plac
164b0 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70 74 69 e of the %Q opti
164c0 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 on. So, for exa
164d0 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 mple, one could
164e0 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 say:.**.** <bloc
164f0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 kquote><pre>.**
16500 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 char *zSQL = sq
16510 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 lite3_mprintf("I
16520 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 NSERT INTO table
16530 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 VALUES(%Q)", zT
16540 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 ext);.** sqlite
16550 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 3_exec(db, zSQL,
16560 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 0, 0, 0);.** s
16570 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c qlite3_free(zSQL
16580 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c );.** </pre></bl
16590 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
165a0 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 The code above w
165b0 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 ill render a cor
165c0 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 rect SQL stateme
165d0 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a nt in the zSQL.*
165e0 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 * variable even
165f0 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 if the zText var
16600 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 iable is a NULL
16610 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 pointer..**.** T
16620 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 he "%z" formatti
16630 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 ng option works
16640 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 73 exactly like "%s
16650 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 " with the.** ad
16660 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 dition that afte
16670 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 r the string has
16680 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 been read and c
16690 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 opied into.** th
166a0 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 e result, [sqlit
166b0 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 e3_free()] is ca
166c0 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 lled on the inpu
166d0 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a t string. {END}.
166e0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
166f0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 33 7d :.**.** {H17403}
16700 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d The [sqlite3_m
16710 70 72 69 6e 74 66 28 29 5d 20 61 6e 64 20 5b 73 printf()] and [s
16720 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 qlite3_vmprintf(
16730 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a )] interfaces.**
16740 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 retur
16750 6e 20 65 69 74 68 65 72 20 70 6f 69 6e 74 65 72 n either pointer
16760 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e s to zero-termin
16770 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e ated UTF-8 strin
16780 67 73 20 68 65 6c 64 20 69 6e 0a 2a 2a 20 20 20 gs held in.**
16790 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 6f memory o
167a0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
167b0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
167c0 6f 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 or NULL pointers
167d0 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 if.**
167e0 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 a call to [sqli
167f0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 61 te3_malloc()] fa
16800 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 ils..**.** {H174
16810 30 36 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 06} The [sqlite
16820 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 3_snprintf()] in
16830 74 65 72 66 61 63 65 20 77 72 69 74 65 73 20 61 terface writes a
16840 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
16850 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 55 54 .** UT
16860 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 74 6f 20 F-8 string into
16870 74 68 65 20 62 75 66 66 65 72 20 70 6f 69 6e 74 the buffer point
16880 65 64 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 ed to by the sec
16890 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a ond parameter.**
168a0 20 20 20 20 20 20 20 20 20 20 20 70 72 6f 76 69 provi
168b0 64 65 64 20 74 68 61 74 20 74 68 65 20 66 69 72 ded that the fir
168c0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 st parameter is
168d0 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 greater than zer
168e0 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 37 o..**.** {H17407
168f0 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f } The [sqlite3_
16900 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 snprintf()] inte
16910 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 77 rface does not w
16920 72 69 74 65 20 73 6c 6f 74 73 20 6f 66 0a 2a 2a rite slots of.**
16930 20 20 20 20 20 20 20 20 20 20 20 69 74 73 20 6f its o
16940 75 74 70 75 74 20 62 75 66 66 65 72 20 28 74 68 utput buffer (th
16950 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
16960 65 72 29 20 6f 75 74 73 69 64 65 20 74 68 65 20 er) outside the
16970 72 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 range.**
16980 20 20 20 6f 66 20 30 20 74 68 72 6f 75 67 68 20 of 0 through
16990 4e 2d 31 20 28 77 68 65 72 65 20 4e 20 69 73 20 N-1 (where N is
169a0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 the first parame
169b0 74 65 72 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 ter).**
169c0 20 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 regardless of
169d0 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 the length of th
169e0 65 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 e string.**
169f0 20 20 20 20 20 20 72 65 71 75 65 73 74 65 64 20 requested
16a00 62 79 20 74 68 65 20 66 6f 72 6d 61 74 20 73 70 by the format sp
16a10 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2f 0a ecification..*/.
16a20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 char *sqlite3_mp
16a30 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 rintf(const char
16a40 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 *,...);.char *sq
16a50 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 lite3_vmprintf(c
16a60 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c onst char*, va_l
16a70 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 ist);.char *sqli
16a80 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 te3_snprintf(int
16a90 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 ,char*,const cha
16aa0 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a r*, ...);../*.**
16ab0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 CAPI3REF: Memor
16ac0 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 y Allocation Sub
16ad0 73 79 73 74 65 6d 20 7b 48 31 37 33 30 30 7d 20 system {H17300}
16ae0 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S20000>.**.** T
16af0 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 20 he SQLite core
16b00 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 uses these three
16b10 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c routines for al
16b20 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 l of its own.**
16b30 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 internal memory
16b40 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 allocation needs
16b50 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 . "Core" in the
16b60 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 previous sentenc
16b70 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e e.** does not in
16b80 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d clude operating-
16b90 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 system specific
16ba0 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 VFS implementati
16bb0 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 on. The.** Wind
16bc0 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 ows VFS uses nat
16bd0 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 ive malloc() and
16be0 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 free() for some
16bf0 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a operations..**.
16c00 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d ** The sqlite3_m
16c10 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 alloc() routine
16c20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
16c30 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 r to a block.**
16c40 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 of memory at lea
16c50 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 st N bytes in le
16c60 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 ngth, where N is
16c70 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a the parameter..
16c80 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 ** If sqlite3_ma
16c90 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 lloc() is unable
16ca0 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 to obtain suffi
16cb0 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 cient free.** me
16cc0 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 mory, it returns
16cd0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
16ce0 20 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 If the paramet
16cf0 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 er N to.** sqlit
16d00 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a e3_malloc() is z
16d10 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 ero or negative
16d20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c then sqlite3_mal
16d30 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a loc() returns.**
16d40 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
16d50 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 73 .**.** Calling s
16d60 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 qlite3_free() wi
16d70 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 th a pointer pre
16d80 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 viously returned
16d90 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d .** by sqlite3_m
16da0 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 alloc() or sqlit
16db0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c e3_realloc() rel
16dc0 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 eases that memor
16dd0 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 y so.** that it
16de0 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e might be reused.
16df0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 The sqlite3_fr
16e00 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a ee() routine is.
16e10 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 ** a no-op if is
16e20 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e called with a N
16e30 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 ULL pointer. Pa
16e40 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 ssing a NULL poi
16e50 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 nter.** to sqlit
16e60 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 e3_free() is har
16e70 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 mless. After be
16e80 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 ing freed, memor
16e90 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 y.** should neit
16ea0 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 her be read nor
16eb0 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 written. Even r
16ec0 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c eading previousl
16ed0 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 y freed.** memor
16ee0 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 y might result i
16ef0 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e n a segmentation
16f00 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 fault or other
16f10 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a severe error..**
16f20 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 Memory corrupti
16f30 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 on, a segmentati
16f40 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 on fault, or oth
16f50 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a er severe error.
16f60 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 ** might result
16f70 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 if sqlite3_free(
16f80 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 ) is called with
16f90 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e a non-NULL poin
16fa0 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 ter that.** was
16fb0 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f not obtained fro
16fc0 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 m sqlite3_malloc
16fd0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 () or sqlite3_re
16fe0 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 alloc()..**.** T
16ff0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c he sqlite3_reall
17000 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 oc() interface a
17010 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a ttempts to resiz
17020 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d e a.** prior mem
17030 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 ory allocation t
17040 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 o be at least N
17050 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 bytes, where N i
17060 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 s the.** second
17070 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 parameter. The
17080 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
17090 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 n to be resized
170a0 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 is the first.**
170b0 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66 20 74 parameter. If t
170c0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
170d0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 er to sqlite3_re
170e0 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 alloc().** is a
170f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 NULL pointer the
17100 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 n its behavior i
17110 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 s identical to c
17120 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 alling.** sqlite
17130 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 3_malloc(N) wher
17140 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e e N is the secon
17150 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 d parameter to s
17160 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
17170 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73 65 63 6f ..** If the seco
17180 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 nd parameter to
17190 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
171a0 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 ) is zero or.**
171b0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 negative then th
171c0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 e behavior is ex
171d0 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 actly the same a
171e0 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c s calling.** sql
171f0 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 ite3_free(P) whe
17200 72 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73 re P is the firs
17210 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 t parameter to s
17220 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
17230 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 ..** sqlite3_rea
17240 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 lloc() returns a
17250 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 pointer to a me
17260 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a mory allocation.
17270 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e ** of at least N
17280 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f bytes in size o
17290 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 r NULL if suffic
172a0 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 ient memory is u
172b0 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 49 navailable..** I
172c0 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 f M is the size
172d0 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c of the prior all
172e0 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 ocation, then mi
172f0 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 n(N,M) bytes.**
17300 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c of the prior all
17310 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 ocation are copi
17320 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 ed into the begi
17330 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 nning of buffer
17340 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 returned.** by s
17350 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
17360 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 and the prior a
17370 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 llocation is fre
17380 65 64 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 ed..** If sqlite
17390 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 3_realloc() retu
173a0 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 rns NULL, then t
173b0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 he prior allocat
173c0 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 ion.** is not fr
173d0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d eed..**.** The m
173e0 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 emory returned b
173f0 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 y sqlite3_malloc
17400 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 () and sqlite3_r
17410 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 ealloc().** is a
17420 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f lways aligned to
17430 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 at least an 8 b
17440 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 7b 45 yte boundary. {E
17450 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 ND}.**.** The de
17460 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61 fault implementa
17470 74 69 6f 6e 20 6f 66 20 74 68 65 20 6d 65 6d 6f tion of the memo
17480 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 ry allocation su
17490 62 73 79 73 74 65 6d 20 75 73 65 73 0a 2a 2a 20 bsystem uses.**
174a0 74 68 65 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 the malloc(), re
174b0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 alloc() and free
174c0 28 29 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 () provided by t
174d0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 he standard C li
174e0 62 72 61 72 79 2e 0a 2a 2a 20 7b 48 31 37 33 38 brary..** {H1738
174f0 32 7d 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53 2} However, if S
17500 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
17510 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 d with the.** SQ
17520 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45 LITE_MEMORY_SIZE
17530 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 43 20 70 72 =<i>NNN</i> C pr
17540 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f eprocessor macro
17550 20 28 77 68 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f (where <i>NNN</
17560 69 3e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 i>.** is an inte
17570 67 65 72 29 2c 20 74 68 65 6e 20 53 51 4c 69 74 ger), then SQLit
17580 65 20 63 72 65 61 74 65 20 61 20 73 74 61 74 69 e create a stati
17590 63 20 61 72 72 61 79 20 6f 66 20 61 74 20 6c 65 c array of at le
175a0 61 73 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e 3c 2f 69 ast.** <i>NNN</i
175b0 3e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 > bytes in size
175c0 61 6e 64 20 75 73 65 73 20 74 68 61 74 20 61 72 and uses that ar
175d0 72 61 79 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 ray for all of i
175e0 74 73 20 64 79 6e 61 6d 69 63 0a 2a 2a 20 6d 65 ts dynamic.** me
175f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
17600 6e 65 65 64 73 2e 20 7b 45 4e 44 7d 20 20 41 64 needs. {END} Ad
17610 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 ditional memory
17620 61 6c 6c 6f 63 61 74 6f 72 20 6f 70 74 69 6f 6e allocator option
17630 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61 64 64 65 s.** may be adde
17640 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
17650 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 ases..**.** In S
17660 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e QLite version 3.
17670 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 5.0 and 3.5.1, i
17680 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 t was possible t
17690 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 o define.** the
176a0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f SQLITE_OMIT_MEMO
176b0 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 RY_ALLOCATION wh
176c0 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 ich would cause
176d0 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 the built-in.**
176e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
176f0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
17700 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 to be omitted.
17710 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 That capability
17720 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 .** is no longer
17730 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 provided. Only
17740 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 built-in memory
17750 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 allocators can
17760 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 be used..**.** T
17770 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e he Windows OS in
17780 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 terface layer ca
17790 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 lls.** the syste
177a0 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 m malloc() and f
177b0 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 ree() directly w
177c0 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a hen converting.*
177d0 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 * filenames betw
177e0 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e een the UTF-8 en
177f0 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 coding used by S
17800 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 QLite.** and wha
17810 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 tever filename e
17820 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 ncoding is used
17830 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 by the particula
17840 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 r Windows.** ins
17850 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f tallation. Memo
17860 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 ry allocation er
17870 72 6f 72 73 20 61 72 65 20 64 65 74 65 63 74 65 rors are detecte
17880 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 d, but.** they a
17890 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b re reported back
178a0 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 as [SQLITE_CANT
178b0 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c OPEN] or.** [SQL
178c0 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 ITE_IOERR] rathe
178d0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e r than [SQLITE_N
178e0 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 OMEM]..**.** INV
178f0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
17900 48 31 37 33 30 33 7d 20 20 54 68 65 20 5b 73 71 H17303} The [sq
17910 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d lite3_malloc(N)]
17920 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
17930 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f 69 6e ns either a poin
17940 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 ter to.**
17950 20 20 20 20 61 20 6e 65 77 6c 79 20 63 68 65 63 a newly chec
17960 6b 65 64 2d 6f 75 74 20 62 6c 6f 63 6b 20 6f 66 ked-out block of
17970 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 at least N byte
17980 73 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 s of memory.**
17990 20 20 20 20 20 20 20 20 20 74 68 61 74 20 69 73 that is
179a0 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 2c 8-byte aligned,
179b0 20 6f 72 20 69 74 20 72 65 74 75 72 6e 73 20 4e or it returns N
179c0 55 4c 4c 20 69 66 20 69 74 20 69 73 20 75 6e 61 ULL if it is una
179d0 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ble.**
179e0 20 74 6f 20 66 75 6c 66 69 6c 6c 20 74 68 65 20 to fulfill the
179f0 72 65 71 75 65 73 74 2e 0a 2a 2a 0a 2a 2a 20 7b request..**.** {
17a00 48 31 37 33 30 34 7d 20 20 54 68 65 20 5b 73 71 H17304} The [sq
17a10 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d lite3_malloc(N)]
17a20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
17a30 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ns a NULL pointe
17a40 72 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 r if.**
17a50 20 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e N is less than
17a60 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 or equal to zer
17a70 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 35 o..**.** {H17305
17a80 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f } The [sqlite3_
17a90 66 72 65 65 28 50 29 5d 20 69 6e 74 65 72 66 61 free(P)] interfa
17aa0 63 65 20 72 65 6c 65 61 73 65 73 20 6d 65 6d 6f ce releases memo
17ab0 72 79 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a ry previously.**
17ac0 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 retur
17ad0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ned from [sqlite
17ae0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 3_malloc()] or [
17af0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
17b00 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 )],.**
17b10 20 6d 61 6b 69 6e 67 20 69 74 20 61 76 61 69 6c making it avail
17b20 61 62 6c 65 20 66 6f 72 20 72 65 75 73 65 2e 0a able for reuse..
17b30 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 36 7d 20 20 **.** {H17306}
17b40 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 A call to [sqlit
17b50 65 33 5f 66 72 65 65 28 4e 55 4c 4c 29 5d 20 69 e3_free(NULL)] i
17b60 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d s a harmless no-
17b70 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 op..**.** {H1731
17b80 30 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 0} A call to [s
17b90 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 30 qlite3_realloc(0
17ba0 2c 4e 29 5d 20 69 73 20 65 71 75 69 76 61 6c 65 ,N)] is equivale
17bb0 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 nt to a call.**
17bc0 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b 73 71 to [sq
17bd0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d lite3_malloc(N)]
17be0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 32 7d ..**.** {H17312}
17bf0 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c A call to [sql
17c00 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 30 ite3_realloc(P,0
17c10 29 5d 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 )] is equivalent
17c20 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 20 to a call.**
17c30 20 20 20 20 20 20 20 20 74 6f 20 5b 73 71 6c 69 to [sqli
17c40 74 65 33 5f 66 72 65 65 28 50 29 5d 2e 0a 2a 2a te3_free(P)]..**
17c50 0a 2a 2a 20 7b 48 31 37 33 31 35 7d 20 20 54 68 .** {H17315} Th
17c60 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 e SQLite core us
17c70 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c es [sqlite3_mall
17c80 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f oc()], [sqlite3_
17c90 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 realloc()],.**
17ca0 20 20 20 20 20 20 20 20 20 61 6e 64 20 5b 73 71 and [sq
17cb0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 66 6f lite3_free()] fo
17cc0 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6d 65 6d r all of its mem
17cd0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 ory allocation a
17ce0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 nd.**
17cf0 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 deallocation nee
17d00 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 ds..**.** {H1731
17d10 38 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 8} The [sqlite3
17d20 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 69 _realloc(P,N)] i
17d30 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
17d40 20 65 69 74 68 65 72 20 61 20 70 6f 69 6e 74 65 either a pointe
17d50 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 r.** t
17d60 6f 20 61 20 62 6c 6f 63 6b 20 6f 66 20 63 68 65 o a block of che
17d70 63 6b 65 64 2d 6f 75 74 20 6d 65 6d 6f 72 79 20 cked-out memory
17d80 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 of at least N by
17d90 74 65 73 20 69 6e 20 73 69 7a 65 0a 2a 2a 20 20 tes in size.**
17da0 20 20 20 20 20 20 20 20 20 74 68 61 74 20 69 73 that is
17db0 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 2c 8-byte aligned,
17dc0 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 or a NULL point
17dd0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32 er..**.** {H1732
17de0 31 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 1} When [sqlite
17df0 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 3_realloc(P,N)]
17e00 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 returns a non-NU
17e10 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74 20 66 LL pointer, it f
17e20 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 irst.**
17e30 20 20 63 6f 70 69 65 73 20 74 68 65 20 66 69 72 copies the fir
17e40 73 74 20 4b 20 62 79 74 65 73 20 6f 66 20 63 6f st K bytes of co
17e50 6e 74 65 6e 74 20 66 72 6f 6d 20 50 20 69 6e 74 ntent from P int
17e60 6f 20 74 68 65 20 6e 65 77 6c 79 0a 2a 2a 20 20 o the newly.**
17e70 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 allocat
17e80 65 64 20 62 6c 6f 63 6b 2c 20 77 68 65 72 65 20 ed block, where
17e90 4b 20 69 73 20 74 68 65 20 6c 65 73 73 65 72 20 K is the lesser
17ea0 6f 66 20 4e 20 61 6e 64 20 74 68 65 20 73 69 7a of N and the siz
17eb0 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 e of.**
17ec0 20 20 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a the buffer P..
17ed0 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32 32 7d 20 20 **.** {H17322}
17ee0 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 When [sqlite3_re
17ef0 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 alloc(P,N)] retu
17f00 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 rns a non-NULL p
17f10 6f 69 6e 74 65 72 2c 20 69 74 20 66 69 72 73 74 ointer, it first
17f20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 .** re
17f30 6c 65 61 73 65 73 20 74 68 65 20 62 75 66 66 65 leases the buffe
17f40 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 r P..**.** {H173
17f50 32 33 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 23} When [sqlit
17f60 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d e3_realloc(P,N)]
17f70 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 returns NULL, t
17f80 68 65 20 62 75 66 66 65 72 20 50 20 69 73 0a 2a he buffer P is.*
17f90 2a 20 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20 * not
17fa0 6d 6f 64 69 66 69 65 64 20 6f 72 20 72 65 6c 65 modified or rele
17fb0 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 ased..**.** ASSU
17fc0 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b MPTIONS:.**.** {
17fd0 41 31 37 33 35 30 7d 20 20 54 68 65 20 70 6f 69 A17350} The poi
17fe0 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 nter arguments t
17ff0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 o [sqlite3_free(
18000 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
18010 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 20 20 realloc()].**
18020 20 20 20 20 20 20 20 20 6d 75 73 74 20 62 65 20 must be
18030 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 either NULL or e
18040 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 lse pointers obt
18050 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 ained from a pri
18060 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 or.**
18070 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 invocation of [s
18080 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
18090 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 or [sqlite3_rea
180a0 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 lloc()] that hav
180b0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e e.** n
180c0 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 ot yet been rele
180d0 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 37 ased..**.** {A17
180e0 33 35 31 7d 20 20 54 68 65 20 61 70 70 6c 69 63 351} The applic
180f0 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 ation must not r
18100 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 ead or write any
18110 20 70 61 72 74 20 6f 66 0a 2a 2a 20 20 20 20 20 part of.**
18120 20 20 20 20 20 20 61 20 62 6c 6f 63 6b 20 6f 66 a block of
18130 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 memory after it
18140 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 has been releas
18150 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 ed using.**
18160 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 66 [sqlite3_f
18170 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 ree()] or [sqlit
18180 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a e3_realloc()]..*
18190 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f /.void *sqlite3_
181a0 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 malloc(int);.voi
181b0 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c d *sqlite3_reall
181c0 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a oc(void*, int);.
181d0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 void sqlite3_fre
181e0 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a e(void*);../*.**
181f0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 CAPI3REF: Memor
18200 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 y Allocator Stat
18210 69 73 74 69 63 73 20 7b 48 31 37 33 37 30 7d 20 istics {H17370}
18220 3c 53 33 30 32 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 <S30210>.**.** S
18230 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 QLite provides t
18240 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 hese two interfa
18250 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e ces for reportin
18260 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a g on the status.
18270 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ** of the [sqlit
18280 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 e3_malloc()], [s
18290 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 qlite3_free()],
182a0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 and [sqlite3_rea
182b0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 lloc()].** routi
182c0 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 nes, which form
182d0 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d the built-in mem
182e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 ory allocation s
182f0 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 ubsystem..**.**
18300 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
18310 2a 20 7b 48 31 37 33 37 31 7d 20 54 68 65 20 5b * {H17371} The [
18320 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 sqlite3_memory_u
18330 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 sed()] routine r
18340 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
18350 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 20 20 r of bytes.**
18360 20 20 20 20 20 20 20 6f 66 20 6d 65 6d 6f 72 79 of memory
18370 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 currently outst
18380 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 anding (malloced
18390 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e but not freed).
183a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 33 7d 20 .**.** {H17373}
183b0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d The [sqlite3_mem
183c0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d ory_highwater()]
183d0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
183e0 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 the maximum.**
183f0 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f value o
18400 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 f [sqlite3_memor
18410 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 y_used()] since
18420 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d the high-water m
18430 61 72 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ark.**
18440 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 0a was last reset..
18450 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 34 7d 20 54 **.** {H17374} T
18460 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e he values return
18470 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d ed by [sqlite3_m
18480 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e emory_used()] an
18490 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 d.** [s
184a0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
184b0 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 ghwater()] inclu
184c0 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a de any overhead.
184d0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 64 64 65 ** adde
184e0 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 d by SQLite in i
184f0 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ts implementatio
18500 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 n of [sqlite3_ma
18510 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 lloc()],.**
18520 20 20 20 20 20 62 75 74 20 6e 6f 74 20 6f 76 65 but not ove
18530 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74 rhead added by t
18540 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e he any underlyin
18550 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 g system library
18560 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75 .** rou
18570 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 tines that [sqli
18580 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 te3_malloc()] ma
18590 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 y call..**.** {H
185a0 31 37 33 37 35 7d 20 54 68 65 20 6d 65 6d 6f 72 17375} The memor
185b0 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 y high-water mar
185c0 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 k is reset to th
185d0 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 e current value
185e0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b of.** [
185f0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 sqlite3_memory_u
18600 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e sed()] if and on
18610 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 ly if the parame
18620 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 ter to.**
18630 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f [sqlite3_memo
18640 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 ry_highwater()]
18650 69 73 20 74 72 75 65 2e 20 20 54 68 65 20 76 61 is true. The va
18660 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 lue returned.**
18670 20 20 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c by [sql
18680 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 ite3_memory_high
18690 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 water(1)] is the
186a0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b high-water mark
186b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 69 .** pri
186c0 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e or to the reset.
186d0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 .*/.sqlite3_int6
186e0 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 4 sqlite3_memory
186f0 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c _used(void);.sql
18700 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 ite3_int64 sqlit
18710 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
18720 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 ter(int resetFla
18730 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 g);../*.** CAPI3
18740 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 REF: Pseudo-Rand
18750 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 om Number Genera
18760 74 6f 72 20 7b 48 31 37 33 39 30 7d 20 3c 53 32 tor {H17390} <S2
18770 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 0000>.**.** SQLi
18780 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 te contains a hi
18790 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 gh-quality pseud
187a0 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 o-random number
187b0 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 generator (PRNG)
187c0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 used to.** sele
187d0 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 ct random [ROWID
187e0 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 | ROWIDs] when
187f0 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 inserting new re
18800 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 cords into a tab
18810 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 le that.** alrea
18820 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 dy uses the larg
18830 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f est possible [RO
18840 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 WID]. The PRNG
18850 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 is also used for
18860 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e .** the build-in
18870 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 random() and ra
18880 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 ndomblob() SQL f
18890 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 unctions. This
188a0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 interface allows
188b0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 .** applications
188c0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 to access the s
188d0 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 ame PRNG for oth
188e0 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a er purposes..**.
188f0 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 ** A call to thi
18900 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 s routine stores
18910 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 N bytes of rand
18920 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 omness into buff
18930 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 er P..**.** The
18940 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 first time this
18950 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b routine is invok
18960 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 ed (either inter
18970 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 nally or by.** t
18980 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 he application)
18990 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 the PRNG is seed
189a0 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e ed using randomn
189b0 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 ess obtained.**
189c0 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d from the xRandom
189d0 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 ness method of t
189e0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 he default [sqli
189f0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e te3_vfs] object.
18a00 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73 75 62 73 65 .** On all subse
18a10 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e quent invocation
18a20 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 s, the pseudo-ra
18a30 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 ndomness is gene
18a40 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 rated.** interna
18a50 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 lly and without
18a60 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 recourse to the
18a70 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 [sqlite3_vfs] xR
18a80 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 andomness.** met
18a90 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 hod..**.** INVAR
18aa0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 IANTS:.**.** {H1
18ab0 37 33 39 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 7392} The [sqlit
18ac0 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 4e 2c e3_randomness(N,
18ad0 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 72 P)] interface wr
18ae0 69 74 65 73 20 4e 20 62 79 74 65 73 20 6f 66 0a ites N bytes of.
18af0 2a 2a 20 20 20 20 20 20 20 20 20 20 68 69 67 68 ** high
18b00 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d -quality pseudo-
18b10 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 randomness into
18b20 62 75 66 66 65 72 20 50 2e 0a 2a 2f 0a 76 6f 69 buffer P..*/.voi
18b30 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d d sqlite3_random
18b40 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 ness(int N, void
18b50 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 *P);../*.** CAP
18b60 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 I3REF: Compile-T
18b70 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f ime Authorizatio
18b80 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 n Callbacks {H12
18b90 35 30 30 7d 20 3c 53 37 30 31 30 30 3e 0a 2a 2a 500} <S70100>.**
18ba0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
18bb0 20 72 65 67 69 73 74 65 72 73 20 61 20 61 75 74 registers a aut
18bc0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
18bd0 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c with a particul
18be0 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 ar.** [database
18bf0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 connection], sup
18c00 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 plied in the fir
18c10 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 st argument..**
18c20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 The authorizer c
18c30 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
18c40 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d ed as SQL statem
18c50 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 ents are being c
18c60 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 ompiled.** by [s
18c70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
18c80 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 ] or its variant
18c90 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 s [sqlite3_prepa
18ca0 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 re_v2()],.** [sq
18cb0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
18cc0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
18cd0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e prepare16_v2()].
18ce0 20 20 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 At various.**
18cf0 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 points during th
18d00 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 e compilation pr
18d10 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 ocess, as logic
18d20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 is being created
18d30 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 .** to perform v
18d40 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 arious actions,
18d50 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
18d60 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
18d70 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 ed to.** see if
18d80 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 those actions ar
18d90 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20 e allowed. The
18da0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
18db0 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 ack should.** re
18dc0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d turn [SQLITE_OK]
18dd0 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 to allow the ac
18de0 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 tion, [SQLITE_IG
18df0 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f NORE] to disallo
18e00 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 w the.** specifi
18e10 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c c action but all
18e20 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 ow the SQL state
18e30 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 ment to continue
18e40 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c to be.** compil
18e50 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 ed, or [SQLITE_D
18e60 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 ENY] to cause th
18e70 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 e entire SQL sta
18e80 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 tement to be.**
18e90 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e rejected with an
18ea0 20 65 72 72 6f 72 2e 20 20 49 66 20 74 68 65 20 error. If the
18eb0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
18ec0 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 ack returns.** a
18ed0 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 ny value other t
18ee0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f han [SQLITE_IGNO
18ef0 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d RE], [SQLITE_OK]
18f00 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e , or [SQLITE_DEN
18f10 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b Y].** then the [
18f20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
18f30 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c v2()] or equival
18f40 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 ent call that tr
18f50 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 iggered.** the a
18f60 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 uthorizer will f
18f70 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f ail with an erro
18f80 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a r message..**.**
18f90 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 When the callba
18fa0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ck returns [SQLI
18fb0 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 TE_OK], that mea
18fc0 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e ns the operation
18fd0 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 .** requested is
18fe0 20 6f 6b 2e 20 20 57 68 65 6e 20 74 68 65 20 63 ok. When the c
18ff0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
19000 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 [SQLITE_DENY], t
19010 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 he.** [sqlite3_p
19020 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
19030 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 equivalent call
19040 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 that triggered t
19050 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 he.** authorizer
19060 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 will fail with
19070 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 an error message
19080 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 explaining that
19090 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 .** access is de
190a0 6e 69 65 64 2e 20 20 49 66 20 74 68 65 20 61 75 nied. If the au
190b0 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 69 73 thorizer code is
190c0 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a [SQLITE_READ].*
190d0 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 * and the callba
190e0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ck returns [SQLI
190f0 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 TE_IGNORE] then
19100 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 the.** [prepared
19110 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 statement] stat
19120 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 ement is constru
19130 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 cted to substitu
19140 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c te.** a NULL val
19150 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 ue in place of t
19160 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 he table column
19170 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a that would have.
19180 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 ** been read if
19190 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 [SQLITE_OK] had
191a0 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 been returned.
191b0 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f The [SQLITE_IGNO
191c0 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 RE].** return ca
191d0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e n be used to den
191e0 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 y an untrusted u
191f0 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e ser access to in
19200 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 dividual.** colu
19210 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a mns of a table..
19220 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
19230 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
19240 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
19250 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f back is a copy o
19260 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 f the third.** p
19270 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
19280 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
19290 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 orizer() interfa
192a0 63 65 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 ce. The second p
192b0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 arameter.** to t
192c0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 he callback is a
192d0 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 n integer [SQLIT
192e0 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 E_COPY | action
192f0 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 code] that speci
19300 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 fies.** the part
19310 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f icular action to
19320 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 be authorized.
19330 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 The third throug
19340 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 h sixth paramete
19350 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c rs.** to the cal
19360 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 lback are zero-t
19370 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 erminated string
19380 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 s that contain a
19390 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 dditional.** det
193a0 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 ails about the a
193b0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 ction to be auth
193c0 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e orized..**.** An
193d0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 authorizer is u
193e0 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 sed when [sqlite
193f0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 3_prepare | prep
19400 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 aring].** SQL st
19410 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e atements from an
19420 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 untrusted sourc
19430 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 e, to ensure tha
19440 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d t the SQL statem
19450 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 ents.** do not t
19460 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 ry to access dat
19470 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 a they are not a
19480 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f llowed to see, o
19490 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e r that they do n
194a0 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 ot.** try to exe
194b0 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 cute malicious s
194c0 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 tatements that d
194d0 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 amage the databa
194e0 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d se. For.** exam
194f0 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 ple, an applicat
19500 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 ion may allow a
19510 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 user to enter ar
19520 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 bitrary.** SQL q
19530 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 ueries for evalu
19540 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 ation by a datab
19550 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 ase. But the ap
19560 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a plication does.*
19570 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 * not want the u
19580 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 ser to be able t
19590 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 o make arbitrary
195a0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a changes to the.
195b0 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e ** database. An
195c0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c authorizer coul
195d0 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e d then be put in
195e0 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 place while the
195f0 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 .** user-entered
19600 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 SQL is being [s
19610 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c qlite3_prepare |
19620 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a prepared] that.
19630 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 ** disallows eve
19640 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b rything except [
19650 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
19660 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 ts..**.** Applic
19670 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 ations that need
19680 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 to process SQL
19690 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 from untrusted s
196a0 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 ources.** might
196b0 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f also consider lo
196c0 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 wering resource
196d0 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 limits using [sq
196e0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a lite3_limit()].*
196f0 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 * and limiting d
19700 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 atabase size usi
19710 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 ng the [max_page
19720 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d _count] [PRAGMA]
19730 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 .** in addition
19740 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 to using an auth
19750 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e orizer..**.** On
19760 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 ly a single auth
19770 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e orizer can be in
19780 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 place on a data
19790 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a base connection.
197a0 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 ** at a time. E
197b0 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 ach call to sqli
197c0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
197d0 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 er overrides the
197e0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c .** previous cal
197f0 6c 2e 20 20 44 69 73 61 62 6c 65 20 74 68 65 20 l. Disable the
19800 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e authorizer by in
19810 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 stalling a NULL
19820 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 callback..** The
19830 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 authorizer is d
19840 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 isabled by defau
19850 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 lt..**.** The au
19860 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
19870 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e k must not do an
19880 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c ything that will
19890 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 modify.** the d
198a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
198b0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 on that invoked
198c0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
198d0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 allback..** Note
198e0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 that [sqlite3_p
198f0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 repare_v2()] and
19900 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
19910 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 ] both modify th
19920 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 eir.** database
19930 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 connections for
19940 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 the meaning of "
19950 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 modify" in this
19960 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a paragraph..**.**
19970 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 When [sqlite3_p
19980 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 repare_v2()] is
19990 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 used to prepare
199a0 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 a statement, the
199b0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 .** statement mi
199c0 67 68 74 20 62 65 20 72 65 70 72 65 70 61 72 65 ght be reprepare
199d0 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 d during [sqlite
199e0 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 3_step()] due to
199f0 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 a .** schema ch
19a00 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 ange. Hence, th
19a10 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 e application sh
19a20 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 ould ensure that
19a30 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 the.** correct
19a40 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
19a50 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 ack remains in p
19a60 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 lace during the
19a70 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
19a80 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ..**.** Note tha
19a90 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 t the authorizer
19aa0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
19ab0 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 oked only during
19ac0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
19ad0 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 pare()] or its v
19ae0 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 ariants. Author
19af0 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a ization is not.*
19b00 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 * performed duri
19b10 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 ng statement eva
19b20 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 luation in [sqli
19b30 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a te3_step()]..**.
19b40 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
19b50 2a 0a 2a 2a 20 7b 48 31 32 35 30 31 7d 20 54 68 *.** {H12501} Th
19b60 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 e [sqlite3_set_a
19b70 75 74 68 6f 72 69 7a 65 72 28 44 2c 2e 2e 2e 29 uthorizer(D,...)
19b80 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 ] interface regi
19b90 73 74 65 72 73 20 61 0a 2a 2a 20 20 20 20 20 20 sters a.**
19ba0 20 20 20 20 61 75 74 68 6f 72 69 7a 65 72 20 63 authorizer c
19bb0 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 64 61 74 allback with dat
19bc0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
19bd0 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 D..**.** {H1250
19be0 32 7d 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 2} The authorize
19bf0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e r callback is in
19c00 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 voked as SQL sta
19c10 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 20 tements are.**
19c20 20 20 20 20 20 20 20 20 62 65 69 6e 67 20 70 61 being pa
19c30 72 73 65 65 64 20 61 6e 64 20 63 6f 6d 70 69 6c rseed and compil
19c40 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 ed..**.** {H1250
19c50 33 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 3} If the author
19c60 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 izer callback re
19c70 74 75 72 6e 73 20 61 6e 79 20 76 61 6c 75 65 20 turns any value
19c80 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 other than.**
19c90 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 [SQLITE_I
19ca0 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f GNORE], [SQLITE_
19cb0 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f OK], or [SQLITE_
19cc0 44 45 4e 59 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20 DENY], then.**
19cd0 20 20 20 20 20 20 20 20 74 68 65 20 61 70 70 6c the appl
19ce0 69 63 61 74 69 6f 6e 20 69 6e 74 65 72 66 61 63 ication interfac
19cf0 65 20 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73 e call that caus
19d00 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 ed.** t
19d10 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
19d20 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68 llback to run sh
19d30 61 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e all fail with an
19d40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 .** [SQ
19d50 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f LITE_ERROR] erro
19d60 72 20 63 6f 64 65 20 61 6e 64 20 61 6e 20 61 70 r code and an ap
19d70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 propriate error
19d80 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b message..**.** {
19d90 48 31 32 35 30 34 7d 20 57 68 65 6e 20 74 68 65 H12504} When the
19da0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
19db0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 back returns [SQ
19dc0 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 20 6f 70 LITE_OK], the op
19dd0 65 72 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 eration.**
19de0 20 20 20 20 64 65 73 63 72 69 62 65 64 20 69 73 described is
19df0 20 70 72 6f 63 65 73 73 65 64 20 6e 6f 72 6d 61 processed norma
19e00 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 lly..**.** {H125
19e10 30 35 7d 20 57 68 65 6e 20 74 68 65 20 61 75 74 05} When the aut
19e20 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
19e30 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
19e40 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 20 _DENY], the.**
19e50 20 20 20 20 20 20 20 20 61 70 70 6c 69 63 61 74 applicat
19e60 69 6f 6e 20 69 6e 74 65 72 66 61 63 65 20 63 61 ion interface ca
19e70 6c 6c 20 74 68 61 74 20 63 61 75 73 65 64 20 74 ll that caused t
19e80 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 he.** a
19e90 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
19ea0 63 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c 6c 20 ck to run shall
19eb0 66 61 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 fail.**
19ec0 20 77 69 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 with an [SQLITE
19ed0 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72 20 63 6f _ERROR] error co
19ee0 64 65 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 de and an error
19ef0 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 message.**
19f00 20 20 20 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 explaining t
19f10 68 61 74 20 61 63 63 65 73 73 20 69 73 20 64 65 hat access is de
19f20 6e 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 nied..**.** {H12
19f30 35 30 36 7d 20 49 66 20 74 68 65 20 61 75 74 68 506} If the auth
19f40 6f 72 69 7a 65 72 20 63 6f 64 65 20 28 74 68 65 orizer code (the
19f50 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 2nd parameter t
19f60 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 o the authorizer
19f70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c .** cal
19f80 6c 62 61 63 6b 29 20 69 73 20 5b 53 51 4c 49 54 lback) is [SQLIT
19f90 45 5f 52 45 41 44 5d 20 61 6e 64 20 74 68 65 20 E_READ] and the
19fa0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
19fb0 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 ack returns.**
19fc0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f [SQLITE_
19fd0 49 47 4e 4f 52 45 5d 2c 20 74 68 65 6e 20 74 68 IGNORE], then th
19fe0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 e prepared state
19ff0 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 ment is construc
1a000 74 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 ted to.**
1a010 20 20 20 69 6e 73 65 72 74 20 61 20 4e 55 4c 4c insert a NULL
1a020 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 value in place
1a030 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c of the table col
1a040 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 umn that would h
1a050 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ave.**
1a060 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 been read if [SQ
1a070 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 LITE_OK] had bee
1a080 6e 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a n returned..**.*
1a090 2a 20 7b 48 31 32 35 30 37 7d 20 49 66 20 74 68 * {H12507} If th
1a0a0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 e authorizer cod
1a0b0 65 20 28 74 68 65 20 32 6e 64 20 70 61 72 61 6d e (the 2nd param
1a0c0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 eter to the auth
1a0d0 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 orizer.**
1a0e0 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69 73 20 callback) is
1a0f0 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 20 74 anything other t
1a100 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 han [SQLITE_READ
1a110 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 ], then.**
1a120 20 20 20 20 61 20 72 65 74 75 72 6e 20 6f 66 20 a return of
1a130 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 [SQLITE_IGNORE]
1a140 68 61 73 20 74 68 65 20 73 61 6d 65 20 65 66 66 has the same eff
1a150 65 63 74 20 61 73 20 5b 53 51 4c 49 54 45 5f 44 ect as [SQLITE_D
1a160 45 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 ENY]..**.** {H12
1a170 35 31 30 7d 20 54 68 65 20 66 69 72 73 74 20 70 510} The first p
1a180 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
1a190 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1a1a0 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 ack is a copy of
1a1b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
1a1c0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
1a1d0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
1a1e0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 _set_authorizer(
1a1f0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a )] interface..**
1a200 0a 2a 2a 20 7b 48 31 32 35 31 31 7d 20 54 68 65 .** {H12511} The
1a210 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
1a220 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 r to the callbac
1a230 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a k is an integer.
1a240 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c ** [SQL
1a250 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f ITE_COPY | actio
1a260 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 n code] that spe
1a270 63 69 66 69 65 73 20 74 68 65 20 70 61 72 74 69 cifies the parti
1a280 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20 cular action.**
1a290 20 20 20 20 20 20 20 20 20 74 6f 20 62 65 20 61 to be a
1a2a0 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a uthorized..**.**
1a2b0 20 7b 48 31 32 35 31 32 7d 20 54 68 65 20 74 68 {H12512} The th
1a2c0 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 ird through sixt
1a2d0 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 h parameters to
1a2e0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 the callback are
1a2f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 .** zer
1a300 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 o-terminated str
1a310 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 ings that contai
1a320 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 64 n.** ad
1a330 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 ditional details
1a340 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f about the actio
1a350 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a n to be authoriz
1a360 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 32 ed..**.** {H1252
1a370 30 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 0} Each call to
1a380 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 [sqlite3_set_aut
1a390 68 6f 72 69 7a 65 72 28 29 5d 20 6f 76 65 72 72 horizer()] overr
1a3a0 69 64 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 ides.**
1a3b0 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 any previously
1a3c0 69 6e 73 74 61 6c 6c 65 64 20 61 75 74 68 6f 72 installed author
1a3d0 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 izer..**.** {H12
1a3e0 35 32 31 7d 20 41 20 4e 55 4c 4c 20 61 75 74 68 521} A NULL auth
1a3f0 6f 72 69 7a 65 72 20 6d 65 61 6e 73 20 74 68 61 orizer means tha
1a400 74 20 6e 6f 20 61 75 74 68 6f 72 69 7a 61 74 69 t no authorizati
1a410 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 on.** c
1a420 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
1a430 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 32 ed..**.** {H1252
1a440 32 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 61 2} The default a
1a450 75 74 68 6f 72 69 7a 65 72 20 69 73 20 4e 55 4c uthorizer is NUL
1a460 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 L..*/.int sqlite
1a470 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
1a480 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 (. sqlite3*,.
1a490 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 int (*xAuth)(voi
1a4a0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 d*,int,const cha
1a4b0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 r*,const char*,c
1a4c0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 onst char*,const
1a4d0 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 char*),. void
1a4e0 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f *pUserData.);../
1a4f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 *.** CAPI3REF: A
1a500 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e uthorizer Return
1a510 20 43 6f 64 65 73 20 7b 48 31 32 35 39 30 7d 20 Codes {H12590}
1a520 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <H12500>.**.** T
1a530 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f he [sqlite3_set_
1a540 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 authorizer | aut
1a550 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
1a560 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a function] must.
1a570 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 ** return either
1a580 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 [SQLITE_OK] or
1a590 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f one of these two
1a5a0 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 constants in or
1a5b0 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c der.** to signal
1a5c0 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 SQLite whether
1a5d0 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f or not the actio
1a5e0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 n is permitted.
1a5f0 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c See the.** [sql
1a600 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
1a610 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 zer | authorizer
1a620 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 documentation]
1a630 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a for additional.*
1a640 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a * information..*
1a650 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1a660 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 _DENY 1 /* A
1a670 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 bort the SQL sta
1a680 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 tement with an e
1a690 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rror */.#define
1a6a0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 SQLITE_IGNORE 2
1a6b0 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 /* Don't allow
1a6c0 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e access, but don
1a6d0 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 't generate an e
1a6e0 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 rror */../*.** C
1a6f0 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 API3REF: Authori
1a700 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 zer Action Codes
1a710 20 7b 48 31 32 35 35 30 7d 20 3c 48 31 32 35 30 {H12550} <H1250
1a720 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 0>.**.** The [sq
1a730 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
1a740 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 izer()] interfac
1a750 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 e registers a ca
1a760 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a llback function.
1a770 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b ** that is invok
1a780 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 ed to authorize
1a790 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 certain SQL stat
1a7a0 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 ement actions.
1a7b0 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 The.** second pa
1a7c0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 rameter to the c
1a7d0 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e allback is an in
1a7e0 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 teger code that
1a7f0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 specifies.** wha
1a800 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e t action is bein
1a810 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 g authorized. T
1a820 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 hese are the int
1a830 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 eger action code
1a840 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 s that.** the au
1a850 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
1a860 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e k may be passed.
1a870 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 .**.** These act
1a880 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 ion code values
1a890 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e signify what kin
1a8a0 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 d of operation i
1a8b0 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f s to be.** autho
1a8c0 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 rized. The 3rd
1a8d0 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 and 4th paramete
1a8e0 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 rs to the author
1a8f0 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 ization.** callb
1a900 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c ack function wil
1a910 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 l be parameters
1a920 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e or NULL dependin
1a930 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 g on which of th
1a940 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 ese.** codes is
1a950 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f used as the seco
1a960 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 nd parameter. T
1a970 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 he 5th parameter
1a980 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f to the.** autho
1a990 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 rizer callback i
1a9a0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
1a9b0 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 e database ("mai
1a9c0 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 n", "temp",.** e
1a9d0 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 tc.) if applicab
1a9e0 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70 61 72 le. The 6th par
1a9f0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 ameter to the au
1aa00 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
1aa10 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 k.** is the name
1aa20 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f of the inner-mo
1aa30 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 st trigger or vi
1aa40 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f ew that is respo
1aa50 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 nsible for.** th
1aa60 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 e access attempt
1aa70 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 or NULL if this
1aa80 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 access attempt
1aa90 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d is directly from
1aaa0 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 .** top-level SQ
1aab0 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e L code..**.** IN
1aac0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
1aad0 7b 48 31 32 35 35 31 7d 20 54 68 65 20 73 65 63 {H12551} The sec
1aae0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ond parameter to
1aaf0 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 an.**
1ab00 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 [sqlite3_set_aut
1ab10 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 horizer | author
1ab20 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 73 izer callback] s
1ab30 68 61 6c 6c 20 62 65 20 61 6e 20 69 6e 74 65 67 hall be an integ
1ab40 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b er.** [
1ab50 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 75 SQLITE_COPY | au
1ab60 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d 20 74 thorizer code] t
1ab70 68 61 74 20 73 70 65 63 69 66 69 65 73 20 77 68 hat specifies wh
1ab80 61 74 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 at action.**
1ab90 20 20 20 20 20 20 69 73 20 62 65 69 6e 67 20 61 is being a
1aba0 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a uthorized..**.**
1abb0 20 7b 48 31 32 35 35 32 7d 20 54 68 65 20 33 72 {H12552} The 3r
1abc0 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 d and 4th parame
1abd0 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 20 ters to the.**
1abe0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
1abf0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 _set_authorizer
1ac00 7c 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 | authorization
1ac10 63 61 6c 6c 62 61 63 6b 5d 0a 2a 2a 20 20 20 20 callback].**
1ac20 20 20 20 20 20 20 73 68 61 6c 6c 20 62 65 20 70 shall be p
1ac30 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c arameters or NUL
1ac40 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 L depending on w
1ac50 68 69 63 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 hich.**
1ac60 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 [SQLITE_COPY |
1ac70 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d authorizer code]
1ac80 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 is used as the
1ac90 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
1aca0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 33 7d ..**.** {H12553}
1acb0 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 The 5th paramet
1acc0 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 er to the.**
1acd0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 [sqlite3_s
1ace0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 et_authorizer |
1acf0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1ad00 61 63 6b 5d 20 73 68 61 6c 6c 20 62 65 20 74 68 ack] shall be th
1ad10 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 e name.**
1ad20 20 20 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 of the databa
1ad30 73 65 20 28 65 78 61 6d 70 6c 65 3a 20 22 6d 61 se (example: "ma
1ad40 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 65 74 63 in", "temp", etc
1ad50 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 .) if applicable
1ad60 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 34 7d ..**.** {H12554}
1ad70 20 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 The 6th paramet
1ad80 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 er to the.**
1ad90 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 [sqlite3_s
1ada0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 et_authorizer |
1adb0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1adc0 61 63 6b 5d 20 73 68 61 6c 6c 20 62 65 20 74 68 ack] shall be th
1add0 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 e name.**
1ade0 20 20 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d of the inner-
1adf0 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 most trigger or
1ae00 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 view that is res
1ae10 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 ponsible for.**
1ae20 20 20 20 20 20 20 20 20 20 74 68 65 20 61 63 63 the acc
1ae30 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e ess attempt or N
1ae40 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 ULL if this acce
1ae50 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 ss attempt is di
1ae60 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 20 rectly from.**
1ae70 20 20 20 20 20 20 20 20 74 6f 70 2d 6c 65 76 65 top-leve
1ae80 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f l SQL code..*/./
1ae90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1aea0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1aeb0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 *********** 3rd
1aec0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 ************ 4th
1aed0 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 ***********/.#d
1aee0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
1aef0 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 ATE_INDEX
1af00 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 1 /* Index
1af10 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 Name Table
1af20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
1af30 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
1af40 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 TE_TABLE
1af50 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 2 /* Table N
1af60 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
1af70 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
1af80 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
1af90 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 E_TEMP_INDEX
1afa0 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 3 /* Index Na
1afb0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 me Table Na
1afc0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
1afd0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
1afe0 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 _TEMP_TABLE
1aff0 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 4 /* Table Nam
1b000 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
1b010 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
1b020 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
1b030 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 TEMP_TRIGGER 5
1b040 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 /* Trigger Na
1b050 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 me Table Name
1b060 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1b070 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 SQLITE_CREATE_T
1b080 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 EMP_VIEW 6
1b090 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 /* View Name
1b0a0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
1b0b0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1b0c0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 SQLITE_CREATE_TR
1b0d0 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 IGGER 7
1b0e0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 /* Trigger Name
1b0f0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
1b100 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1b110 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 QLITE_CREATE_VIE
1b120 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 W 8
1b130 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 /* View Name
1b140 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
1b150 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1b160 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 LITE_DELETE
1b170 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 9 /
1b180 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
1b190 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
1b1a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1b1b0 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 ITE_DROP_INDEX
1b1c0 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 10 /*
1b1d0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 Index Name
1b1e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
1b1f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1b200 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 TE_DROP_TABLE
1b210 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 11 /*
1b220 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
1b230 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
1b240 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1b250 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 E_DROP_TEMP_INDE
1b260 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 X 12 /* I
1b270 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 ndex Name T
1b280 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
1b290 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1b2a0 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 _DROP_TEMP_TABLE
1b2b0 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 13 /* Ta
1b2c0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
1b2d0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
1b2e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1b2f0 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 DROP_TEMP_TRIGGE
1b300 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 R 14 /* Tri
1b310 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 gger Name Tab
1b320 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
1b330 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
1b340 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 ROP_TEMP_VIEW
1b350 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 15 /* View
1b360 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c Name NULL
1b370 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
1b380 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
1b390 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 OP_TRIGGER
1b3a0 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 16 /* Trigg
1b3b0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 er Name Table
1b3c0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
1b3d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
1b3e0 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 P_VIEW
1b3f0 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 17 /* View N
1b400 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 ame NULL
1b410 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
1b420 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 fine SQLITE_INSE
1b430 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 RT
1b440 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 18 /* Table N
1b450 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
1b460 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
1b470 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d ine SQLITE_PRAGM
1b480 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 A
1b490 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 19 /* Pragma N
1b4a0 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 ame 1st arg
1b4b0 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 or NULL */.#defi
1b4c0 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 ne SQLITE_READ
1b4d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 2
1b4e0 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 0 /* Table Nam
1b4f0 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 e Column Na
1b500 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e me */.#defin
1b510 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 e SQLITE_SELECT
1b520 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 21
1b530 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 /* NULL
1b540 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
1b550 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1b560 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 SQLITE_TRANSACT
1b570 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 ION 22
1b580 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 /* Operation
1b590 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
1b5a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1b5b0 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 SQLITE_UPDATE
1b5c0 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 23
1b5d0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
1b5e0 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 Column Name
1b5f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1b600 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 QLITE_ATTACH
1b610 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 24
1b620 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 /* Filename
1b630 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
1b640 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1b650 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 LITE_DETACH
1b660 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 25 /
1b670 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 * Database Name
1b680 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
1b690 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1b6a0 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 ITE_ALTER_TABLE
1b6b0 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 26 /*
1b6c0 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 Database Name
1b6d0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
1b6e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1b6f0 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 TE_REINDEX
1b700 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 27 /*
1b710 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 Index Name
1b720 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
1b730 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1b740 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 E_ANALYZE
1b750 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 28 /* T
1b760 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
1b770 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
1b780 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1b790 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 _CREATE_VTABLE
1b7a0 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 29 /* Ta
1b7b0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f ble Name Mo
1b7c0 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f dule Name */
1b7d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1b7e0 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 DROP_VTABLE
1b7f0 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 30 /* Tab
1b800 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 le Name Mod
1b810 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a ule Name */.
1b820 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
1b830 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 UNCTION
1b840 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 31 /* NULL
1b850 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 Func
1b860 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 tion Name */.#
1b870 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 define SQLITE_SA
1b880 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 VEPOINT
1b890 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 32 /* Opera
1b8a0 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 tion Savep
1b8b0 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 oint Name */.#d
1b8c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 efine SQLITE_COP
1b8d0 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 Y
1b8e0 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 0 /* No lon
1b8f0 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a ger used */../*.
1b900 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 ** CAPI3REF: Tra
1b910 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 cing And Profili
1b920 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 ng Functions {H1
1b930 32 32 38 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2280} <S60400>.*
1b940 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
1b950 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
1b960 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c nes register cal
1b970 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 lback functions
1b980 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 that can be used
1b990 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 for.** tracing
1b9a0 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 and profiling th
1b9b0 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 e execution of S
1b9c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a QL statements..*
1b9d0 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 *.** The callbac
1b9e0 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 k function regis
1b9f0 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 tered by sqlite3
1ba00 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f _trace() is invo
1ba10 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 ked at.** variou
1ba20 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 s times when an
1ba30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 SQL statement is
1ba40 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 being run by [s
1ba50 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a qlite3_step()]..
1ba60 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 ** The callback
1ba70 72 65 74 75 72 6e 73 20 61 20 55 54 46 2d 38 20 returns a UTF-8
1ba80 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 rendering of the
1ba90 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
1baa0 65 78 74 0a 2a 2a 20 61 73 20 74 68 65 20 73 74 ext.** as the st
1bab0 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 atement first be
1bac0 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 20 gins executing.
1bad0 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 61 6c 6c Additional call
1bae0 62 61 63 6b 73 20 6f 63 63 75 72 0a 2a 2a 20 61 backs occur.** a
1baf0 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 s each triggered
1bb00 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 subprogram is e
1bb10 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c ntered. The cal
1bb20 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 lbacks for trigg
1bb30 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 ers.** contain a
1bb40 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 UTF-8 SQL comme
1bb50 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 nt that identifi
1bb60 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 0a es the trigger..
1bb70 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 **.** The callba
1bb80 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 ck function regi
1bb90 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 stered by sqlite
1bba0 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 3_profile() is i
1bbb0 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 nvoked.** as eac
1bbc0 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 h SQL statement
1bbd0 66 69 6e 69 73 68 65 73 2e 20 20 54 68 65 20 70 finishes. The p
1bbe0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 rofile callback
1bbf0 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 contains.** the
1bc00 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 original stateme
1bc10 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 nt text and an e
1bc20 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d stimate of wall-
1bc30 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 clock time.** of
1bc40 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 how long that s
1bc50 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f tatement took to
1bc60 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 run..**.** INVA
1bc70 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 RIANTS:.**.** {H
1bc80 31 32 32 38 31 7d 20 54 68 65 20 63 61 6c 6c 62 12281} The callb
1bc90 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 ack function reg
1bca0 69 73 74 65 72 65 64 20 62 79 20 5b 73 71 6c 69 istered by [sqli
1bcb0 74 65 33 5f 74 72 61 63 65 28 29 5d 20 0a 2a 2a te3_trace()] .**
1bcc0 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 shall
1bcd0 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 be invoked.**
1bce0 20 20 20 20 20 20 20 77 68 65 6e 65 76 65 72 20 whenever
1bcf0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 an SQL statement
1bd00 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 74 6f first begins to
1bd10 20 65 78 65 63 75 74 65 20 61 6e 64 0a 2a 2a 20 execute and.**
1bd20 20 20 20 20 20 20 20 20 20 77 68 65 6e 65 76 65 wheneve
1bd30 72 20 61 20 74 72 69 67 67 65 72 20 73 75 62 70 r a trigger subp
1bd40 72 6f 67 72 61 6d 20 66 69 72 73 74 20 62 65 67 rogram first beg
1bd50 69 6e 73 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a ins to run..**.*
1bd60 2a 20 7b 48 31 32 32 38 32 7d 20 45 61 63 68 20 * {H12282} Each
1bd70 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
1bd80 5f 74 72 61 63 65 28 29 5d 20 73 68 61 6c 6c 20 _trace()] shall
1bd90 6f 76 65 72 72 69 64 65 20 74 68 65 20 70 72 65 override the pre
1bda0 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 viously.**
1bdb0 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20 74 registered t
1bdc0 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a race callback..*
1bdd0 2a 0a 2a 2a 20 7b 48 31 32 32 38 33 7d 20 41 20 *.** {H12283} A
1bde0 4e 55 4c 4c 20 74 72 61 63 65 20 63 61 6c 6c 62 NULL trace callb
1bdf0 61 63 6b 20 73 68 61 6c 6c 20 64 69 73 61 62 6c ack shall disabl
1be00 65 20 74 72 61 63 69 6e 67 2e 0a 2a 2a 0a 2a 2a e tracing..**.**
1be10 20 7b 48 31 32 32 38 34 7d 20 54 68 65 20 66 69 {H12284} The fi
1be20 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
1be30 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 the trace callba
1be40 63 6b 20 73 68 61 6c 6c 20 62 65 20 61 20 63 6f ck shall be a co
1be50 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 py of.**
1be60 20 20 74 68 65 20 70 6f 69 6e 74 65 72 20 77 68 the pointer wh
1be70 69 63 68 20 77 61 73 20 74 68 65 20 33 72 64 20 ich was the 3rd
1be80 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c argument to [sql
1be90 69 74 65 33 5f 74 72 61 63 65 28 29 5d 2e 0a 2a ite3_trace()]..*
1bea0 2a 0a 2a 2a 20 7b 48 31 32 32 38 35 7d 20 54 68 *.** {H12285} Th
1beb0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
1bec0 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 t to the trace c
1bed0 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20 allback is a.**
1bee0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 zero-te
1bef0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 rminated UTF-8 s
1bf00 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 tring containing
1bf10 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 74 65 the original te
1bf20 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f xt.** o
1bf30 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d f the SQL statem
1bf40 65 6e 74 20 61 73 20 69 74 20 77 61 73 20 70 61 ent as it was pa
1bf50 73 73 65 64 20 69 6e 74 6f 20 5b 73 71 6c 69 74 ssed into [sqlit
1bf60 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
1bf70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 .** or
1bf80 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 2c 20 the equivalent,
1bf90 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e or an SQL commen
1bfa0 74 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 t indicating the
1bfb0 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 20 20 beginning.**
1bfc0 20 20 20 20 20 20 20 6f 66 20 61 20 74 72 69 67 of a trig
1bfd0 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 0a ger subprogram..
1bfe0 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 37 7d 20 54 **.** {H12287} T
1bff0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 he callback func
1c000 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 tion registered
1c010 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 by [sqlite3_prof
1c020 69 6c 65 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 ile()] is invoke
1c030 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 d.** as
1c040 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d each SQL statem
1c050 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a ent finishes..**
1c060 0a 2a 2a 20 7b 48 31 32 32 38 38 7d 20 54 68 65 .** {H12288} The
1c070 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
1c080 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 to the profile
1c090 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f callback is a co
1c0a0 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 py of.**
1c0b0 20 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 the 3rd parame
1c0c0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
1c0d0 70 72 6f 66 69 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a profile()]..**.*
1c0e0 2a 20 7b 48 31 32 32 38 39 7d 20 54 68 65 20 73 * {H12289} The s
1c0f0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
1c100 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63 to the profile c
1c110 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20 allback is a.**
1c120 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 zero-te
1c130 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 rminated UTF-8 s
1c140 74 72 69 6e 67 20 74 68 61 74 20 63 6f 6e 74 61 tring that conta
1c150 69 6e 73 20 74 68 65 20 63 6f 6d 70 6c 65 74 65 ins the complete
1c160 20 74 65 78 74 20 6f 66 0a 2a 2a 20 20 20 20 20 text of.**
1c170 20 20 20 20 20 74 68 65 20 53 51 4c 20 73 74 61 the SQL sta
1c180 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77 61 73 tement as it was
1c190 20 70 72 6f 63 65 73 73 65 64 20 62 79 20 5b 73 processed by [s
1c1a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1c1b0 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 2()].**
1c1c0 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 or the equivale
1c1d0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 39 nt..**.** {H1229
1c1e0 30 7d 20 54 68 65 20 74 68 69 72 64 20 70 61 72 0} The third par
1c1f0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70 72 ameter to the pr
1c200 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 ofile callback i
1c210 73 20 61 6e 20 65 73 74 69 6d 61 74 65 0a 2a 2a s an estimate.**
1c220 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 of the
1c230 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73 number of nanos
1c240 65 63 6f 6e 64 73 20 6f 66 20 77 61 6c 6c 2d 63 econds of wall-c
1c250 6c 6f 63 6b 20 74 69 6d 65 20 72 65 71 75 69 72 lock time requir
1c260 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 ed to.**
1c270 20 20 72 75 6e 20 74 68 65 20 53 51 4c 20 73 74 run the SQL st
1c280 61 74 65 6d 65 6e 74 20 66 72 6f 6d 20 73 74 61 atement from sta
1c290 72 74 20 74 6f 20 66 69 6e 69 73 68 2e 0a 2a 2f rt to finish..*/
1c2a0 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 .SQLITE_EXPERIME
1c2b0 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 NTAL void *sqlit
1c2c0 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 e3_trace(sqlite3
1c2d0 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 *, void(*xTrace)
1c2e0 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 (void*,const cha
1c2f0 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c r*), void*);.SQL
1c300 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c ITE_EXPERIMENTAL
1c310 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 void *sqlite3_p
1c320 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c rofile(sqlite3*,
1c330 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 . void(*xProfi
1c340 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 le)(void*,const
1c350 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 char*,sqlite3_ui
1c360 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a nt64), void*);..
1c370 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1c380 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 Query Progress C
1c390 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 31 30 allbacks {H12910
1c3a0 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a } <S60400>.**.**
1c3b0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f This routine co
1c3c0 6e 66 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62 nfigures a callb
1c3d0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 ack function - t
1c3e0 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 63 he.** progress c
1c3f0 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 20 69 allback - that i
1c400 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 s invoked period
1c410 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f ically during lo
1c420 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61 ng.** running ca
1c430 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
1c440 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 exec()], [sqlite
1c450 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 3_step()] and.**
1c460 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 [sqlite3_get_ta
1c470 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d ble()]. An exam
1c480 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 ple use for this
1c490 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 .** interface is
1c4a0 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 to keep a GUI u
1c4b0 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 pdated during a
1c4c0 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a large query..**.
1c4d0 2a 2a 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 ** If the progre
1c4e0 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 ss callback retu
1c4f0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 rns non-zero, th
1c500 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a e operation is.*
1c510 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 * interrupted.
1c520 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e This feature can
1c530 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c be used to impl
1c540 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 ement a.** "Canc
1c550 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 el" button on a
1c560 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 GUI progress dia
1c570 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 log box..**.** T
1c580 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 he progress hand
1c590 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 ler must not do
1c5a0 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 anything that wi
1c5b0 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 ll modify.** the
1c5c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1c5d0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 tion that invoke
1c5e0 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 d the progress h
1c5f0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 andler..** Note
1c600 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 that [sqlite3_pr
1c610 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 epare_v2()] and
1c620 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
1c630 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 both modify the
1c640 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 ir.** database c
1c650 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 onnections for t
1c660 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d he meaning of "m
1c670 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 odify" in this p
1c680 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 aragraph..**.**
1c690 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
1c6a0 2a 20 7b 48 31 32 39 31 31 7d 20 54 68 65 20 63 * {H12911} The c
1c6b0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
1c6c0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 registered by s
1c6d0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f qlite3_progress_
1c6e0 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 20 20 20 handler().**
1c6f0 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 is invoked
1c700 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 periodically du
1c710 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e ring long runnin
1c720 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20 g calls to.**
1c730 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
1c740 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b step()]..**.** {
1c750 48 31 32 39 31 32 7d 20 54 68 65 20 70 72 6f 67 H12912} The prog
1c760 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 ress callback is
1c770 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f invoked once fo
1c780 72 20 65 76 65 72 79 20 4e 20 76 69 72 74 75 61 r every N virtua
1c790 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 61 l.** ma
1c7a0 63 68 69 6e 65 20 6f 70 63 6f 64 65 73 2c 20 77 chine opcodes, w
1c7b0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 here N is the se
1c7c0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
1c7d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
1c7e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 [sqlite3_progre
1c7f0 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 20 63 61 ss_handler()] ca
1c800 6c 6c 20 74 68 61 74 20 72 65 67 69 73 74 65 72 ll that register
1c810 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 ed.** t
1c820 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66 he callback. If
1c830 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 N is less than
1c840 31 2c 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 1, sqlite3_progr
1c850 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a ess_handler().**
1c860 20 20 20 20 20 20 20 20 20 20 61 63 74 73 20 61 acts a
1c870 73 20 69 66 20 61 20 4e 55 4c 4c 20 70 72 6f 67 s if a NULL prog
1c880 72 65 73 73 20 68 61 6e 64 6c 65 72 20 68 61 64 ress handler had
1c890 20 62 65 65 6e 20 73 70 65 63 69 66 69 65 64 2e been specified.
1c8a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 33 7d 20 .**.** {H12913}
1c8b0 54 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c The progress cal
1c8c0 6c 62 61 63 6b 20 69 74 73 65 6c 66 20 69 73 20 lback itself is
1c8d0 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 identified by th
1c8e0 65 20 74 68 69 72 64 0a 2a 2a 20 20 20 20 20 20 e third.**
1c8f0 20 20 20 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 argument to
1c900 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 sqlite3_progress
1c910 5f 68 61 6e 64 6c 65 72 28 29 2e 0a 2a 2a 0a 2a _handler()..**.*
1c920 2a 20 7b 48 31 32 39 31 34 7d 20 54 68 65 20 66 * {H12914} The f
1c930 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 ourth argument t
1c940 6f 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 o sqlite3_progre
1c950 73 73 5f 68 61 6e 64 6c 65 72 28 29 20 69 73 20 ss_handler() is
1c960 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 6f a.** vo
1c970 69 64 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 id pointer passe
1c980 64 20 74 6f 20 74 68 65 20 70 72 6f 67 72 65 73 d to the progres
1c990 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 s callback.**
1c9a0 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 function
1c9b0 65 61 63 68 20 74 69 6d 65 20 69 74 20 69 73 20 each time it is
1c9c0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b invoked..**.** {
1c9d0 48 31 32 39 31 35 7d 20 49 66 20 61 20 63 61 6c H12915} If a cal
1c9e0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 l to [sqlite3_st
1c9f0 65 70 28 29 5d 20 72 65 73 75 6c 74 73 20 69 6e ep()] results in
1ca00 20 66 65 77 65 72 20 74 68 61 6e 20 4e 20 6f 70 fewer than N op
1ca10 63 6f 64 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 codes.**
1ca20 20 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 being executed
1ca30 2c 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 , then the progr
1ca40 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 ess callback is
1ca50 6e 65 76 65 72 20 69 6e 76 6f 6b 65 64 2e 0a 2a never invoked..*
1ca60 2a 0a 2a 2a 20 7b 48 31 32 39 31 36 7d 20 45 76 *.** {H12916} Ev
1ca70 65 72 79 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ery call to [sql
1ca80 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 ite3_progress_ha
1ca90 6e 64 6c 65 72 28 29 5d 0a 2a 2a 20 20 20 20 20 ndler()].**
1caa0 20 20 20 20 20 6f 76 65 72 77 72 69 74 65 73 20 overwrites
1cab0 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 72 any previously r
1cac0 65 67 69 73 74 65 72 65 64 20 70 72 6f 67 72 65 egistered progre
1cad0 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a ss handler..**.*
1cae0 2a 20 7b 48 31 32 39 31 37 7d 20 49 66 20 74 68 * {H12917} If th
1caf0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c e progress handl
1cb00 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e er callback is N
1cb10 55 4c 4c 20 74 68 65 6e 20 6e 6f 20 70 72 6f 67 ULL then no prog
1cb20 72 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 ress.**
1cb30 20 68 61 6e 64 6c 65 72 20 69 73 20 69 6e 76 6f handler is invo
1cb40 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 ked..**.** {H129
1cb50 31 38 7d 20 49 66 20 74 68 65 20 70 72 6f 67 72 18} If the progr
1cb60 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 ess callback ret
1cb70 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 6f 74 urns a result ot
1cb80 68 65 72 20 74 68 61 6e 20 30 2c 20 74 68 65 6e her than 0, then
1cb90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
1cba0 20 62 65 68 61 76 69 6f 72 20 69 73 20 61 20 69 behavior is a i
1cbb0 66 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 f [sqlite3_inter
1cbc0 72 75 70 74 28 29 5d 20 68 61 64 20 62 65 65 6e rupt()] had been
1cbd0 20 63 61 6c 6c 65 64 2e 0a 2a 2a 20 20 20 20 20 called..**
1cbe0 20 20 20 20 20 3c 53 33 30 35 30 30 3e 0a 2a 2f <S30500>.*/
1cbf0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 .void sqlite3_pr
1cc00 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 ogress_handler(s
1cc10 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e qlite3*, int, in
1cc20 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 t(*)(void*), voi
1cc30 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d*);../*.** CAPI
1cc40 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 3REF: Opening A
1cc50 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e New Database Con
1cc60 6e 65 63 74 69 6f 6e 20 7b 48 31 32 37 30 30 7d nection {H12700}
1cc70 20 3c 53 34 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S40200>.**.**
1cc80 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f These routines o
1cc90 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 pen an SQLite da
1cca0 74 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73 tabase file whos
1ccb0 65 20 6e 61 6d 65 20 69 73 20 67 69 76 65 6e 20 e name is given
1ccc0 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 by the.** filena
1ccd0 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 65 me argument. The
1cce0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 filename argume
1ccf0 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 nt is interprete
1cd00 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a d as UTF-8 for.*
1cd10 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 * sqlite3_open()
1cd20 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 and sqlite3_ope
1cd30 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 n_v2() and as UT
1cd40 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 F-16 in the nati
1cd50 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 ve byte.** order
1cd60 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 for sqlite3_ope
1cd70 6e 31 36 28 29 2e 20 41 20 5b 64 61 74 61 62 61 n16(). A [databa
1cd80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 se connection] h
1cd90 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 andle is usually
1cda0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 .** returned in
1cdb0 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 *ppDb, even if a
1cdc0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 n error occurs.
1cdd0 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 The only except
1cde0 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 ion is that.** i
1cdf0 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 f SQLite is unab
1ce00 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d le to allocate m
1ce10 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 emory to hold th
1ce20 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 e [sqlite3] obje
1ce30 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 ct,.** a NULL wi
1ce40 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e ll be written in
1ce50 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 to *ppDb instead
1ce60 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f of a pointer to
1ce70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a the [sqlite3].*
1ce80 2a 20 6f 62 6a 65 63 74 2e 20 49 66 20 74 68 65 * object. If the
1ce90 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
1cea0 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 ned (and/or crea
1ceb0 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c ted) successfull
1cec0 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 y, then.** [SQLI
1ced0 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e TE_OK] is return
1cee0 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 ed. Otherwise a
1cef0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 n [error code] i
1cf00 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 s returned. The
1cf10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 .** [sqlite3_err
1cf20 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 msg()] or [sqlit
1cf30 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 e3_errmsg16()] r
1cf40 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 outines can be u
1cf50 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a sed to obtain.**
1cf60 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 an English lang
1cf70 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e uage description
1cf80 20 6f 66 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a of the error..*
1cf90 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 *.** The default
1cfa0 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 encoding for th
1cfb0 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 e database will
1cfc0 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 be UTF-8 if.** s
1cfd0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 qlite3_open() or
1cfe0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
1cff0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 () is called and
1d000 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 .** UTF-16 in th
1d010 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 e native byte or
1d020 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f der if sqlite3_o
1d030 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e pen16() is used.
1d040 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f .**.** Whether o
1d050 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f r not an error o
1d060 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 ccurs when it is
1d070 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 opened, resourc
1d080 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 es.** associated
1d090 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 with the [datab
1d0a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
1d0b0 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 handle should be
1d0c0 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 released by.**
1d0d0 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 passing it to [s
1d0e0 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 qlite3_close()]
1d0f0 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f when it is no lo
1d100 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a nger required..*
1d110 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
1d120 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 _open_v2() inter
1d130 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 face works like
1d140 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a sqlite3_open().*
1d150 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 * except that it
1d160 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 accepts two add
1d170 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 itional paramete
1d180 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 rs for additiona
1d190 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 l control.** ove
1d1a0 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 r the new databa
1d1b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 se connection.
1d1c0 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 The flags parame
1d1d0 74 65 72 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 ter can take one
1d1e0 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f of.** the follo
1d1f0 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 wing three value
1d200 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f s, optionally co
1d210 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 mbined with the
1d220 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e .** [SQLITE_OPEN
1d230 5f 4e 4f 4d 55 54 45 58 5d 20 6f 72 20 5b 53 51 _NOMUTEX] or [SQ
1d240 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 LITE_OPEN_FULLMU
1d250 54 45 58 5d 20 66 6c 61 67 73 3a 0a 2a 2a 0a 2a TEX] flags:.**.*
1d260 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 5b 53 * <dl>.** <dt>[S
1d270 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
1d280 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 NLY]</dt>.** <dd
1d290 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 >The database is
1d2a0 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d opened in read-
1d2b0 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 only mode. If t
1d2c0 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 he database does
1d2d0 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 not.** already
1d2e0 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 exist, an error
1d2f0 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 is returned.</dd
1d300 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c >.**.** <dt>[SQL
1d310 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 ITE_OPEN_READWRI
1d320 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TE]</dt>.** <dd>
1d330 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 The database is
1d340 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 opened for readi
1d350 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 ng and writing i
1d360 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 f possible, or r
1d370 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 eading.** only i
1d380 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 f the file is wr
1d390 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 ite protected by
1d3a0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 the operating s
1d3b0 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 ystem. In eithe
1d3c0 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 r.** case the da
1d3d0 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 tabase must alre
1d3e0 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 ady exist, other
1d3f0 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 wise an error is
1d400 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a returned.</dd>.
1d410 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 **.** <dt>[SQLIT
1d420 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 E_OPEN_READWRITE
1d430 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e ] | [SQLITE_OPEN
1d440 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a _CREATE]</dt>.**
1d450 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 <dd>The databas
1d460 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 e is opened for
1d470 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 reading and writ
1d480 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 ing, and is crea
1d490 74 65 73 20 69 74 20 69 66 0a 2a 2a 20 69 74 20 tes it if.** it
1d4a0 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 does not already
1d4b0 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 exist. This is
1d4c0 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 the behavior tha
1d4d0 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 t is always used
1d4e0 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f for.** sqlite3_
1d4f0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 open() and sqlit
1d500 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 e3_open16().</dd
1d510 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a >.** </dl>.**.**
1d520 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 If the 3rd para
1d530 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
1d540 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f _open_v2() is no
1d550 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 t one of the.**
1d560 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f combinations sho
1d570 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20 wn above or one
1d580 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e 61 74 69 of the combinati
1d590 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 ons shown above
1d5a0 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68 combined.** with
1d5b0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 the [SQLITE_OPE
1d5c0 4e 5f 4e 4f 4d 55 54 45 58 5d 20 6f 72 20 5b 53 N_NOMUTEX] or [S
1d5d0 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d QLITE_OPEN_FULLM
1d5e0 55 54 45 58 5d 20 66 6c 61 67 73 2c 0a 2a 2a 20 UTEX] flags,.**
1d5f0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f then the behavio
1d600 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a r is undefined..
1d610 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53 51 **.** If the [SQ
1d620 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 LITE_OPEN_NOMUTE
1d630 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 X] flag is set,
1d640 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 then the databas
1d650 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
1d660 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c opens in the mul
1d670 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 ti-thread [threa
1d680 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f ding mode] as lo
1d690 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 ng as the single
1d6a0 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 -thread.** mode
1d6b0 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 has not been set
1d6c0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 at compile-time
1d6d0 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 or start-time.
1d6e0 20 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 If the.** [SQLI
1d6f0 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 TE_OPEN_FULLMUTE
1d700 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 X] flag is set t
1d710 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
1d720 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e connection open
1d730 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 s.** in the seri
1d740 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e alized [threadin
1d750 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 g mode] unless s
1d760 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 ingle-thread was
1d770 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 .** previously s
1d780 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 elected at compi
1d790 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 le-time or start
1d7a0 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 -time..**.** If
1d7b0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 the filename is
1d7c0 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e ":memory:", then
1d7d0 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 a private, temp
1d7e0 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 orary in-memory
1d7f0 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 database.** is c
1d800 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 reated for the c
1d810 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69 73 onnection. This
1d820 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 in-memory datab
1d830 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 ase will vanish
1d840 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 when.** the data
1d850 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
1d860 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 is closed. Futu
1d870 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 re versions of S
1d880 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d QLite might.** m
1d890 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 ake use of addit
1d8a0 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 ional special fi
1d8b0 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 lenames that beg
1d8c0 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 in with the ":"
1d8d0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 character..** It
1d8e0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
1d8f0 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 that when a data
1d900 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 base filename ac
1d910 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 tually does begi
1d920 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 n with.** a ":"
1d930 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 character you sh
1d940 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 ould prefix the
1d950 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 filename with a
1d960 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 pathname such as
1d970 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 .** "./" to avoi
1d980 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a d ambiguity..**.
1d990 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 ** If the filena
1d9a0 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 me is an empty s
1d9b0 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 tring, then a pr
1d9c0 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 ivate, temporary
1d9d0 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 .** on-disk data
1d9e0 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 base will be cre
1d9f0 61 74 65 64 2e 20 20 54 68 69 73 20 70 72 69 76 ated. This priv
1da00 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c ate database wil
1da10 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 l be.** automati
1da20 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 cally deleted as
1da30 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 soon as the dat
1da40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1da50 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a is closed..**.*
1da60 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 * The fourth par
1da70 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
1da80 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 3_open_v2() is t
1da90 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a he name of the.*
1daa0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 * [sqlite3_vfs]
1dab0 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 object that defi
1dac0 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e nes the operatin
1dad0 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 g system interfa
1dae0 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e ce that.** the n
1daf0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ew database conn
1db00 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 ection should us
1db10 65 2e 20 20 49 66 20 74 68 65 20 66 6f 75 72 74 e. If the fourt
1db20 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a h parameter is.*
1db30 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 * a NULL pointer
1db40 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c then the defaul
1db50 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 t [sqlite3_vfs]
1db60 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a object is used..
1db70 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f **.** <b>Note to
1db80 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c Windows users:<
1db90 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e /b> The encodin
1dba0 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 g used for the f
1dbb0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 ilename argument
1dbc0 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f .** of sqlite3_o
1dbd0 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 pen() and sqlite
1dbe0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 3_open_v2() must
1dbf0 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 be UTF-8, not w
1dc00 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 hatever.** codep
1dc10 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 age is currently
1dc20 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e defined. Filen
1dc30 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 ames containing
1dc40 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a international.**
1dc50 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 characters must
1dc60 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f be converted to
1dc70 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 UTF-8 prior to
1dc80 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 passing them int
1dc90 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 o.** sqlite3_ope
1dca0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f n() or sqlite3_o
1dcb0 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 pen_v2()..**.**
1dcc0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
1dcd0 2a 20 7b 48 31 32 37 30 31 7d 20 54 68 65 20 5b * {H12701} The [
1dce0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
1dcf0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
1dd00 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20 ()], and.**
1dd10 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 [sqlite3_op
1dd20 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 en_v2()] interfa
1dd30 63 65 73 20 63 72 65 61 74 65 20 61 20 6e 65 77 ces create a new
1dd40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 .** [da
1dd50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1dd60 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 n] associated wi
1dd70 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 th.** t
1dd80 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
1dd90 20 67 69 76 65 6e 20 69 6e 20 74 68 65 69 72 20 given in their
1dda0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e first parameter.
1ddb0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 32 7d 20 .**.** {H12702}
1ddc0 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 The filename arg
1ddd0 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 ument is interpr
1dde0 65 74 65 64 20 61 73 20 55 54 46 2d 38 0a 2a 2a eted as UTF-8.**
1ddf0 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 5b 73 for [s
1de00 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 qlite3_open()] a
1de10 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e nd [sqlite3_open
1de20 5f 76 32 28 29 5d 20 61 6e 64 20 61 73 20 55 54 _v2()] and as UT
1de30 46 2d 31 36 0a 2a 2a 20 20 20 20 20 20 20 20 20 F-16.**
1de40 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 in the native b
1de50 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 5b 73 yte order for [s
1de60 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
1de70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 33 7d ..**.** {H12703}
1de80 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e A successful in
1de90 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c vocation of [sql
1dea0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 ite3_open()], [s
1deb0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
1dec0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 ,.** or
1ded0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
1dee0 32 28 29 5d 20 77 72 69 74 65 73 20 61 20 70 6f 2()] writes a po
1def0 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a inter to a new.*
1df00 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 * [data
1df10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
1df20 20 69 6e 74 6f 20 2a 70 70 44 62 2e 0a 2a 2a 0a into *ppDb..**.
1df30 2a 2a 20 7b 48 31 32 37 30 34 7d 20 54 68 65 20 ** {H12704} The
1df40 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
1df50 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 , [sqlite3_open1
1df60 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 6()], and.**
1df70 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f [sqlite3_o
1df80 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 pen_v2()] interf
1df90 61 63 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c aces return [SQL
1dfa0 49 54 45 5f 4f 4b 5d 20 75 70 6f 6e 20 73 75 63 ITE_OK] upon suc
1dfb0 63 65 73 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20 cess,.**
1dfc0 20 20 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 or an appropri
1dfd0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d ate [error code]
1dfe0 20 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a on failure..**.
1dff0 2a 2a 20 7b 48 31 32 37 30 36 7d 20 54 68 65 20 ** {H12706} The
1e000 64 65 66 61 75 6c 74 20 74 65 78 74 20 65 6e 63 default text enc
1e010 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e 65 77 20 oding for a new
1e020 64 61 74 61 62 61 73 65 20 63 72 65 61 74 65 64 database created
1e030 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 using.**
1e040 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e [sqlite3_open
1e050 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
1e060 6f 70 65 6e 5f 76 32 28 29 5d 20 77 69 6c 6c 20 open_v2()] will
1e070 62 65 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 be UTF-8..**.**
1e080 7b 48 31 32 37 30 37 7d 20 54 68 65 20 64 65 66 {H12707} The def
1e090 61 75 6c 74 20 74 65 78 74 20 65 6e 63 6f 64 69 ault text encodi
1e0a0 6e 67 20 66 6f 72 20 61 20 6e 65 77 20 64 61 74 ng for a new dat
1e0b0 61 62 61 73 65 20 63 72 65 61 74 65 64 20 75 73 abase created us
1e0c0 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ing.**
1e0d0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 [sqlite3_open16(
1e0e0 29 5d 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 )] will be UTF-1
1e0f0 36 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 39 6..**.** {H12709
1e100 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f } The [sqlite3_o
1e110 70 65 6e 28 46 2c 44 29 5d 20 69 6e 74 65 72 66 pen(F,D)] interf
1e120 61 63 65 20 69 73 20 65 71 75 69 76 61 6c 65 6e ace is equivalen
1e130 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 t to.**
1e140 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
1e150 32 28 46 2c 44 2c 47 2c 30 29 5d 20 77 68 65 72 2(F,D,G,0)] wher
1e160 65 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 e the G paramete
1e170 72 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 r is.**
1e180 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 [SQLITE_OPEN_RE
1e190 41 44 57 52 49 54 45 5d 7c 5b 53 51 4c 49 54 45 ADWRITE]|[SQLITE
1e1a0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 0a 2a _OPEN_CREATE]..*
1e1b0 2a 0a 2a 2a 20 7b 48 31 32 37 31 31 7d 20 49 66 *.** {H12711} If
1e1c0 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 the G parameter
1e1d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 to [sqlite3_ope
1e1e0 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 n_v2(F,D,G,V)] c
1e1f0 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 ontains the.**
1e200 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 bit valu
1e210 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 e [SQLITE_OPEN_R
1e220 45 41 44 4f 4e 4c 59 5d 20 74 68 65 6e 20 74 68 EADONLY] then th
1e230 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 e database is op
1e240 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 ened.**
1e250 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c for reading onl
1e260 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 32 y..**.** {H12712
1e270 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d } If the G param
1e280 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 eter to [sqlite3
1e290 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 _open_v2(F,D,G,V
1e2a0 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a )] contains the.
1e2b0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20 ** bit
1e2c0 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 value [SQLITE_OP
1e2d0 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 74 68 EN_READWRITE] th
1e2e0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
1e2f0 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20 is opened.**
1e300 20 20 20 20 20 20 72 65 61 64 69 6e 67 20 61 6e reading an
1e310 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 d writing if pos
1e320 73 69 62 6c 65 2c 20 6f 72 20 66 6f 72 20 72 65 sible, or for re
1e330 61 64 69 6e 67 20 6f 6e 6c 79 20 69 66 20 74 68 ading only if th
1e340 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 e.** fi
1e350 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 le is write prot
1e360 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 ected by the ope
1e370 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 0a 2a rating system..*
1e380 2a 0a 2a 2a 20 7b 48 31 32 37 31 33 7d 20 49 66 *.** {H12713} If
1e390 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 the G parameter
1e3a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 to [sqlite3_ope
1e3b0 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 6f n_v2(F,D,G,V)] o
1e3c0 6d 69 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 mits the.**
1e3d0 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b bit value [
1e3e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 SQLITE_OPEN_CREA
1e3f0 54 45 5d 20 61 6e 64 20 74 68 65 20 64 61 74 61 TE] and the data
1e400 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a base does not.**
1e410 20 20 20 20 20 20 20 20 20 20 70 72 65 76 69 6f previo
1e420 75 73 6c 79 20 65 78 69 73 74 2c 20 61 6e 20 65 usly exist, an e
1e430 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 rror is returned
1e440 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 34 7d ..**.** {H12714}
1e450 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 If the G parame
1e460 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
1e470 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 open_v2(F,D,G,V)
1e480 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a ] contains the.*
1e490 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20 76 * bit v
1e4a0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 alue [SQLITE_OPE
1e4b0 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64 20 74 68 N_CREATE] and th
1e4c0 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 e database does
1e4d0 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 not.**
1e4e0 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73 74 previously exist
1e4f0 2c 20 74 68 65 6e 20 61 6e 20 61 74 74 65 6d 70 , then an attemp
1e500 74 20 69 73 20 6d 61 64 65 20 74 6f 20 63 72 65 t is made to cre
1e510 61 74 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 ate and.**
1e520 20 20 20 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 initialize t
1e530 68 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 0a he database..**.
1e540 2a 2a 20 7b 48 31 32 37 31 37 7d 20 49 66 20 74 ** {H12717} If t
1e550 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 he filename argu
1e560 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 ment to [sqlite3
1e570 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 _open()], [sqlit
1e580 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a e3_open16()],.**
1e590 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 or [sq
1e5a0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d lite3_open_v2()]
1e5b0 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 is ":memory:",
1e5c0 74 68 65 6e 20 61 6e 20 70 72 69 76 61 74 65 2c then an private,
1e5d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 70 68 .** eph
1e5e0 65 6d 65 72 61 6c 2c 20 69 6e 2d 6d 65 6d 6f 72 emeral, in-memor
1e5f0 79 20 64 61 74 61 62 61 73 65 20 69 73 20 63 72 y database is cr
1e600 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f eated for the co
1e610 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 20 20 20 20 nnection..**
1e620 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53 <todo>Is S
1e630 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
1e640 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 E|SQLITE_OPEN_RE
1e650 41 44 57 52 49 54 45 20 72 65 71 75 69 72 65 64 ADWRITE required
1e660 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 .** in
1e670 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
1e680 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 )?</todo>.**.**
1e690 7b 48 31 32 37 31 39 7d 20 49 66 20 74 68 65 20 {H12719} If the
1e6a0 66 69 6c 65 6e 61 6d 65 20 69 73 20 4e 55 4c 4c filename is NULL
1e6b0 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 or an empty str
1e6c0 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 ing, then a priv
1e6d0 61 74 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 ate,.**
1e6e0 20 65 70 68 65 6d 65 72 61 6c 20 6f 6e 2d 64 69 ephemeral on-di
1e6f0 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c sk database will
1e700 20 62 65 20 63 72 65 61 74 65 64 2e 0a 2a 2a 20 be created..**
1e710 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49 <todo>I
1e720 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 s SQLITE_OPEN_CR
1e730 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e EATE|SQLITE_OPEN
1e740 5f 52 45 41 44 57 52 49 54 45 20 72 65 71 75 69 _READWRITE requi
1e750 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 red.**
1e760 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f in sqlite3_open_
1e770 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a v2()?</todo>.**.
1e780 2a 2a 20 7b 48 31 32 37 32 31 7d 20 54 68 65 20 ** {H12721} The
1e790 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
1e7a0 74 69 6f 6e 5d 20 63 72 65 61 74 65 64 20 62 79 tion] created by
1e7b0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
1e7c0 32 28 46 2c 44 2c 47 2c 56 29 5d 0a 2a 2a 20 20 2(F,D,G,V)].**
1e7d0 20 20 20 20 20 20 20 20 77 69 6c 6c 20 75 73 65 will use
1e7e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 the [sqlite3_vf
1e7f0 73 5d 20 6f 62 6a 65 63 74 20 69 64 65 6e 74 69 s] object identi
1e800 66 69 65 64 20 62 79 20 74 68 65 20 56 20 70 61 fied by the V pa
1e810 72 61 6d 65 74 65 72 2c 0a 2a 2a 20 20 20 20 20 rameter,.**
1e820 20 20 20 20 20 6f 72 20 74 68 65 20 64 65 66 61 or the defa
1e830 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 ult [sqlite3_vfs
1e840 5d 20 6f 62 6a 65 63 74 20 69 66 20 56 20 69 73 ] object if V is
1e850 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
1e860 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 32 33 7d 20 .**.** {H12723}
1e870 54 77 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f Two [database co
1e880 6e 6e 65 63 74 69 6f 6e 73 5d 20 77 69 6c 6c 20 nnections] will
1e890 73 68 61 72 65 20 61 20 63 6f 6d 6d 6f 6e 20 63 share a common c
1e8a0 61 63 68 65 20 69 66 20 62 6f 74 68 20 77 65 72 ache if both wer
1e8b0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 70 e.** op
1e8c0 65 6e 65 64 20 77 69 74 68 20 74 68 65 20 73 61 ened with the sa
1e8d0 6d 65 20 56 46 53 20 77 68 69 6c 65 20 5b 73 68 me VFS while [sh
1e8e0 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d ared cache mode]
1e8f0 20 77 61 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 was enabled and
1e900 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 .** if
1e910 62 6f 74 68 20 66 69 6c 65 6e 61 6d 65 73 20 63 both filenames c
1e920 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 75 73 69 ompare equal usi
1e930 6e 67 20 6d 65 6d 63 6d 70 28 29 20 61 66 74 65 ng memcmp() afte
1e940 72 20 68 61 76 69 6e 67 20 62 65 65 6e 0a 2a 2a r having been.**
1e950 20 20 20 20 20 20 20 20 20 20 70 72 6f 63 65 73 proces
1e960 73 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 sed by the [sqli
1e970 74 65 33 5f 76 66 73 20 7c 20 78 46 75 6c 6c 50 te3_vfs | xFullP
1e980 61 74 68 6e 61 6d 65 5d 20 6d 65 74 68 6f 64 20 athname] method
1e990 6f 66 20 74 68 65 20 56 46 53 2e 0a 2a 2f 0a 69 of the VFS..*/.i
1e9a0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 nt sqlite3_open(
1e9b0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 . const char *f
1e9c0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 ilename, /* Da
1e9d0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 tabase filename
1e9e0 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c (UTF-8) */. sql
1e9f0 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 ite3 **ppDb
1ea00 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c /* OUT: SQL
1ea10 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f ite db handle */
1ea20 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .);.int sqlite3_
1ea30 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 open16(. const
1ea40 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 void *filename,
1ea50 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 /* Database fi
1ea60 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 lename (UTF-16)
1ea70 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 */. sqlite3 **p
1ea80 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 pDb /*
1ea90 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 OUT: SQLite db h
1eaa0 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 andle */.);.int
1eab0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
1eac0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 . const char *f
1ead0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 ilename, /* Da
1eae0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 tabase filename
1eaf0 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c (UTF-8) */. sql
1eb00 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 ite3 **ppDb,
1eb10 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c /* OUT: SQL
1eb20 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f ite db handle */
1eb30 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 . int flags,
1eb40 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c /* Fl
1eb50 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 ags */. const c
1eb60 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 har *zVfs
1eb70 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 /* Name of VFS
1eb80 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f module to use */
1eb90 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
1eba0 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 REF: Error Codes
1ebb0 20 41 6e 64 20 4d 65 73 73 61 67 65 73 20 7b 48 And Messages {H
1ebc0 31 32 38 30 30 7d 20 3c 53 36 30 32 30 30 3e 0a 12800} <S60200>.
1ebd0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
1ebe0 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 3_errcode() inte
1ebf0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 rface returns th
1ec00 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c e numeric [resul
1ec10 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 t code] or.** [e
1ec20 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
1ec30 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 ode] for the mos
1ec40 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 t recent failed
1ec50 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 sqlite3_* API ca
1ec60 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 ll.** associated
1ec70 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 with a [databas
1ec80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 e connection]. I
1ec90 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 f a prior API ca
1eca0 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 ll failed.** but
1ecb0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
1ecc0 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 API call succee
1ecd0 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 ded, the return
1ece0 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 value from.** sq
1ecf0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 lite3_errcode()
1ed00 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 54 is undefined. T
1ed10 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e he sqlite3_exten
1ed20 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a ded_errcode().**
1ed30 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 interface is th
1ed40 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 e same except th
1ed50 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 at it always ret
1ed60 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 urns the .** [ex
1ed70 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
1ed80 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 de] even when ex
1ed90 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
1eda0 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 des are.** disab
1edb0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 led..**.** The s
1edc0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 qlite3_errmsg()
1edd0 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d and sqlite3_errm
1ede0 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e sg16() return En
1edf0 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a glish-language.*
1ee00 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 * text that desc
1ee10 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c ribes the error,
1ee20 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 as either UTF-8
1ee30 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 or UTF-16 respe
1ee40 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f ctively..** Memo
1ee50 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 ry to hold the e
1ee60 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 rror message str
1ee70 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 ing is managed i
1ee80 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 nternally..** Th
1ee90 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f e application do
1eea0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 es not need to w
1eeb0 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 orry about freei
1eec0 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a ng the result..*
1eed0 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 * However, the e
1eee0 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 rror string migh
1eef0 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e t be overwritten
1ef00 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 or deallocated
1ef10 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 by.** subsequent
1ef20 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 calls to other
1ef30 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
1ef40 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a functions..**.*
1ef50 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 * When the seria
1ef60 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 lized [threading
1ef70 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 mode] is in use
1ef80 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 , it might be th
1ef90 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 e.** case that a
1efa0 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 second error oc
1efb0 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 curs on a separa
1efc0 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 te thread in bet
1efd0 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 ween.** the time
1efe0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 of the first er
1eff0 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c ror and the call
1f000 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 to these interf
1f010 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 aces..** When th
1f020 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 at happens, the
1f030 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c second error wil
1f040 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 l be reported si
1f050 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 nce these.** int
1f060 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 erfaces always r
1f070 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 eport the most r
1f080 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 ecent result. T
1f090 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c o avoid.** this,
1f0a0 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e each thread can
1f0b0 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 obtain exclusiv
1f0c0 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 e use of the [da
1f0d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1f0e0 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b n] D.** by invok
1f0f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 ing [sqlite3_mut
1f100 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 ex_enter]([sqlit
1f110 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 e3_db_mutex](D))
1f120 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e before beginnin
1f130 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e g.** to use D an
1f140 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 d invoking [sqli
1f150 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d te3_mutex_leave]
1f160 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 ([sqlite3_db_mut
1f170 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a ex](D)) after.**
1f180 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 all calls to th
1f190 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 e interfaces lis
1f1a0 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d ted here are com
1f1b0 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 pleted..**.** If
1f1c0 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 an interface fa
1f1d0 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f ils with SQLITE_
1f1e0 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 MISUSE, that mea
1f1f0 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 ns the interface
1f200 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 .** was invoked
1f210 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 incorrectly by t
1f220 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 he application.
1f230 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 In that case, t
1f240 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 he.** error code
1f250 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 and message may
1f260 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 or may not be s
1f270 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 et..**.** INVARI
1f280 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 ANTS:.**.** {H12
1f290 38 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 801} The [sqlite
1f2a0 33 5f 65 72 72 63 6f 64 65 28 44 29 5d 20 69 6e 3_errcode(D)] in
1f2b0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
1f2c0 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 20 the numeric.**
1f2d0 20 20 20 20 20 20 20 20 5b 72 65 73 75 6c 74 20 [result
1f2e0 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 code] or [extend
1f2f0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 ed result code]
1f300 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 for the most rec
1f310 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 ently.**
1f320 20 20 66 61 69 6c 65 64 20 69 6e 74 65 72 66 61 failed interfa
1f330 63 65 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 ce call associat
1f340 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 ed with the [dat
1f350 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1f360 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 ] D..**.** {H128
1f370 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 02} The [sqlite3
1f380 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 _extended_errcod
1f390 65 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 e(D)] interface
1f3a0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 returns the nume
1f3b0 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ric.**
1f3c0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
1f3d0 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d code] for the m
1f3e0 6f 73 74 20 72 65 63 65 6e 74 6c 79 0a 2a 2a 20 ost recently.**
1f3f0 20 20 20 20 20 20 20 20 20 66 61 69 6c 65 64 20 failed
1f400 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 61 interface call a
1f410 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
1f420 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
1f430 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a nection] D..**.*
1f440 2a 20 7b 48 31 32 38 30 33 7d 20 54 68 65 20 5b * {H12803} The [
1f450 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 44 sqlite3_errmsg(D
1f460 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
1f470 65 72 72 6d 73 67 31 36 28 44 29 5d 0a 2a 2a 20 errmsg16(D)].**
1f480 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 interfa
1f490 63 65 73 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 ces return Engli
1f4a0 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 sh-language text
1f4b0 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 0a that describes.
1f4c0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
1f4d0 65 72 72 6f 72 20 69 6e 20 74 68 65 20 6d 6f 73 error in the mos
1f4e0 74 6c 79 20 72 65 63 65 6e 74 6c 79 20 66 61 69 tly recently fai
1f4f0 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20 63 61 led interface ca
1f500 6c 6c 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ll,.**
1f510 65 6e 63 6f 64 65 64 20 61 73 20 65 69 74 68 65 encoded as eithe
1f520 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 r UTF-8 or UTF-1
1f530 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 6 respectively..
1f540 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 37 7d 20 54 **.** {H12807} T
1f550 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 he strings retur
1f560 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ned by [sqlite3_
1f570 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20 5b 73 errmsg()] and [s
1f580 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 qlite3_errmsg16(
1f590 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 )].** a
1f5a0 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 re valid until t
1f5b0 68 65 20 6e 65 78 74 20 53 51 4c 69 74 65 20 69 he next SQLite i
1f5c0 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 2e 0a 2a nterface call..*
1f5d0 2a 0a 2a 2a 20 7b 48 31 32 38 30 38 7d 20 43 61 *.** {H12808} Ca
1f5e0 6c 6c 73 20 74 6f 20 41 50 49 20 72 6f 75 74 69 lls to API routi
1f5f0 6e 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 nes that do not
1f600 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 20 return an error
1f610 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 code.**
1f620 20 28 65 78 61 6d 70 6c 65 3a 20 5b 73 71 6c 69 (example: [sqli
1f630 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 te3_data_count()
1f640 5d 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20 20 20 20 ]) do not.**
1f650 20 20 20 20 20 20 63 68 61 6e 67 65 20 74 68 65 change the
1f660 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 72 20 6d error code or m
1f670 65 73 73 61 67 65 20 72 65 74 75 72 6e 65 64 20 essage returned
1f680 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b by.** [
1f690 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
1f6a0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 )], [sqlite3_ext
1f6b0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d ended_errcode()]
1f6c0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 ,.** [s
1f6d0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d qlite3_errmsg()]
1f6e0 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 , or [sqlite3_er
1f6f0 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a rmsg16()]..**.**
1f700 20 7b 48 31 32 38 30 39 7d 20 49 6e 74 65 72 66 {H12809} Interf
1f710 61 63 65 73 20 74 68 61 74 20 61 72 65 20 6e 6f aces that are no
1f720 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 t associated wit
1f730 68 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 h a specific.**
1f740 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 [databa
1f750 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 se connection] (
1f760 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20 20 20 20 examples:.**
1f770 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d [sqlite3_m
1f780 70 72 69 6e 74 66 28 29 5d 20 6f 72 20 5b 73 71 printf()] or [sq
1f790 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 lite3_enable_sha
1f7a0 72 65 64 5f 63 61 63 68 65 28 29 5d 0a 2a 2a 20 red_cache()].**
1f7b0 20 20 20 20 20 20 20 20 20 64 6f 20 6e 6f 74 20 do not
1f7c0 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 change the value
1f7d0 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a s returned by.**
1f7e0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
1f7f0 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b e3_errcode()], [
1f800 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
1f810 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 _errcode()],.**
1f820 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
1f830 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20 3_errmsg()], or
1f840 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 [sqlite3_errmsg1
1f850 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 6()]..*/.int sql
1f860 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c ite3_errcode(sql
1f870 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 ite3 *db);.int s
1f880 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f qlite3_extended_
1f890 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 errcode(sqlite3
1f8a0 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 *db);.const char
1f8b0 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 *sqlite3_errmsg
1f8c0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 (sqlite3*);.cons
1f8d0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
1f8e0 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 errmsg16(sqlite3
1f8f0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
1f900 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 REF: SQL Stateme
1f910 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 30 30 nt Object {H1300
1f920 30 7d 20 3c 48 31 33 30 31 30 3e 0a 2a 2a 20 4b 0} <H13010>.** K
1f930 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 EYWORDS: {prepar
1f940 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 ed statement} {p
1f950 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
1f960 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 ts}.**.** An ins
1f970 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 tance of this ob
1f980 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 ject represents
1f990 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 a single SQL sta
1f9a0 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 tement..** This
1f9b0 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 object is variou
1f9c0 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 sly known as a "
1f9d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1f9e0 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d nt" or a.** "com
1f9f0 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d piled SQL statem
1fa00 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 ent" or simply a
1fa10 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e s a "statement".
1fa20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 .**.** The life
1fa30 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f of a statement o
1fa40 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 bject goes somet
1fa50 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a hing like this:.
1fa60 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c **.** <ol>.** <l
1fa70 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 i> Create the ob
1fa80 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 ject using [sqli
1fa90 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
1faa0 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a ] or a related.*
1fab0 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e * function.
1fac0 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 .** <li> Bind va
1fad0 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 lues to [host pa
1fae0 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 rameters] using
1faf0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 the sqlite3_bind
1fb00 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 _*().** int
1fb10 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e erfaces..** <li>
1fb20 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 Run the SQL by
1fb30 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 calling [sqlite3
1fb40 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 _step()] one or
1fb50 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c more times..** <
1fb60 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 li> Reset the st
1fb70 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 atement using [s
1fb80 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
1fb90 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 then go back.**
1fba0 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 to step 2.
1fbb0 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 Do this zero or
1fbc0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 more times..**
1fbd0 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 <li> Destroy the
1fbe0 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 object using [s
1fbf0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
1fc00 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a )]..** </ol>.**.
1fc10 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 ** Refer to docu
1fc20 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 mentation on ind
1fc30 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 ividual methods
1fc40 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 above for additi
1fc50 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 onal.** informat
1fc60 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ion..*/.typedef
1fc70 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 struct sqlite3_s
1fc80 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 tmt sqlite3_stmt
1fc90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1fca0 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 F: Run-time Limi
1fcb0 74 73 20 7b 48 31 32 37 36 30 7d 20 3c 53 32 30 ts {H12760} <S20
1fcc0 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 600>.**.** This
1fcd0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 interface allows
1fce0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 the size of var
1fcf0 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 ious constructs
1fd00 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a to be limited.**
1fd10 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e on a connection
1fd20 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 by connection b
1fd30 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 asis. The first
1fd40 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
1fd50 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 e.** [database c
1fd60 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 onnection] whose
1fd70 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 limit is to be
1fd80 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 set or queried.
1fd90 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 The.** second p
1fda0 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 arameter is one
1fdb0 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 of the [limit ca
1fdc0 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 tegories] that d
1fdd0 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 efine a.** class
1fde0 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 of constructs t
1fdf0 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 o be size limite
1fe00 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 d. The third pa
1fe10 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a rameter is the.*
1fe20 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 * new limit for
1fe30 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 20 that construct.
1fe40 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 The function re
1fe50 74 75 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c 69 turns the old li
1fe60 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 mit..**.** If th
1fe70 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 e new limit is a
1fe80 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 negative number
1fe90 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 , the limit is u
1fea0 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 46 6f 72 nchanged..** For
1feb0 20 74 68 65 20 6c 69 6d 69 74 20 63 61 74 65 67 the limit categ
1fec0 6f 72 79 20 6f 66 20 53 51 4c 49 54 45 5f 4c 49 ory of SQLITE_LI
1fed0 4d 49 54 5f 58 59 5a 20 74 68 65 72 65 20 69 73 MIT_XYZ there is
1fee0 20 61 20 68 61 72 64 20 75 70 70 65 72 0a 2a 2a a hard upper.**
1fef0 20 62 6f 75 6e 64 20 73 65 74 20 62 79 20 61 20 bound set by a
1ff00 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43 20 70 compile-time C p
1ff10 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 reprocessor macr
1ff20 6f 20 6e 61 6d 65 64 20 53 51 4c 49 54 45 5f 4d o named SQLITE_M
1ff30 41 58 5f 58 59 5a 2e 0a 2a 2a 20 28 54 68 65 20 AX_XYZ..** (The
1ff40 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 "_LIMIT_" in the
1ff50 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 name is changed
1ff60 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a 2a to "_MAX_".).**
1ff70 20 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 Attempts to inc
1ff80 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 rease a limit ab
1ff90 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70 ove its hard upp
1ffa0 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 er bound are.**
1ffb0 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 silently truncat
1ffc0 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 ed to the hard u
1ffd0 70 70 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a pper limit..**.*
1ffe0 2a 20 52 75 6e 20 74 69 6d 65 20 6c 69 6d 69 74 * Run time limit
1fff0 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 s are intended f
20000 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 or use in applic
20010 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 ations that mana
20020 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 ge.** both their
20030 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 own internal da
20040 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 tabase and also
20050 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 databases that a
20060 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a re controlled.**
20070 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 by untrusted ex
20080 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 ternal sources.
20090 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c An example appl
200a0 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 ication might be
200b0 20 61 0a 2a 2a 20 77 65 62 62 72 6f 77 73 65 72 a.** webbrowser
200c0 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 that has its ow
200d0 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 n databases for
200e0 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 storing history
200f0 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 and.** separate
20100 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f databases contro
20110 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 lled by JavaScri
20120 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 pt applications
20130 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 downloaded.** of
20140 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 f the Internet.
20150 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 The internal da
20160 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 tabases can be g
20170 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 iven the.** larg
20180 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 e, default limit
20190 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 s. Databases ma
201a0 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 naged by externa
201b0 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a l sources can.**
201c0 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 be given much s
201d0 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 maller limits de
201e0 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e signed to preven
201f0 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 t a denial of se
20200 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e rvice.** attack.
20210 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 Developers mig
20220 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 ht also want to
20230 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 use the [sqlite3
20240 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 _set_authorizer(
20250 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 )].** interface
20260 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 to further contr
20270 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c ol untrusted SQL
20280 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 . The size of t
20290 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 he database.** c
202a0 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 reated by an unt
202b0 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61 rusted script ca
202c0 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 n be contained u
202d0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 sing the.** [max
202e0 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 _page_count] [PR
202f0 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 AGMA]..**.** New
20300 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 run-time limit
20310 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 categories may b
20320 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
20330 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a e releases..**.*
20340 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
20350 0a 2a 2a 20 7b 48 31 32 37 36 32 7d 20 41 20 73 .** {H12762} A s
20360 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 uccessful call t
20370 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 o [sqlite3_limit
20380 28 44 2c 43 2c 56 29 5d 20 77 68 65 72 65 20 56 (D,C,V)] where V
20390 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 is.**
203a0 70 6f 73 69 74 69 76 65 20 63 68 61 6e 67 65 73 positive changes
203b0 20 74 68 65 20 6c 69 6d 69 74 20 6f 6e 20 74 68 the limit on th
203c0 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72 e size of constr
203d0 75 63 74 20 43 20 69 6e 20 74 68 65 0a 2a 2a 20 uct C in the.**
203e0 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 [databa
203f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
20400 20 74 6f 20 74 68 65 20 6c 65 73 73 65 72 20 6f to the lesser o
20410 66 20 56 20 61 6e 64 20 74 68 65 20 68 61 72 64 f V and the hard
20420 20 75 70 70 65 72 0a 2a 2a 20 20 20 20 20 20 20 upper.**
20430 20 20 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 bound on the
20440 73 69 7a 65 20 6f 66 20 43 20 74 68 61 74 20 69 size of C that i
20450 73 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 s set at compile
20460 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 -time..**.** {H1
20470 32 37 36 36 7d 20 41 20 73 75 63 63 65 73 73 66 2766} A successf
20480 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 ul call to [sqli
20490 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 te3_limit(D,C,V)
204a0 5d 20 77 68 65 72 65 20 56 20 69 73 20 6e 65 67 ] where V is neg
204b0 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 ative.**
204c0 20 20 6c 65 61 76 65 73 20 74 68 65 20 73 74 61 leaves the sta
204d0 74 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 te of the [datab
204e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
204f0 44 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a D unchanged..**.
20500 2a 2a 20 7b 48 31 32 37 36 39 7d 20 41 20 73 75 ** {H12769} A su
20510 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f ccessful call to
20520 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 [sqlite3_limit(
20530 44 2c 43 2c 56 29 5d 20 72 65 74 75 72 6e 73 20 D,C,V)] returns
20540 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
20550 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d value of the lim
20560 69 74 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f it on the size o
20570 66 20 63 6f 6e 73 74 72 75 63 74 20 43 20 69 6e f construct C in
20580 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
20590 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
205a0 63 74 69 6f 6e 5d 20 44 20 61 73 20 69 74 20 77 ction] D as it w
205b0 61 73 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 as prior to the
205c0 63 61 6c 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c call..*/.int sql
205d0 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 ite3_limit(sqlit
205e0 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 e3*, int id, int
205f0 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a newVal);../*.**
20600 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 CAPI3REF: Run-T
20610 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f ime Limit Catego
20620 72 69 65 73 20 7b 48 31 32 37 39 30 7d 20 3c 48 ries {H12790} <H
20630 31 32 37 36 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 12760>.** KEYWOR
20640 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 DS: {limit categ
20650 6f 72 79 7d 20 7b 6c 69 6d 69 74 20 63 61 74 65 ory} {limit cate
20660 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 gories}.**.** Th
20670 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 ese constants de
20680 66 69 6e 65 20 76 61 72 69 6f 75 73 20 61 73 70 fine various asp
20690 65 63 74 73 20 6f 66 20 61 20 5b 64 61 74 61 62 ects of a [datab
206a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a ase connection].
206b0 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c ** that can be l
206c0 69 6d 69 74 65 64 20 69 6e 20 73 69 7a 65 20 62 imited in size b
206d0 79 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 y calls to [sqli
206e0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a te3_limit()]..**
206f0 20 54 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 The meanings of
20700 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d the various lim
20710 69 74 73 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f its are as follo
20720 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a ws:.**.** <dl>.*
20730 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d * <dt>SQLITE_LIM
20740 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a IT_LENGTH</dt>.*
20750 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
20760 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 m size of any st
20770 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 ring or BLOB or
20780 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a table row.<dd>.*
20790 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
207a0 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 LIMIT_SQL_LENGTH
207b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
207c0 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 maximum length
207d0 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d of an SQL statem
207e0 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ent.</dd>.**.**
207f0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
20800 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 _COLUMN</dt>.**
20810 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
20820 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e number of column
20830 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 s in a table def
20840 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 inition or in th
20850 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 e.** result set
20860 6f 66 20 61 20 53 45 4c 45 43 54 20 6f 72 20 74 of a SELECT or t
20870 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
20880 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 r of columns in
20890 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 an index.** or i
208a0 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 n an ORDER BY or
208b0 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 GROUP BY clause
208c0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
208d0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 >SQLITE_LIMIT_EX
208e0 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a PR_DEPTH</dt>.**
208f0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
20900 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 depth of the pa
20910 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 rse tree on any
20920 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e expression.</dd>
20930 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
20940 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 E_LIMIT_COMPOUND
20950 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 _SELECT</dt>.**
20960 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
20970 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 number of terms
20980 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 in a compound SE
20990 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c LECT statement.<
209a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
209b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 QLITE_LIMIT_VDBE
209c0 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e _OP</dt>.** <dd>
209d0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
209e0 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f er of instructio
209f0 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 ns in a virtual
20a00 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a machine program.
20a10 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 ** used to imple
20a20 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 ment an SQL stat
20a30 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a ement.</dd>.**.*
20a40 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d * <dt>SQLITE_LIM
20a50 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c IT_FUNCTION_ARG<
20a60 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
20a70 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
20a80 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 f arguments on a
20a90 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a function.</dd>.
20aa0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
20ab0 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c _LIMIT_ATTACHED<
20ac0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
20ad0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
20ae0 66 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 f attached datab
20af0 61 73 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ases.</dd>.**.**
20b00 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 <dt>SQLITE_LIMI
20b10 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c T_LIKE_PATTERN_L
20b20 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ENGTH</dt>.** <d
20b30 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 d>The maximum le
20b40 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 ngth of the patt
20b50 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ern argument to
20b60 74 68 65 20 4c 49 4b 45 20 6f 72 0a 2a 2a 20 47 the LIKE or.** G
20b70 4c 4f 42 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f LOB operators.</
20b80 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
20b90 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 LITE_LIMIT_VARIA
20ba0 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a BLE_NUMBER</dt>.
20bb0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
20bc0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 72 um number of var
20bd0 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c iables in an SQL
20be0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 statement that
20bf0 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e can.** be bound.
20c00 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a </dd>.** </dl>.*
20c10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
20c20 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 _LIMIT_LENGTH
20c30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
20c40 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 0.#define SQLIT
20c50 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 E_LIMIT_SQL_LENG
20c60 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TH
20c70 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 1.#define SQLI
20c80 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 TE_LIMIT_COLUMN
20c90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
20ca0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 2.#define SQL
20cb0 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 ITE_LIMIT_EXPR_D
20cc0 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 EPTH
20cd0 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 3.#define SQ
20ce0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f LITE_LIMIT_COMPO
20cf0 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 UND_SELECT
20d00 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 4.#define S
20d10 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 QLITE_LIMIT_VDBE
20d20 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 _OP
20d30 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 5.#define
20d40 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e SQLITE_LIMIT_FUN
20d50 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 CTION_ARG
20d60 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 6.#define
20d70 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 SQLITE_LIMIT_AT
20d80 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 TACHED
20d90 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 7.#defin
20da0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c e SQLITE_LIMIT_L
20db0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 IKE_PATTERN_LENG
20dc0 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 TH 8.#defi
20dd0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
20de0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 VARIABLE_NUMBER
20df0 20 20 20 20 20 20 20 20 20 20 39 0a 0a 2f 2a 0a 9../*.
20e00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d ** CAPI3REF: Com
20e10 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 piling An SQL St
20e20 61 74 65 6d 65 6e 74 20 7b 48 31 33 30 31 30 7d atement {H13010}
20e30 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 20 4b 45 59 <S10000>.** KEY
20e40 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 WORDS: {SQL stat
20e50 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a ement compiler}.
20e60 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 **.** To execute
20e70 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 an SQL query, i
20e80 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 t must first be
20e90 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 compiled into a
20ea0 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f byte-code.** pro
20eb0 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f gram using one o
20ec0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
20ed0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 ..**.** The firs
20ee0 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 t argument, "db"
20ef0 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 , is a [database
20f00 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 connection] obt
20f10 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 ained from a.**
20f20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 5b 73 prior call to [s
20f30 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 qlite3_open()],
20f40 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
20f50 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
20f60 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a open16()]..**.**
20f70 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 The second argu
20f80 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 ment, "zSql", is
20f90 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 the statement t
20fa0 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 o be compiled, e
20fb0 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 ncoded.** as eit
20fc0 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 her UTF-8 or UTF
20fd0 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 -16. The sqlite
20fe0 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 3_prepare() and
20ff0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
21000 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 v2().** interfac
21010 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e es use UTF-8, an
21020 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 d sqlite3_prepar
21030 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 e16() and sqlite
21040 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
21050 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a .** use UTF-16..
21060 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42 79 **.** If the nBy
21070 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c te argument is l
21080 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 ess than zero, t
21090 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 hen zSql is read
210a0 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 up to the.** fi
210b0 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 rst zero termina
210c0 74 6f 72 2e 20 49 66 20 6e 42 79 74 65 20 69 73 tor. If nByte is
210d0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 non-negative, t
210e0 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 hen it is the ma
210f0 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 ximum.** number
21100 6f 66 20 20 62 79 74 65 73 20 72 65 61 64 20 66 of bytes read f
21110 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20 rom zSql. When
21120 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 nByte is non-neg
21130 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 ative, the.** zS
21140 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 ql string ends a
21150 74 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72 t either the fir
21160 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 st '\000' or '\u
21170 30 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20 0000' character
21180 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d or.** the nByte-
21190 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 th byte, whichev
211a0 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 er comes first.
211b0 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e If the caller kn
211c0 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 ows.** that the
211d0 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 supplied string
211e0 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 is nul-terminate
211f0 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 d, then there is
21200 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 a small.** perf
21210 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 ormance advantag
21220 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 e to be gained b
21230 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 y passing an nBy
21240 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 te parameter tha
21250 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f t.** is equal to
21260 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
21270 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 ytes in the inpu
21280 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c t string <i>incl
21290 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 uding</i>.** the
212a0 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 nul-terminator
212b0 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 2a 70 7a bytes..**.** *pz
212c0 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 Tail is made to
212d0 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 point to the fir
212e0 73 74 20 62 79 74 65 20 70 61 73 74 20 74 68 65 st byte past the
212f0 20 65 6e 64 20 6f 66 20 74 68 65 0a 2a 2a 20 66 end of the.** f
21300 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 irst SQL stateme
21310 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 nt in zSql. The
21320 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 se routines only
21330 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 compile the fir
21340 73 74 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 st.** statement
21350 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 in zSql, so *pzT
21360 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e ail is left poin
21370 74 69 6e 67 20 74 6f 20 77 68 61 74 20 72 65 6d ting to what rem
21380 61 69 6e 73 0a 2a 2a 20 75 6e 63 6f 6d 70 69 6c ains.** uncompil
21390 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d ed..**.** *ppStm
213a0 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 t is left pointi
213b0 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 ng to a compiled
213c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
213d0 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 ment] that can b
213e0 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 e.** executed us
213f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 ing [sqlite3_ste
21400 70 28 29 5d 2e 20 20 49 66 20 74 68 65 72 65 20 p()]. If there
21410 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 is an error, *pp
21420 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 Stmt is set.** t
21430 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 o NULL. If the
21440 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 input text conta
21450 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 ins no SQL (if t
21460 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 he input is an e
21470 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f mpty.** string o
21480 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 r a comment) the
21490 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 n *ppStmt is set
214a0 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b 41 31 to NULL..** {A1
214b0 33 30 31 38 7d 20 54 68 65 20 63 61 6c 6c 69 6e 3018} The callin
214c0 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 g procedure is r
214d0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 esponsible for d
214e0 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 eleting the comp
214f0 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 iled.** SQL stat
21500 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c ement using [sql
21510 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
21520 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 after it has fi
21530 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a nished with it..
21540 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 **.** On success
21550 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 , [SQLITE_OK] is
21560 20 72 65 74 75 72 6e 65 64 2c 20 6f 74 68 65 72 returned, other
21570 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 wise an [error c
21580 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 ode] is returned
21590 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
215a0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
215b0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 and sqlite3_pre
215c0 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 pare16_v2() inte
215d0 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 rfaces are.** re
215e0 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c commended for al
215f0 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 l new programs.
21600 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e The two older in
21610 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 terfaces are ret
21620 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 ained.** for bac
21630 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 kwards compatibi
21640 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 lity, but their
21650 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 use is discourag
21660 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76 ed..** In the "v
21670 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 2" interfaces, t
21680 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 he prepared stat
21690 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 ement.** that is
216a0 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b returned (the [
216b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 sqlite3_stmt] ob
216c0 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 ject) contains a
216d0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 copy of the.**
216e0 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 original SQL tex
216f0 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 t. This causes t
21700 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 he [sqlite3_step
21710 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f ()] interface to
21720 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 64 69 66 .** behave a dif
21730 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20 ferently in two
21740 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e ways:.**.** <ol>
21750 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 .** <li>.** If t
21760 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 he database sche
21770 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 ma changes, inst
21780 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 ead of returning
21790 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d [SQLITE_SCHEMA]
217a0 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 as it.** always
217b0 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 used to do, [sq
217c0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 lite3_step()] wi
217d0 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ll automatically
217e0 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 recompile the S
217f0 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 QL.** statement
21800 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 and try to run i
21810 74 20 61 67 61 69 6e 2e 20 20 49 66 20 74 68 65 t again. If the
21820 20 73 63 68 65 6d 61 20 68 61 73 20 63 68 61 6e schema has chan
21830 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20 ged in.** a way
21840 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 20 73 that makes the s
21850 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 tatement no long
21860 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 er valid, [sqlit
21870 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 e3_step()] will
21880 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 still.** return
21890 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e [SQLITE_SCHEMA].
218a0 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 But unlike the
218b0 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 legacy behavior
218c0 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 , [SQLITE_SCHEMA
218d0 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 ] is.** now a fa
218e0 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c tal error. Call
218f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 ing [sqlite3_pre
21900 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e pare_v2()] again
21910 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 will not make t
21920 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 he.** error go a
21930 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 way. Note: use
21940 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 [sqlite3_errmsg(
21950 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 )] to find the t
21960 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 ext.** of the pa
21970 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74 rsing error that
21980 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b results in an [
21990 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 SQLITE_SCHEMA] r
219a0 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a eturn..** </li>.
219b0 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 **.** <li>.** Wh
219c0 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 en an error occu
219d0 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 rs, [sqlite3_ste
219e0 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e p()] will return
219f0 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 one of the deta
21a00 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 iled.** [error c
21a10 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 odes] or [extend
21a20 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e ed error codes].
21a30 20 20 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 The legacy beh
21a40 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a avior was that.*
21a50 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 * [sqlite3_step(
21a60 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 )] would only re
21a70 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b turn a generic [
21a80 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 SQLITE_ERROR] re
21a90 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 sult code.** and
21aa0 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20 you would have
21ab0 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 to make a second
21ac0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
21ad0 33 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 6f 72 3_reset()] in or
21ae0 64 65 72 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 der.** to find t
21af0 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 he underlying ca
21b00 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c use of the probl
21b10 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 em. With the "v2
21b20 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 " prepare.** int
21b30 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 erfaces, the und
21b40 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 erlying reason f
21b50 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 or the error is
21b60 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 returned immedia
21b70 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a tely..** </li>.*
21b80 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e * </ol>.**.** IN
21b90 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
21ba0 7b 48 31 33 30 31 31 7d 20 54 68 65 20 5b 73 71 {H13011} The [sq
21bb0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 64 62 lite3_prepare(db
21bc0 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a ,zSql,...)] and.
21bd0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
21be0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
21bf0 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e db,zSql,...)] in
21c00 74 65 72 66 61 63 65 73 20 69 6e 74 65 72 70 72 terfaces interpr
21c10 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 et the.**
21c20 20 20 20 74 65 78 74 20 69 6e 20 74 68 65 69 72 text in their
21c30 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 72 20 zSql parameter
21c40 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 as UTF-8..**.**
21c50 7b 48 31 33 30 31 32 7d 20 54 68 65 20 5b 73 71 {H13012} The [sq
21c60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
21c70 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e db,zSql,...)] an
21c80 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 d.** [s
21c90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
21ca0 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 _v2(db,zSql,...)
21cb0 5d 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e 74 ] interfaces int
21cc0 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 20 20 erpret the.**
21cd0 20 20 20 20 20 20 20 74 65 78 74 20 69 6e 20 74 text in t
21ce0 68 65 69 72 20 7a 53 71 6c 20 70 61 72 61 6d 65 heir zSql parame
21cf0 74 65 72 20 61 73 20 55 54 46 2d 31 36 20 69 6e ter as UTF-16 in
21d00 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 the native byte
21d10 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 order..**.** {H
21d20 31 33 30 31 33 7d 20 49 66 20 74 68 65 20 6e 42 13013} If the nB
21d30 79 74 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 yte argument to
21d40 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
21d50 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 _v2(db,zSql,nByt
21d60 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 e,...)].**
21d70 20 20 20 20 61 6e 64 20 69 74 73 20 76 61 72 69 and its vari
21d80 61 6e 74 73 20 69 73 20 6c 65 73 73 20 74 68 61 ants is less tha
21d90 6e 20 7a 65 72 6f 2c 20 74 68 65 20 53 51 4c 20 n zero, the SQL
21da0 74 65 78 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 text is.**
21db0 20 20 20 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 read from zS
21dc0 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f ql is read up to
21dd0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 the first zero
21de0 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a terminator..**.*
21df0 2a 20 7b 48 31 33 30 31 34 7d 20 49 66 20 74 68 * {H13014} If th
21e00 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 e nByte argument
21e10 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 to [sqlite3_pre
21e20 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c pare_v2(db,zSql,
21e30 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 nByte,...)].**
21e40 20 20 20 20 20 20 20 20 61 6e 64 20 69 74 73 20 and its
21e50 76 61 72 69 61 6e 74 73 20 69 73 20 6e 6f 6e 2d variants is non-
21e60 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 negative, then a
21e70 74 20 6d 6f 73 74 20 6e 42 79 74 65 73 20 62 79 t most nBytes by
21e80 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 tes of.**
21e90 20 20 20 53 51 4c 20 74 65 78 74 20 69 73 20 72 SQL text is r
21ea0 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 0a 2a ead from zSql..*
21eb0 2a 0a 2a 2a 20 7b 48 31 33 30 31 35 7d 20 49 6e *.** {H13015} In
21ec0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
21ed0 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 50 e_v2(db,zSql,N,P
21ee0 2c 70 7a 54 61 69 6c 29 5d 20 61 6e 64 20 69 74 ,pzTail)] and it
21ef0 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a 20 20 20 s variants.**
21f00 20 20 20 20 20 20 20 69 66 20 74 68 65 20 7a 53 if the zS
21f10 71 6c 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f ql input text co
21f20 6e 74 61 69 6e 73 20 6d 6f 72 65 20 74 68 61 6e ntains more than
21f30 20 6f 6e 65 20 53 51 4c 20 73 74 61 74 65 6d 65 one SQL stateme
21f40 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 nt.** a
21f50 6e 64 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 nd pzTail is not
21f60 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 2a 70 7a 54 NULL, then *pzT
21f70 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 ail is made to p
21f80 6f 69 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20 oint to the.**
21f90 20 20 20 20 20 20 20 20 66 69 72 73 74 20 62 79 first by
21fa0 74 65 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 te past the end
21fb0 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c of the first SQL
21fc0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 statement in zS
21fd0 71 6c 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ql..**
21fe0 3c 74 6f 64 6f 3e 57 68 61 74 20 64 6f 65 73 20 <todo>What does
21ff0 2a 70 7a 54 61 69 6c 20 70 6f 69 6e 74 20 74 6f *pzTail point to
22000 20 69 66 20 74 68 65 72 65 20 69 73 20 6f 6e 65 if there is one
22010 20 73 74 61 74 65 6d 65 6e 74 3f 3c 2f 74 6f 64 statement?</tod
22020 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 36 o>.**.** {H13016
22030 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 } A successful c
22040 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
22050 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 prepare_v2(db,zS
22060 71 6c 2c 4e 2c 70 70 53 74 6d 74 2c 2e 2e 2e 29 ql,N,ppStmt,...)
22070 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 ].** or
22080 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 one of its vari
22090 61 6e 74 73 20 77 72 69 74 65 73 20 69 6e 74 6f ants writes into
220a0 20 2a 70 70 53 74 6d 74 20 61 20 70 6f 69 6e 74 *ppStmt a point
220b0 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 er to a new.**
220c0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 [prepare
220d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 d statement] or
220e0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c a pointer to NUL
220f0 4c 20 69 66 20 7a 53 71 6c 20 63 6f 6e 74 61 69 L if zSql contai
22100 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e ns.** n
22110 6f 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 othing other tha
22120 6e 20 77 68 69 74 65 73 70 61 63 65 20 6f 72 20 n whitespace or
22130 63 6f 6d 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 comments..**.**
22140 7b 48 31 33 30 31 39 7d 20 54 68 65 20 5b 73 71 {H13019} The [sq
22150 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
22160 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e ()] interface an
22170 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 72 d its variants r
22180 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 eturn.**
22190 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 [SQLITE_OK] or
221a0 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 an appropriate
221b0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f [error code] upo
221c0 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a n failure..**.**
221d0 20 7b 48 31 33 30 32 31 7d 20 42 65 66 6f 72 65 {H13021} Before
221e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
221f0 65 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c e(db,zSql,nByte,
22200 70 70 53 74 6d 74 2c 70 7a 54 61 69 6c 29 5d 20 ppStmt,pzTail)]
22210 6f 72 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 or its.**
22220 20 20 20 76 61 72 69 61 6e 74 73 20 72 65 74 75 variants retu
22230 72 6e 73 20 61 6e 20 65 72 72 6f 72 20 28 61 6e rns an error (an
22240 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 y value other th
22250 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 29 2c an [SQLITE_OK]),
22260 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
22270 79 20 66 69 72 73 74 20 73 65 74 20 2a 70 70 53 y first set *ppS
22280 74 6d 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a tmt to NULL..*/.
22290 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 int sqlite3_prep
222a0 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a are(. sqlite3 *
222b0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f db, /
222c0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c * Database handl
222d0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
222e0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f r *zSql, /
222f0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c * SQL statement,
22300 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a UTF-8 encoded *
22310 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 /. int nByte,
22320 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d /* M
22330 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
22340 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 zSql in bytes.
22350 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d */. sqlite3_stm
22360 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 t **ppStmt, /*
22370 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 OUT: Statement h
22380 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
22390 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 char **pzTail
223a0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 /* OUT: Point
223b0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 er to unused por
223c0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a tion of zSql */.
223d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 );.int sqlite3_p
223e0 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c repare_v2(. sql
223f0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
22400 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
22410 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
22420 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 st char *zSql,
22430 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 /* SQL stat
22440 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 ement, UTF-8 enc
22450 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 oded */. int nB
22460 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 yte,
22470 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e /* Maximum len
22480 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 gth of zSql in b
22490 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 ytes. */. sqlit
224a0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 e3_stmt **ppStmt
224b0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 , /* OUT: State
224c0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 ment handle */.
224d0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a const char **pz
224e0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a Tail /* OUT:
224f0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 Pointer to unus
22500 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 ed portion of zS
22510 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c ql */.);.int sql
22520 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a ite3_prepare16(.
22530 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
22540 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
22550 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a abase handle */.
22560 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 const void *zS
22570 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c ql, /* SQL
22580 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d statement, UTF-
22590 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 16 encoded */.
225a0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 int nByte,
225b0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d /* Maxim
225c0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 um length of zSq
225d0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 l in bytes. */.
225e0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a sqlite3_stmt **
225f0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a ppStmt, /* OUT:
22600 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c Statement handl
22610 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 e */. const voi
22620 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f d **pzTail /
22630 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 * OUT: Pointer t
22640 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e o unused portion
22650 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 of zSql */.);.i
22660 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nt sqlite3_prepa
22670 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 re16_v2(. sqlit
22680 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
22690 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 /* Database h
226a0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
226b0 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 void *zSql,
226c0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d /* SQL statem
226d0 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f ent, UTF-16 enco
226e0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 ded */. int nBy
226f0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 te,
22700 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 /* Maximum leng
22710 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 th of zSql in by
22720 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 tes. */. sqlite
22730 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 3_stmt **ppStmt,
22740 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d /* OUT: Statem
22750 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ent handle */.
22760 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 const void **pzT
22770 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 ail /* OUT:
22780 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 Pointer to unuse
22790 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 d portion of zSq
227a0 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 l */.);../*.** C
227b0 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 API3REF: Retriev
227c0 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 ing Statement SQ
227d0 4c 20 7b 48 31 33 31 30 30 7d 20 3c 48 31 33 30 L {H13100} <H130
227e0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 00>.**.** This i
227f0 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 nterface can be
22800 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 used to retrieve
22810 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 a saved copy of
22820 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a the original.**
22830 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 SQL text used t
22840 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 o create a [prep
22850 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
22860 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e if that statemen
22870 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 t was.** compile
22880 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b d using either [
22890 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
228a0 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 v2()] or [sqlite
228b0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
228c0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 ]..**.** INVARIA
228d0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 NTS:.**.** {H131
228e0 30 31 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 01} If the [prep
228f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
22900 70 61 73 73 65 64 20 61 73 20 74 68 65 20 61 72 passed as the ar
22910 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 gument to.**
22920 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 [sqlite3_s
22930 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c ql()] was compil
22940 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 ed using either
22950 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
22960 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 _v2()] or.**
22970 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 [sqlite3_p
22980 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 repare16_v2()],
22990 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 then [sqlite3_sq
229a0 6c 28 29 5d 20 72 65 74 75 72 6e 73 0a 2a 2a 20 l()] returns.**
229b0 20 20 20 20 20 20 20 20 20 61 20 70 6f 69 6e 74 a point
229c0 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 er to a zero-ter
229d0 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 20 63 minated string c
229e0 6f 6e 74 61 69 6e 69 6e 67 20 61 20 55 54 46 2d ontaining a UTF-
229f0 38 20 72 65 6e 64 65 72 69 6e 67 0a 2a 2a 20 20 8 rendering.**
22a00 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 6f of the o
22a10 72 69 67 69 6e 61 6c 20 53 51 4c 20 73 74 61 74 riginal SQL stat
22a20 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ement..**.** {H1
22a30 33 31 30 32 7d 20 49 66 20 74 68 65 20 5b 70 72 3102} If the [pr
22a40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
22a50 5d 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 ] passed as the
22a60 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 argument to.**
22a70 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
22a80 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 _sql()] was comp
22a90 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 iled using eithe
22aa0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
22ab0 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 re()] or.**
22ac0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 [sqlite3_pr
22ad0 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 65 6e epare16()], then
22ae0 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d [sqlite3_sql()]
22af0 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 returns a NULL
22b00 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b pointer..**.** {
22b10 48 31 33 31 30 33 7d 20 54 68 65 20 73 74 72 69 H13103} The stri
22b20 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b ng returned by [
22b30 73 71 6c 69 74 65 33 5f 73 71 6c 28 53 29 5d 20 sqlite3_sql(S)]
22b40 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 is valid until t
22b50 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b he.** [
22b60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
22b70 6e 74 5d 20 53 20 69 73 20 64 65 6c 65 74 65 64 nt] S is deleted
22b80 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
22b90 66 69 6e 61 6c 69 7a 65 28 53 29 5d 2e 0a 2a 2f finalize(S)]..*/
22ba0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
22bb0 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 ite3_sql(sqlite3
22bc0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a _stmt *pStmt);..
22bd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
22be0 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 Dynamically Type
22bf0 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 20 7b d Value Object {
22c00 48 31 35 30 30 30 7d 20 3c 53 32 30 32 30 30 3e H15000} <S20200>
22c10 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 .** KEYWORDS: {p
22c20 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
22c30 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 _value} {unprote
22c40 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
22c50 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 ue}.**.** SQLite
22c60 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 uses the sqlite
22c70 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 3_value object t
22c80 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 o represent all
22c90 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 values.** that c
22ca0 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 an be stored in
22cb0 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 a database table
22cc0 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 . SQLite uses dy
22cd0 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 namic typing.**
22ce0 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 for the values i
22cf0 74 20 73 74 6f 72 65 73 2e 20 56 61 6c 75 65 73 t stores. Values
22d00 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 stored in sqlit
22d10 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
22d20 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 .** can be integ
22d30 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f ers, floating po
22d40 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 int values, stri
22d50 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e ngs, BLOBs, or N
22d60 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 ULL..**.** An sq
22d70 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
22d80 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 ct may be either
22d90 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 "protected" or
22da0 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a "unprotected"..*
22db0 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 * Some interface
22dc0 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 s require a prot
22dd0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
22de0 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 lue. Other inte
22df0 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 rfaces.** will a
22e00 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70 ccept either a p
22e10 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 rotected or an u
22e20 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
22e30 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 e3_value..** Eve
22e40 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 ry interface tha
22e50 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 t accepts sqlite
22e60 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 3_value argument
22e70 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 s specifies.** w
22e80 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 hether or not it
22e90 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 requires a prot
22ea0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
22eb0 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 lue..**.** The t
22ec0 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 erms "protected"
22ed0 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 and "unprotecte
22ee0 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 d" refer to whet
22ef0 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 her or not.** a
22f00 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 mutex is held.
22f10 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 A internal mutex
22f20 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 is held for a p
22f30 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 rotected.** sqli
22f40 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
22f50 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 but no mutex is
22f60 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 held for an unp
22f70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 rotected.** sqli
22f80 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
22f90 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 . If SQLite is
22fa0 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 compiled to be s
22fb0 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a ingle-threaded.*
22fc0 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f * (with [SQLITE_
22fd0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e THREADSAFE=0] an
22fe0 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f d with [sqlite3_
22ff0 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 threadsafe()] re
23000 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 turning 0).** or
23010 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 if SQLite is ru
23020 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 n in one of redu
23030 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 ced mutex modes
23040 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 .** [SQLITE_CONF
23050 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d IG_SINGLETHREAD]
23060 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 or [SQLITE_CONF
23070 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a IG_MULTITHREAD].
23080 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 ** then there is
23090 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 no distinction
230a0 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 between protecte
230b0 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 d and unprotecte
230c0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c d.** sqlite3_val
230d0 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 ue objects and t
230e0 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 hey can be used
230f0 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e interchangeably.
23100 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f However,.** fo
23110 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 r maximum code p
23120 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 ortability it is
23130 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 recommended tha
23140 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a t applications.*
23150 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 * still make the
23160 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 distinction bet
23170 77 65 65 6e 20 62 65 74 77 65 65 6e 20 70 72 6f ween between pro
23180 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f tected and unpro
23190 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 tected.** sqlite
231a0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 3_value objects
231b0 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 even when not st
231c0 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e rictly required.
231d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
231e0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
231f0 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64 that are passed
23200 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 as parameters i
23210 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 nto the.** imple
23220 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 mentation of [ap
23230 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
23240 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d d SQL functions]
23250 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a are protected..
23260 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 ** The sqlite3_v
23270 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 alue object retu
23280 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 rned by.** [sqli
23290 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 te3_column_value
232a0 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 ()] is unprotect
232b0 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 ed..** Unprotect
232c0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
232d0 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c objects may onl
232e0 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a y be used with.*
232f0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c * [sqlite3_resul
23300 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b t_value()] and [
23310 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c sqlite3_bind_val
23320 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 ue()]..** The [s
23330 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f qlite3_value_blo
23340 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 b | sqlite3_valu
23350 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 e_type()] family
23360 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 of.** interface
23370 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 s require protec
23380 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
23390 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 e objects..*/.ty
233a0 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d pedef struct Mem
233b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a sqlite3_value;.
233c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
233d0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f SQL Function Co
233e0 6e 74 65 78 74 20 4f 62 6a 65 63 74 20 7b 48 31 ntext Object {H1
233f0 36 30 30 31 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 6001} <S20200>.*
23400 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 *.** The context
23410 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c in which an SQL
23420 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 function execut
23430 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 es is stored in
23440 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f an.** sqlite3_co
23450 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 41 ntext object. A
23460 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 pointer to an s
23470 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f qlite3_context o
23480 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 bject.** is alwa
23490 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 ys first paramet
234a0 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 er to [applicati
234b0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 on-defined SQL f
234c0 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 unctions]..** Th
234d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
234e0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 fined SQL functi
234f0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f on implementatio
23500 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 n will pass this
23510 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f .** pointer thro
23520 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 ugh into calls t
23530 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c o [sqlite3_resul
23540 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f t_int | sqlite3_
23550 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 result()],.** [s
23560 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
23570 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 _context()], [sq
23580 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 lite3_user_data(
23590 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
235a0 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c context_db_handl
235b0 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 e()], [sqlite3_g
235c0 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a et_auxdata()],.*
235d0 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 * and/or [sqlite
235e0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 3_set_auxdata()]
235f0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
23600 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 uct sqlite3_cont
23610 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ext sqlite3_cont
23620 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ext;../*.** CAPI
23630 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 3REF: Binding Va
23640 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 lues To Prepared
23650 20 53 74 61 74 65 6d 65 6e 74 73 20 7b 48 31 33 Statements {H13
23660 35 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 500} <S70300>.**
23670 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 KEYWORDS: {host
23680 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 parameter} {hos
23690 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 t parameters} {h
236a0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 ost parameter na
236b0 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a me}.** KEYWORDS:
236c0 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d {SQL parameter}
236d0 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 {SQL parameters
236e0 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e } {parameter bin
236f0 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 ding}.**.** In t
23700 68 65 20 53 51 4c 20 73 74 72 69 6e 67 73 20 69 he SQL strings i
23710 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 nput to [sqlite3
23720 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 _prepare_v2()] a
23730 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c nd its variants,
23740 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 .** literals may
23750 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 be replaced by
23760 61 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 6f a parameter in o
23770 6e 65 20 6f 66 20 74 68 65 73 65 20 66 6f 72 6d ne of these form
23780 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a s:.**.** <ul>.**
23790 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e <li> ?.** <li>
237a0 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 ?NNN.** <li>
237b0 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 :VVV.** <li> @V
237c0 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 VV.** <li> $VVV
237d0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
237e0 49 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 In the parameter
237f0 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f forms shown abo
23800 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74 ve NNN is an int
23810 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a eger literal,.**
23820 20 61 6e 64 20 56 56 56 20 69 73 20 61 6e 20 61 and VVV is an a
23830 6c 70 68 61 2d 6e 75 6d 65 72 69 63 20 70 61 72 lpha-numeric par
23840 61 6d 65 74 65 72 20 6e 61 6d 65 2e 20 54 68 65 ameter name. The
23850 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 values of these
23860 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 .** parameters (
23870 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 also called "hos
23880 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 t parameter name
23890 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d s" or "SQL param
238a0 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 eters").** can b
238b0 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 e set using the
238c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 sqlite3_bind_*()
238d0 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 routines define
238e0 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 d here..**.** Th
238f0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
23900 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
23910 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 bind_*() routine
23920 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 s is always.** a
23930 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
23940 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f [sqlite3_stmt] o
23950 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 bject returned f
23960 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f rom.** [sqlite3_
23970 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
23980 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a its variants..*
23990 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 *.** The second
239a0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 argument is the
239b0 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c index of the SQL
239c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 parameter to be
239d0 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20 6c 65 66 set..** The lef
239e0 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 tmost SQL parame
239f0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 ter has an index
23a00 20 6f 66 20 31 2e 20 20 57 68 65 6e 20 74 68 65 of 1. When the
23a10 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 same named.** S
23a20 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 QL parameter is
23a30 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f used more than o
23a40 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 nce, second and
23a50 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 subsequent.** oc
23a60 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 currences have t
23a70 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 he same index as
23a80 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 the first occur
23a90 72 65 6e 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6e rence..** The in
23aa0 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 dex for named pa
23ab0 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 rameters can be
23ac0 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 looked up using
23ad0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
23ae0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 bind_parameter_i
23af0 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 ndex()] API if d
23b00 65 73 69 72 65 64 2e 20 20 54 68 65 20 69 6e 64 esired. The ind
23b10 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 ex.** for "?NNN"
23b20 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 parameters is t
23b30 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e he value of NNN.
23b40 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75 .** The NNN valu
23b50 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 e must be betwee
23b60 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c n 1 and the [sql
23b70 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a ite3_limit()].**
23b80 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 parameter [SQLI
23b90 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c TE_LIMIT_VARIABL
23ba0 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 E_NUMBER] (defau
23bb0 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a lt value: 999)..
23bc0 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 **.** The third
23bd0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 argument is the
23be0 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f value to bind to
23bf0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a the parameter..
23c00 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 72 **.** In those r
23c10 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 outines that hav
23c20 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d e a fourth argum
23c30 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 ent, its value i
23c40 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 s the.** number
23c50 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 of bytes in the
23c60 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 parameter. To b
23c70 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c e clear: the val
23c80 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d ue is the.** num
23c90 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c ber of <u>bytes<
23ca0 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 /u> in the value
23cb0 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 , not the number
23cc0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a of characters..
23cd0 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 ** If the fourth
23ce0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 parameter is ne
23cf0 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 gative, the leng
23d00 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 th of the string
23d10 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 is.** the numbe
23d20 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f r of bytes up to
23d30 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 the first zero
23d40 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a terminator..**.*
23d50 2a 20 54 68 65 20 66 69 66 74 68 20 61 72 67 75 * The fifth argu
23d60 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f ment to sqlite3_
23d70 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c bind_blob(), sql
23d80 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 ite3_bind_text()
23d90 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 , and.** sqlite3
23da0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 _bind_text16() i
23db0 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 s a destructor u
23dc0 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f sed to dispose o
23dd0 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a f the BLOB or.**
23de0 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 string after SQ
23df0 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 Lite has finishe
23e00 64 20 77 69 74 68 20 69 74 2e 20 49 66 20 74 68 d with it. If th
23e10 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 e fifth argument
23e20 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 is.** the speci
23e30 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 al value [SQLITE
23e40 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 _STATIC], then S
23e50 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 QLite assumes th
23e60 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d at the.** inform
23e70 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 ation is in stat
23e80 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 ic, unmanaged sp
23e90 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 ace and does not
23ea0 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 need to be free
23eb0 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 66 d..** If the fif
23ec0 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 th argument has
23ed0 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 the value [SQLIT
23ee0 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 E_TRANSIENT], th
23ef0 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b en.** SQLite mak
23f00 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 es its own priva
23f10 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 te copy of the d
23f20 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c ata immediately,
23f30 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 before.** the s
23f40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 qlite3_bind_*()
23f50 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e routine returns.
23f60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
23f70 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 e3_bind_zeroblob
23f80 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 () routine binds
23f90 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 a BLOB of lengt
23fa0 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 h N that.** is f
23fb0 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 illed with zeroe
23fc0 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f 62 20 75 s. A zeroblob u
23fd0 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 ses a fixed amou
23fe0 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 nt of memory.**
23ff0 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 (just an integer
24000 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a to hold its siz
24010 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 e) while it is b
24020 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a eing processed..
24030 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 ** Zeroblobs are
24040 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 intended to ser
24050 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 ve as placeholde
24060 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f rs for BLOBs who
24070 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 se.** content is
24080 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 later written u
24090 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 sing.** [sqlite3
240a0 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 _blob_open | inc
240b0 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f remental BLOB I/
240c0 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 O] routines..**
240d0 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 A negative value
240e0 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f for the zeroblo
240f0 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a b results in a z
24100 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e ero-length BLOB.
24110 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
24120 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 e3_bind_*() rout
24130 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c ines must be cal
24140 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73 71 led after.** [sq
24150 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
24160 28 29 5d 20 28 61 6e 64 20 69 74 73 20 76 61 72 ()] (and its var
24170 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69 74 iants) or [sqlit
24180 65 33 5f 72 65 73 65 74 28 29 5d 20 61 6e 64 0a e3_reset()] and.
24190 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 ** before [sqlit
241a0 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 42 e3_step()]..** B
241b0 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 indings are not
241c0 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b cleared by the [
241d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
241e0 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62 routine..** Unb
241f0 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 ound parameters
24200 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 are interpreted
24210 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 as NULL..**.** T
24220 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 hese routines re
24230 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d turn [SQLITE_OK]
24240 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 on success or a
24250 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69 66 0a n error code if.
24260 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 ** anything goes
24270 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 54 45 wrong. [SQLITE
24280 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 _RANGE] is retur
24290 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d ned if the param
242a0 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 eter.** index is
242b0 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 out of range.
242c0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 [SQLITE_NOMEM] i
242d0 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 s returned if ma
242e0 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a lloc() fails..**
242f0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
24300 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e might be return
24310 65 64 20 69 66 20 74 68 65 73 65 20 72 6f 75 74 ed if these rout
24320 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 ines are called
24330 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75 61 6c 20 on a.** virtual
24340 6d 61 63 68 69 6e 65 20 74 68 61 74 20 69 73 20 machine that is
24350 74 68 65 20 77 72 6f 6e 67 20 73 74 61 74 65 20 the wrong state
24360 6f 72 20 77 68 69 63 68 20 68 61 73 20 61 6c 72 or which has alr
24370 65 61 64 79 20 62 65 65 6e 20 66 69 6e 61 6c 69 eady been finali
24380 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63 74 69 6f zed..** Detectio
24390 6e 20 6f 66 20 6d 69 73 75 73 65 20 69 73 20 75 n of misuse is u
243a0 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41 70 70 6c nreliable. Appl
243b0 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 ications should
243c0 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e not depend.** on
243d0 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 72 SQLITE_MISUSE r
243e0 65 74 75 72 6e 73 2e 20 20 53 51 4c 49 54 45 5f eturns. SQLITE_
243f0 4d 49 53 55 53 45 20 69 73 20 69 6e 74 65 6e 64 MISUSE is intend
24400 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 61 ed to indicate a
24410 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65 72 72 6f .** a logic erro
24420 72 20 69 6e 20 74 68 65 20 61 70 70 6c 69 63 61 r in the applica
24430 74 69 6f 6e 2e 20 20 46 75 74 75 72 65 20 76 65 tion. Future ve
24440 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
24450 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e 69 63 20 might.** panic
24460 72 61 74 68 65 72 20 74 68 61 6e 20 72 65 74 75 rather than retu
24470 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 rn SQLITE_MISUSE
24480 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
24490 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f : [sqlite3_bind_
244a0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 parameter_count(
244b0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
244c0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e bind_parameter_n
244d0 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c ame()], and [sql
244e0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
244f0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a ter_index()]..**
24500 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
24510 2a 2a 0a 2a 2a 20 7b 48 31 33 35 30 36 7d 20 54 **.** {H13506} T
24520 68 65 20 5b 53 51 4c 20 73 74 61 74 65 6d 65 6e he [SQL statemen
24530 74 20 63 6f 6d 70 69 6c 65 72 5d 20 72 65 63 6f t compiler] reco
24540 67 6e 69 7a 65 73 20 74 6f 6b 65 6e 73 20 6f 66 gnizes tokens of
24550 20 74 68 65 20 66 6f 72 6d 73 0a 2a 2a 20 20 20 the forms.**
24560 20 20 20 20 20 20 20 22 3f 22 2c 20 22 3f 4e 4e "?", "?NN
24570 4e 22 2c 20 22 24 56 56 56 22 2c 20 22 3a 56 56 N", "$VVV", ":VV
24580 56 22 2c 20 61 6e 64 20 22 40 56 56 56 22 20 61 V", and "@VVV" a
24590 73 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 s SQL parameters
245a0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 ,.** wh
245b0 65 72 65 20 4e 4e 4e 20 69 73 20 61 6e 79 20 73 ere NNN is any s
245c0 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f equence of one o
245d0 72 20 6d 6f 72 65 20 64 69 67 69 74 73 0a 2a 2a r more digits.**
245e0 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 77 68 and wh
245f0 65 72 65 20 56 56 56 20 69 73 20 61 6e 79 20 73 ere VVV is any s
24600 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f equence of one o
24610 72 20 6d 6f 72 65 20 61 6c 70 68 61 6e 75 6d 65 r more alphanume
24620 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ric.**
24630 63 68 61 72 61 63 74 65 72 73 20 6f 72 20 22 3a characters or ":
24640 3a 22 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 66 6f :" optionally fo
24650 6c 6c 6f 77 65 64 20 62 79 20 61 20 73 74 72 69 llowed by a stri
24660 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a ng containing.**
24670 20 20 20 20 20 20 20 20 20 20 6e 6f 20 73 70 61 no spa
24680 63 65 73 20 61 6e 64 20 63 6f 6e 74 61 69 6e 65 ces and containe
24690 64 20 77 69 74 68 69 6e 20 70 61 72 65 6e 74 68 d within parenth
246a0 65 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 eses..**.** {H13
246b0 35 30 39 7d 20 54 68 65 20 69 6e 69 74 69 61 6c 509} The initial
246c0 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c value of an SQL
246d0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 parameter is NU
246e0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 LL..**.** {H1351
246f0 32 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 2} The index of
24700 61 6e 20 22 3f 22 20 53 51 4c 20 70 61 72 61 6d an "?" SQL param
24710 65 74 65 72 20 69 73 20 6f 6e 65 20 6c 61 72 67 eter is one larg
24720 65 72 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20 20 er than the.**
24730 20 20 20 20 20 20 20 20 6c 61 72 67 65 73 74 20 largest
24740 69 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72 index of SQL par
24750 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 6c 65 ameter to the le
24760 66 74 2c 20 6f 72 20 31 20 69 66 0a 2a 2a 20 20 ft, or 1 if.**
24770 20 20 20 20 20 20 20 20 74 68 65 20 22 3f 22 20 the "?"
24780 69 73 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 is the leftmost
24790 53 51 4c 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a SQL parameter..*
247a0 2a 0a 2a 2a 20 7b 48 31 33 35 31 35 7d 20 54 68 *.** {H13515} Th
247b0 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f e index of an "?
247c0 4e 4e 4e 22 20 53 51 4c 20 70 61 72 61 6d 65 74 NNN" SQL paramet
247d0 65 72 20 69 73 20 74 68 65 20 69 6e 74 65 67 65 er is the intege
247e0 72 20 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 r NNN..**.** {H1
247f0 33 35 31 38 7d 20 54 68 65 20 69 6e 64 65 78 20 3518} The index
24800 6f 66 20 61 6e 20 22 3a 56 56 56 22 2c 20 22 24 of an ":VVV", "$
24810 56 56 56 22 2c 20 6f 72 20 22 40 56 56 56 22 20 VVV", or "@VVV"
24820 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 SQL parameter is
24830 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
24840 20 73 61 6d 65 20 61 73 20 74 68 65 20 69 6e 64 same as the ind
24850 65 78 20 6f 66 20 6c 65 66 74 6d 6f 73 74 20 6f ex of leftmost o
24860 63 63 75 72 72 65 6e 63 65 73 20 6f 66 20 74 68 ccurrences of th
24870 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 e same.**
24880 20 20 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 parameter, or
24890 20 6f 6e 65 20 6d 6f 72 65 20 74 68 61 6e 20 74 one more than t
248a0 68 65 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 he largest index
248b0 20 6f 76 65 72 20 61 6c 6c 0a 2a 2a 20 20 20 20 over all.**
248c0 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 73 parameters
248d0 20 74 6f 20 74 68 65 20 6c 65 66 74 20 69 66 20 to the left if
248e0 74 68 69 73 20 69 73 20 74 68 65 20 66 69 72 73 this is the firs
248f0 74 20 6f 63 63 75 72 72 65 6e 63 65 0a 2a 2a 20 t occurrence.**
24900 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 69 73 of this
24910 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 31 parameter, or 1
24920 20 69 66 20 74 68 69 73 20 69 73 20 74 68 65 20 if this is the
24930 6c 65 66 74 6d 6f 73 74 20 70 61 72 61 6d 65 74 leftmost paramet
24940 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 er..**.** {H1352
24950 31 7d 20 54 68 65 20 5b 53 51 4c 20 73 74 61 74 1} The [SQL stat
24960 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 ement compiler]
24970 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 5b 53 fails with an [S
24980 51 4c 49 54 45 5f 52 41 4e 47 45 5d 0a 2a 2a 20 QLITE_RANGE].**
24990 20 20 20 20 20 20 20 20 20 65 72 72 6f 72 20 69 error i
249a0 66 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 f the index of a
249b0 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 n SQL parameter
249c0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 31 0a 2a is less than 1.*
249d0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 67 72 * or gr
249e0 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 63 eater than the c
249f0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 53 51 4c 49 ompile-time SQLI
24a00 54 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f TE_MAX_VARIABLE_
24a10 4e 55 4d 42 45 52 0a 2a 2a 20 20 20 20 20 20 20 NUMBER.**
24a20 20 20 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a parameter..**
24a30 0a 2a 2a 20 7b 48 31 33 35 32 34 7d 20 43 61 6c .** {H13524} Cal
24a40 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 ls to [sqlite3_b
24a50 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 ind_text | sqlit
24a60 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 56 2c 2e 2e e3_bind(S,N,V,..
24a70 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 .)].**
24a80 61 73 73 6f 63 69 61 74 65 20 74 68 65 20 76 61 associate the va
24a90 6c 75 65 20 56 20 77 69 74 68 20 61 6c 6c 20 53 lue V with all S
24aa0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 68 61 QL parameters ha
24ab0 76 69 6e 67 20 61 6e 0a 2a 2a 20 20 20 20 20 20 ving an.**
24ac0 20 20 20 20 69 6e 64 65 78 20 6f 66 20 4e 20 69 index of N i
24ad0 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 n the [prepared
24ae0 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a statement] S..**
24af0 0a 2a 2a 20 7b 48 31 33 35 32 37 7d 20 43 61 6c .** {H13527} Cal
24b00 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 ls to [sqlite3_b
24b10 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 ind_text | sqlit
24b20 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 2e 2e 2e 29 e3_bind(S,N,...)
24b30 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76 ].** ov
24b40 65 72 72 69 64 65 20 70 72 69 6f 72 20 63 61 6c erride prior cal
24b50 6c 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 ls with the same
24b60 20 76 61 6c 75 65 73 20 6f 66 20 53 20 61 6e 64 values of S and
24b70 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 N..**.** {H1353
24b80 30 7d 20 42 69 6e 64 69 6e 67 73 20 65 73 74 61 0} Bindings esta
24b90 62 6c 69 73 68 65 64 20 62 79 20 5b 73 71 6c 69 blished by [sqli
24ba0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 te3_bind_text |
24bb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 2e sqlite3_bind(S,.
24bc0 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 ..)].**
24bd0 20 70 65 72 73 69 73 74 20 61 63 72 6f 73 73 20 persist across
24be0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
24bf0 33 5f 72 65 73 65 74 28 53 29 5d 2e 0a 2a 2a 0a 3_reset(S)]..**.
24c00 2a 2a 20 7b 48 31 33 35 33 33 7d 20 49 6e 20 63 ** {H13533} In c
24c10 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
24c20 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 _bind_blob(S,N,V
24c30 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 ,L,D)],.**
24c40 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e [sqlite3_bin
24c50 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 d_text(S,N,V,L,D
24c60 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 )], or.**
24c70 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 [sqlite3_bind
24c80 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c _text16(S,N,V,L,
24c90 44 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 D)] SQLite binds
24ca0 20 74 68 65 20 66 69 72 73 74 20 4c 0a 2a 2a 20 the first L.**
24cb0 20 20 20 20 20 20 20 20 20 62 79 74 65 73 20 6f bytes o
24cc0 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 f the BLOB or st
24cd0 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 ring pointed to
24ce0 62 79 20 56 2c 20 77 68 65 6e 20 4c 0a 2a 2a 20 by V, when L.**
24cf0 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d is non-
24d00 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 negative..**.**
24d10 7b 48 31 33 35 33 36 7d 20 49 6e 20 63 61 6c 6c {H13536} In call
24d20 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 s to [sqlite3_bi
24d30 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c nd_text(S,N,V,L,
24d40 44 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 D)] or.**
24d50 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 [sqlite3_bind
24d60 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c _text16(S,N,V,L,
24d70 44 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 D)] SQLite binds
24d80 20 63 68 61 72 61 63 74 65 72 73 0a 2a 2a 20 20 characters.**
24d90 20 20 20 20 20 20 20 20 66 72 6f 6d 20 56 20 74 from V t
24da0 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 hrough the first
24db0 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 20 zero character
24dc0 77 68 65 6e 20 4c 20 69 73 20 6e 65 67 61 74 69 when L is negati
24dd0 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 ve..**.** {H1353
24de0 39 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 9} In calls to [
24df0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
24e00 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a b(S,N,V,L,D)],.*
24e10 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
24e20 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c te3_bind_text(S,
24e30 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a N,V,L,D)], or.**
24e40 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
24e50 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 e3_bind_text16(S
24e60 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 ,N,V,L,D)] when
24e70 44 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c D is the special
24e80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e .** con
24e90 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 stant [SQLITE_ST
24ea0 41 54 49 43 5d 2c 20 53 51 4c 69 74 65 20 61 73 ATIC], SQLite as
24eb0 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 76 sumes that the v
24ec0 61 6c 75 65 20 56 0a 2a 2a 20 20 20 20 20 20 20 alue V.**
24ed0 20 20 20 69 73 20 68 65 6c 64 20 69 6e 20 73 74 is held in st
24ee0 61 74 69 63 20 75 6e 6d 61 6e 61 67 65 64 20 73 atic unmanaged s
24ef0 70 61 63 65 20 74 68 61 74 20 77 69 6c 6c 20 6e pace that will n
24f00 6f 74 20 63 68 61 6e 67 65 0a 2a 2a 20 20 20 20 ot change.**
24f10 20 20 20 20 20 20 64 75 72 69 6e 67 20 74 68 65 during the
24f20 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 lifetime of the
24f30 20 62 69 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 binding..**.**
24f40 7b 48 31 33 35 34 32 7d 20 49 6e 20 63 61 6c 6c {H13542} In call
24f50 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 s to [sqlite3_bi
24f60 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c nd_blob(S,N,V,L,
24f70 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 D)],.**
24f80 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 [sqlite3_bind_t
24f90 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c ext(S,N,V,L,D)],
24fa0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 or.**
24fb0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 [sqlite3_bind_te
24fc0 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d xt16(S,N,V,L,D)]
24fd0 20 77 68 65 6e 20 44 20 69 73 20 74 68 65 20 73 when D is the s
24fe0 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 pecial.**
24ff0 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c constant [SQL
25000 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 ITE_TRANSIENT],
25010 74 68 65 20 72 6f 75 74 69 6e 65 20 6d 61 6b 65 the routine make
25020 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 s a.**
25030 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 private copy of
25040 74 68 65 20 76 61 6c 75 65 20 56 20 62 65 66 6f the value V befo
25050 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a re it returns..*
25060 2a 0a 2a 2a 20 7b 48 31 33 35 34 35 7d 20 49 6e *.** {H13545} In
25070 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 calls to [sqlit
25080 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e e3_bind_blob(S,N
25090 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 ,V,L,D)],.**
250a0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 [sqlite3_b
250b0 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c ind_text(S,N,V,L
250c0 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 ,D)], or.**
250d0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 [sqlite3_bi
250e0 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c nd_text16(S,N,V,
250f0 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20 L,D)] when D is
25100 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 a pointer to.**
25110 20 20 20 20 20 20 20 20 20 61 20 66 75 6e 63 74 a funct
25120 69 6f 6e 2c 20 53 51 4c 69 74 65 20 69 6e 76 6f ion, SQLite invo
25130 6b 65 73 20 74 68 61 74 20 66 75 6e 63 74 69 6f kes that functio
25140 6e 20 74 6f 20 64 65 73 74 72 6f 79 20 74 68 65 n to destroy the
25150 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c .** val
25160 75 65 20 56 20 61 66 74 65 72 20 69 74 20 68 61 ue V after it ha
25170 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 s finished using
25180 20 74 68 65 20 76 61 6c 75 65 20 56 2e 0a 2a 2a the value V..**
25190 0a 2a 2a 20 7b 48 31 33 35 34 38 7d 20 49 6e 20 .** {H13548} In
251a0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
251b0 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 3_bind_zeroblob(
251c0 53 2c 4e 2c 56 2c 4c 29 5d 20 74 68 65 20 76 61 S,N,V,L)] the va
251d0 6c 75 65 20 62 6f 75 6e 64 0a 2a 2a 20 20 20 20 lue bound.**
251e0 20 20 20 20 20 20 69 73 20 61 20 42 4c 4f 42 20 is a BLOB
251f0 6f 66 20 4c 20 62 79 74 65 73 2c 20 6f 72 20 61 of L bytes, or a
25200 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f zero-length BLO
25210 42 20 69 66 20 4c 20 69 73 20 6e 65 67 61 74 69 B if L is negati
25220 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 35 ve..**.** {H1355
25230 31 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 1} In calls to [
25240 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c sqlite3_bind_val
25250 75 65 28 53 2c 4e 2c 56 29 5d 20 74 68 65 20 56 ue(S,N,V)] the V
25260 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 0a 2a 2a argument may.**
25270 20 20 20 20 20 20 20 20 20 20 62 65 20 65 69 74 be eit
25280 68 65 72 20 61 20 5b 70 72 6f 74 65 63 74 65 64 her a [protected
25290 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
252a0 6f 62 6a 65 63 74 20 6f 72 20 61 6e 0a 2a 2a 20 object or an.**
252b0 20 20 20 20 20 20 20 20 20 5b 75 6e 70 72 6f 74 [unprot
252c0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
252d0 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a lue] object..*/.
252e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
252f0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 _blob(sqlite3_st
25300 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 mt*, int, const
25310 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f void*, int n, vo
25320 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 id(*)(void*));.i
25330 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
25340 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 double(sqlite3_s
25350 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c tmt*, int, doubl
25360 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f e);.int sqlite3_
25370 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 bind_int(sqlite3
25380 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 _stmt*, int, int
25390 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 );.int sqlite3_b
253a0 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 ind_int64(sqlite
253b0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 3_stmt*, int, sq
253c0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e lite3_int64);.in
253d0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e t sqlite3_bind_n
253e0 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ull(sqlite3_stmt
253f0 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c *, int);.int sql
25400 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 ite3_bind_text(s
25410 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
25420 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 t, const char*,
25430 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 int n, void(*)(v
25440 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 oid*));.int sqli
25450 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 te3_bind_text16(
25460 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
25470 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c nt, const void*,
25480 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f int, void(*)(vo
25490 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 id*));.int sqlit
254a0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 e3_bind_value(sq
254b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
254c0 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f , const sqlite3_
254d0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c value*);.int sql
254e0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c ite3_bind_zerobl
254f0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ob(sqlite3_stmt*
25500 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a , int, int n);..
25510 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
25520 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 Number Of SQL Pa
25530 72 61 6d 65 74 65 72 73 20 7b 48 31 33 36 30 30 rameters {H13600
25540 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a } <S70300>.**.**
25550 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 This routine ca
25560 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e n be used to fin
25570 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 d the number of
25580 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d [SQL parameters]
25590 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 .** in a [prepar
255a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 ed statement].
255b0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 SQL parameters a
255c0 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 re tokens of the
255d0 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f .** form "?", "?
255e0 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 NNN", ":AAA", "$
255f0 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 AAA", or "@AAA"
25600 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a that serve as.**
25610 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f placeholders fo
25620 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 r values that ar
25630 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f e [sqlite3_bind_
25640 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a blob | bound].**
25650 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 to the paramete
25660 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 rs at a later ti
25670 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 me..**.** This r
25680 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 outine actually
25690 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 returns the inde
256a0 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 x of the largest
256b0 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 (rightmost).**
256c0 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 parameter. For a
256d0 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 ll forms except
256e0 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 ?NNN, this will
256f0 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 correspond to th
25700 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 e.** number of u
25710 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 nique parameters
25720 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 . If parameters
25730 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 61 72 65 of the ?NNN are
25740 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 used,.** there
25750 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 may be gaps in t
25760 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 he list..**.** S
25770 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
25780 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 3_bind_blob|sqli
25790 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 te3_bind()],.**
257a0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
257b0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c rameter_name()],
257c0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
257d0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
257e0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 index()]..**.**
257f0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
25800 2a 20 7b 48 31 33 36 30 31 7d 20 54 68 65 20 5b * {H13601} The [
25810 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
25820 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 53 29 5d ameter_count(S)]
25830 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
25840 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 ns.** t
25850 68 65 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 he largest index
25860 20 6f 66 20 61 6c 6c 20 53 51 4c 20 70 61 72 61 of all SQL para
25870 6d 65 74 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a meters in the.**
25880 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 [prepa
25890 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
258a0 2c 20 6f 72 20 30 20 69 66 20 53 20 63 6f 6e 74 , or 0 if S cont
258b0 61 69 6e 73 20 6e 6f 20 53 51 4c 20 70 61 72 61 ains no SQL para
258c0 6d 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e 74 20 73 meters..*/.int s
258d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
258e0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 meter_count(sqli
258f0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a te3_stmt*);../*.
25900 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d ** CAPI3REF: Nam
25910 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 e Of A Host Para
25920 6d 65 74 65 72 20 7b 48 31 33 36 32 30 7d 20 3c meter {H13620} <
25930 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S70300>.**.** Th
25940 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 is routine retur
25950 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
25960 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
25970 6e 2d 74 68 0a 2a 2a 20 5b 53 51 4c 20 70 61 72 n-th.** [SQL par
25980 61 6d 65 74 65 72 5d 20 69 6e 20 61 20 5b 70 72 ameter] in a [pr
25990 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
259a0 5d 2e 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 ]..** SQL parame
259b0 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d ters of the form
259c0 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 "?NNN" or ":AAA
259d0 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 " or "@AAA" or "
259e0 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 $AAA".** have a
259f0 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 name which is th
25a00 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 e string "?NNN"
25a10 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 or ":AAA" or "@A
25a20 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a AA" or "$AAA".**
25a30 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a respectively..*
25a40 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 * In other words
25a50 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a , the initial ":
25a60 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 " or "$" or "@"
25a70 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 or "?".** is inc
25a80 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 luded as part of
25a90 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 the name..** Pa
25aa0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 rameters of the
25ab0 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 form "?" without
25ac0 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 a following int
25ad0 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d eger have no nam
25ae0 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 61 6c 73 e.** and are als
25af0 6f 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 o referred to as
25b00 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 "anonymous para
25b10 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 54 meters"..**.** T
25b20 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 he first host pa
25b30 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 rameter has an i
25b40 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 ndex of 1, not 0
25b50 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 76 ..**.** If the v
25b60 61 6c 75 65 20 6e 20 69 73 20 6f 75 74 20 6f 66 alue n is out of
25b70 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 range or if the
25b80 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 n-th parameter
25b90 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 is.** nameless,
25ba0 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 then NULL is ret
25bb0 75 72 6e 65 64 2e 20 20 54 68 65 20 72 65 74 75 urned. The retu
25bc0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a rned string is.*
25bd0 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d * always in UTF-
25be0 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 8 encoding even
25bf0 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 if the named par
25c00 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 ameter was.** or
25c10 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 iginally specifi
25c20 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 ed as UTF-16 in
25c30 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
25c40 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 16()] or.** [sql
25c50 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
25c60 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 2()]..**.** See
25c70 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 also: [sqlite3_b
25c80 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 ind_blob|sqlite3
25c90 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 _bind()],.** [sq
25ca0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
25cb0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 eter_count()], a
25cc0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 nd.** [sqlite3_b
25cd0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e ind_parameter_in
25ce0 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e dex()]..**.** IN
25cf0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
25d00 7b 48 31 33 36 32 31 7d 20 54 68 65 20 5b 73 71 {H13621} The [sq
25d10 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
25d20 65 74 65 72 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 eter_name(S,N)]
25d30 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
25d40 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 s.** a
25d50 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 UTF-8 rendering
25d60 6f 66 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 of the name of t
25d70 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 he SQL parameter
25d80 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 in.**
25d90 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
25da0 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 76 69 6e atement] S havin
25db0 67 20 69 6e 64 65 78 20 4e 2c 20 6f 72 0a 2a 2a g index N, or.**
25dc0 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 69 NULL i
25dd0 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 53 51 f there is no SQ
25de0 4c 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 L parameter with
25df0 20 69 6e 64 65 78 20 4e 20 6f 72 20 69 66 20 74 index N or if t
25e00 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 he.** p
25e10 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 69 6e arameter with in
25e20 64 65 78 20 4e 20 69 73 20 61 6e 20 61 6e 6f 6e dex N is an anon
25e30 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 20 ymous parameter
25e40 22 3f 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 "?"..*/.const ch
25e50 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 ar *sqlite3_bind
25e60 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 _parameter_name(
25e70 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
25e80 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 nt);../*.** CAPI
25e90 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 3REF: Index Of A
25ea0 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 Parameter With
25eb0 41 20 47 69 76 65 6e 20 4e 61 6d 65 20 7b 48 31 A Given Name {H1
25ec0 33 36 34 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 3640} <S70300>.*
25ed0 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 *.** Return the
25ee0 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 index of an SQL
25ef0 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 parameter given
25f00 69 74 73 20 6e 61 6d 65 2e 20 20 54 68 65 0a 2a its name. The.*
25f10 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 * index value re
25f20 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 turned is suitab
25f30 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 le for use as th
25f40 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 e second.** para
25f50 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 meter to [sqlite
25f60 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 3_bind_blob|sqli
25f70 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 41 20 te3_bind()]. A
25f80 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 zero.** is retur
25f90 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 ned if no matchi
25fa0 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 ng parameter is
25fb0 66 6f 75 6e 64 2e 20 20 54 68 65 20 70 61 72 61 found. The para
25fc0 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 meter.** name mu
25fd0 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 st be given in U
25fe0 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 TF-8 even if the
25ff0 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d original statem
26000 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 ent.** was prepa
26010 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 red from UTF-16
26020 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 text using [sqli
26030 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
26040 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ()]..**.** See a
26050 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 lso: [sqlite3_bi
26060 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f nd_blob|sqlite3_
26070 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c bind()],.** [sql
26080 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
26090 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e ter_count()], an
260a0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 d.** [sqlite3_bi
260b0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 nd_parameter_ind
260c0 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 ex()]..**.** INV
260d0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
260e0 48 31 33 36 34 31 7d 20 54 68 65 20 5b 73 71 6c H13641} The [sql
260f0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
26100 74 65 72 5f 69 6e 64 65 78 28 53 2c 4e 29 5d 20 ter_index(S,N)]
26110 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
26120 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 s.** th
26130 65 20 69 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 e index of SQL p
26140 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 arameter in the
26150 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
26160 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 ent].**
26170 20 53 20 77 68 6f 73 65 20 6e 61 6d 65 20 6d 61 S whose name ma
26180 74 63 68 65 73 20 74 68 65 20 55 54 46 2d 38 20 tches the UTF-8
26190 73 74 72 69 6e 67 20 4e 2c 20 6f 72 20 30 20 69 string N, or 0 i
261a0 66 20 74 68 65 72 65 20 69 73 0a 2a 2a 20 20 20 f there is.**
261b0 20 20 20 20 20 20 20 6e 6f 20 6d 61 74 63 68 2e no match.
261c0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
261d0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 bind_parameter_i
261e0 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d ndex(sqlite3_stm
261f0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a t*, const char *
26200 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 zName);../*.** C
26210 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 API3REF: Reset A
26220 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 ll Bindings On A
26230 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d Prepared Statem
26240 65 6e 74 20 7b 48 31 33 36 36 30 7d 20 3c 53 37 ent {H13660} <S7
26250 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 0300>.**.** Cont
26260 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 rary to the intu
26270 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b ition of many, [
26280 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
26290 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a does not reset.
262a0 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f ** the [sqlite3_
262b0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 bind_blob | bind
262c0 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 ings] on a [prep
262d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
262e0 0a 2a 2a 20 55 73 65 20 74 68 69 73 20 72 6f 75 .** Use this rou
262f0 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c tine to reset al
26300 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 l host parameter
26310 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a s to NULL..**.**
26320 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
26330 2a 2a 20 7b 48 31 33 36 36 31 7d 20 54 68 65 20 ** {H13661} The
26340 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 [sqlite3_clear_b
26350 69 6e 64 69 6e 67 73 28 53 29 5d 20 69 6e 74 65 indings(S)] inte
26360 72 66 61 63 65 20 72 65 73 65 74 73 20 61 6c 6c rface resets all
26370 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 SQL.**
26380 20 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 parameter bindi
26390 6e 67 73 20 69 6e 20 74 68 65 20 5b 70 72 65 70 ngs in the [prep
263a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
263b0 53 20 62 61 63 6b 20 74 6f 20 4e 55 4c 4c 2e 0a S back to NULL..
263c0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 */.int sqlite3_c
263d0 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 lear_bindings(sq
263e0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f lite3_stmt*);../
263f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e *.** CAPI3REF: N
26400 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 umber Of Columns
26410 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 In A Result Set
26420 20 7b 48 31 33 37 31 30 7d 20 3c 53 31 30 37 30 {H13710} <S1070
26430 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 0>.**.** Return
26440 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f the number of co
26450 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 lumns in the res
26460 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 ult set returned
26470 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 by the.** [prep
26480 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
26490 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 This routine re
264a0 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 turns 0 if pStmt
264b0 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 is an SQL.** st
264c0 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 atement that doe
264d0 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 s not return dat
264e0 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 a (for example a
264f0 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a n [UPDATE])..**.
26500 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
26510 2a 0a 2a 2a 20 7b 48 31 33 37 31 31 7d 20 54 68 *.** {H13711} Th
26520 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d e [sqlite3_colum
26530 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 n_count(S)] inte
26540 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 rface returns th
26550 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 e number of.**
26560 20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 73 20 columns
26570 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 in the result se
26580 74 20 67 65 6e 65 72 61 74 65 64 20 62 79 20 74 t generated by t
26590 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
265a0 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20 20 tement] S,.**
265b0 20 20 20 20 20 20 20 6f 72 20 30 20 69 66 20 53 or 0 if S
265c0 20 64 6f 65 73 20 6e 6f 74 20 67 65 6e 65 72 61 does not genera
265d0 74 65 20 61 20 72 65 73 75 6c 74 20 73 65 74 2e te a result set.
265e0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
265f0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c column_count(sql
26600 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
26610 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
26620 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 EF: Column Names
26630 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 In A Result Set
26640 20 7b 48 31 33 37 32 30 7d 20 3c 53 31 30 37 30 {H13720} <S1070
26650 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 0>.**.** These r
26660 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 outines return t
26670 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 he name assigned
26680 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 to a particular
26690 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 column.** in th
266a0 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 e result set of
266b0 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 a [SELECT] state
266c0 6d 65 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 ment. The sqlit
266d0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 e3_column_name()
266e0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 .** interface re
266f0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
26700 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e to a zero-termin
26710 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e ated UTF-8 strin
26720 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 g.** and sqlite3
26730 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 _column_name16()
26740 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
26750 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 er to a zero-ter
26760 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 minated.** UTF-1
26770 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 66 6 string. The f
26780 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 irst parameter i
26790 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 s the [prepared
267a0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 statement].** th
267b0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 at implements th
267c0 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 e [SELECT] state
267d0 6d 65 6e 74 2e 20 54 68 65 20 73 65 63 6f 6e 64 ment. The second
267e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
267f0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 e.** column numb
26800 65 72 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 er. The leftmos
26810 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 t column is numb
26820 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 er 0..**.** The
26830 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 returned string
26840 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 pointer is valid
26850 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 until either th
26860 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
26870 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 ement].** is des
26880 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 troyed by [sqlit
26890 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f e3_finalize()] o
268a0 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 r until the next
268b0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 call to.** sqli
268c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 te3_column_name(
268d0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c ) or sqlite3_col
268e0 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 umn_name16() on
268f0 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e the same column.
26900 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 .**.** If sqlite
26910 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 3_malloc() fails
26920 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 during the proc
26930 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 essing of either
26940 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 routine.** (for
26950 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 example during
26960 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f a conversion fro
26970 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 m UTF-8 to UTF-1
26980 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 6) then a.** NUL
26990 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 L pointer is ret
269a0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 urned..**.** The
269b0 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c name of a resul
269c0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 t column is the
269d0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 value of the "AS
269e0 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 " clause for.**
269f0 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 that column, if
26a00 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 there is an AS c
26a10 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 lause. If there
26a20 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 is no AS clause
26a30 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d .** then the nam
26a40 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 e of the column
26a50 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 is unspecified a
26a60 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 nd may change fr
26a70 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 om.** one releas
26a80 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 e of SQLite to t
26a90 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 49 he next..**.** I
26aa0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
26ab0 20 7b 48 31 33 37 32 31 7d 20 41 20 73 75 63 63 {H13721} A succ
26ac0 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f essful invocatio
26ad0 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 n of the [sqlite
26ae0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 3_column_name(S,
26af0 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 N)].**
26b00 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
26b10 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
26b20 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 e Nth column (wh
26b30 65 72 65 20 30 20 69 73 0a 2a 2a 20 20 20 20 20 ere 0 is.**
26b40 20 20 20 20 20 74 68 65 20 6c 65 66 74 6d 6f 73 the leftmos
26b50 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68 t column) for th
26b60 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 e result set of
26b70 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
26b80 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
26b90 65 6e 74 5d 20 53 20 61 73 20 61 20 7a 65 72 6f ent] S as a zero
26ba0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d -terminated UTF-
26bb0 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 8 string..**.**
26bc0 7b 48 31 33 37 32 33 7d 20 41 20 73 75 63 63 65 {H13723} A succe
26bd0 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e ssful invocation
26be0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
26bf0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 _column_name16(S
26c00 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 ,N)].**
26c10 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
26c20 6e 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 ns the name of t
26c30 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 he Nth column (w
26c40 68 65 72 65 20 30 20 69 73 0a 2a 2a 20 20 20 20 here 0 is.**
26c50 20 20 20 20 20 20 74 68 65 20 6c 65 66 74 6d 6f the leftmo
26c60 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 st column) for t
26c70 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 he result set of
26c80 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
26c90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
26ca0 6d 65 6e 74 5d 20 53 20 61 73 20 61 20 7a 65 72 ment] S as a zer
26cb0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 o-terminated UTF
26cc0 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 -16 string.**
26cd0 20 20 20 20 20 20 20 69 6e 20 74 68 65 20 6e 61 in the na
26ce0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e tive byte order.
26cf0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 34 7d 20 .**.** {H13724}
26d00 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c The [sqlite3_col
26d10 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 umn_name()] and
26d20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
26d30 6e 61 6d 65 31 36 28 29 5d 0a 2a 2a 20 20 20 20 name16()].**
26d40 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 interfaces
26d50 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 return a NULL p
26d60 6f 69 6e 74 65 72 20 69 66 20 74 68 65 79 20 61 ointer if they a
26d70 72 65 20 75 6e 61 62 6c 65 20 74 6f 0a 2a 2a 20 re unable to.**
26d80 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 allocat
26d90 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 e memory to hold
26da0 20 74 68 65 69 72 20 6e 6f 72 6d 61 6c 20 72 65 their normal re
26db0 74 75 72 6e 20 73 74 72 69 6e 67 73 2e 0a 2a 2a turn strings..**
26dc0 0a 2a 2a 20 7b 48 31 33 37 32 35 7d 20 49 66 20 .** {H13725} If
26dd0 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 the N parameter
26de0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to [sqlite3_colu
26df0 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 6f 72 mn_name(S,N)] or
26e00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
26e10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
26e20 65 31 36 28 53 2c 4e 29 5d 20 69 73 20 6f 75 74 e16(S,N)] is out
26e30 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 6e 20 of range, then
26e40 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
26e50 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 72 interfaces retur
26e60 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 n a NULL pointer
26e70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 36 7d ..**.** {H13726}
26e80 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 The strings ret
26e90 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 urned by [sqlite
26ea0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 3_column_name(S,
26eb0 4e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 N)] and.**
26ec0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c [sqlite3_col
26ed0 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d umn_name16(S,N)]
26ee0 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c are valid until
26ef0 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 20 20 20 the next.**
26f00 20 20 20 20 20 20 63 61 6c 6c 20 74 6f 20 65 69 call to ei
26f10 74 68 65 72 20 72 6f 75 74 69 6e 65 20 77 69 74 ther routine wit
26f20 68 20 74 68 65 20 73 61 6d 65 20 53 20 61 6e 64 h the same S and
26f30 20 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a N parameters.**
26f40 20 20 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74 or unt
26f50 69 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 il [sqlite3_fina
26f60 6c 69 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c lize(S)] is call
26f70 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 ed..**.** {H1372
26f80 37 7d 20 57 68 65 6e 20 61 20 72 65 73 75 6c 74 7} When a result
26f90 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 5b 53 45 column of a [SE
26fa0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 LECT] statement
26fb0 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 contains.**
26fc0 20 20 20 20 20 61 6e 20 41 53 20 63 6c 61 75 73 an AS claus
26fd0 65 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 e, the name of t
26fe0 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 hat column is th
26ff0 65 20 69 64 65 6e 74 69 66 69 65 72 0a 2a 2a 20 e identifier.**
27000 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 to the
27010 72 69 67 68 74 20 6f 66 20 74 68 65 20 41 53 20 right of the AS
27020 6b 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63 6f 6e 73 keyword..*/.cons
27030 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
27040 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 column_name(sqli
27050 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e te3_stmt*, int N
27060 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
27070 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
27080 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d me16(sqlite3_stm
27090 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a t*, int N);../*.
270a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 ** CAPI3REF: Sou
270b0 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 rce Of Data In A
270c0 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48 Query Result {H
270d0 31 33 37 34 30 7d 20 3c 53 31 30 37 30 30 3e 0a 13740} <S10700>.
270e0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
270f0 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d ines provide a m
27100 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e eans to determin
27110 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 e what column of
27120 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69 what.** table i
27130 6e 20 77 68 69 63 68 20 64 61 74 61 62 61 73 65 n which database
27140 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 20 5b a result of a [
27150 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
27160 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a t comes from..**
27170 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 The name of the
27180 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 database or tab
27190 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e le or column can
271a0 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a be returned as.
271b0 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d ** either a UTF-
271c0 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 8 or UTF-16 stri
271d0 6e 67 2e 20 20 54 68 65 20 5f 64 61 74 61 62 61 ng. The _databa
271e0 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 se_ routines ret
271f0 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 urn.** the datab
27200 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 ase name, the _t
27210 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 able_ routines r
27220 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 eturn the table
27230 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 name, and.** the
27240 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 origin_ routine
27250 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c s return the col
27260 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 umn name..** The
27270 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 returned string
27280 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 is valid until
27290 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
272a0 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 atement] is dest
272b0 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b royed.** using [
272c0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
272d0 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 ()] or until the
272e0 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f same informatio
272f0 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a n is requested.*
27300 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 * again in a dif
27310 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e ferent encoding.
27320 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73 .**.** The names
27330 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 returned are th
27340 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c e original un-al
27350 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 iased names of t
27360 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 he.** database,
27370 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d table, and colum
27380 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 n..**.** The fir
27390 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 st argument to t
273a0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c he following cal
273b0 6c 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 ls is a [prepare
273c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a d statement]..**
273d0 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 These functions
273e0 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 return informat
273f0 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 ion about the Nt
27400 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 h column returne
27410 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 d by.** the stat
27420 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 ement, where N i
27430 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e s the second fun
27440 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a ction argument..
27450 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74 68 **.** If the Nth
27460 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 column returned
27470 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e by the statemen
27480 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 t is an expressi
27490 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 on or.** subquer
274a0 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 y and is not a c
274b0 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 olumn value, the
274c0 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 n all of these f
274d0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a unctions return.
274e0 2a 2a 20 4e 55 4c 4c 2e 20 20 54 68 65 73 65 20 ** NULL. These
274f0 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c routine might al
27500 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 so return NULL i
27510 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 f a memory alloc
27520 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f ation error.** o
27530 63 63 75 72 73 2e 20 20 4f 74 68 65 72 77 69 73 ccurs. Otherwis
27540 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 e, they return t
27550 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 he name of the a
27560 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 ttached database
27570 2c 20 74 61 62 6c 65 0a 2a 2a 20 61 6e 64 20 63 , table.** and c
27580 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 olumn that query
27590 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 result column w
275a0 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f as extracted fro
275b0 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 68 m..**.** As with
275c0 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 all other SQLit
275d0 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 70 6f e APIs, those po
275e0 73 74 66 69 78 65 64 20 77 69 74 68 20 22 31 36 stfixed with "16
275f0 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d " return.** UTF-
27600 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 16 encoded strin
27610 67 73 2c 20 74 68 65 20 6f 74 68 65 72 20 66 75 gs, the other fu
27620 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 nctions return U
27630 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a TF-8. {END}.**.*
27640 2a 20 54 68 65 73 65 20 41 50 49 73 20 61 72 65 * These APIs are
27650 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 only available
27660 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 if the library w
27670 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 as compiled with
27680 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
27690 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 ENABLE_COLUMN_ME
276a0 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f TADATA] C-prepro
276b0 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 cessor symbol de
276c0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 fined..**.** {A1
276d0 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77 6f 20 3751}.** If two
276e0 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 or more threads
276f0 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 call one or more
27700 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e of these routin
27710 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 es against the s
27720 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 ame.** prepared
27730 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f statement and co
27740 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 lumn at the same
27750 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 time then the r
27760 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e esults are.** un
27770 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 defined..**.** I
27780 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
27790 20 7b 48 31 33 37 34 31 7d 20 54 68 65 20 5b 73 {H13741} The [s
277a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 qlite3_column_da
277b0 74 61 62 61 73 65 5f 6e 61 6d 65 28 53 2c 4e 29 tabase_name(S,N)
277c0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ] interface retu
277d0 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 rns either.**
277e0 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 the UTF-8
277f0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
27800 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 name of the dat
27810 61 62 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 abase from which
27820 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
27830 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 Nth result colu
27840 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 mn of the [prepa
27850 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
27860 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 0a 2a is extracted,.*
27870 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 * or NU
27880 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f LL if the Nth co
27890 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 lumn of S is a g
278a0 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f eneral expressio
278b0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 n.** or
278c0 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c if unable to al
278d0 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f locate memory to
278e0 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e store the name.
278f0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 32 7d 20 .**.** {H13742}
27900 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c The [sqlite3_col
27910 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d umn_database_nam
27920 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 e16(S,N)] interf
27930 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 ace returns eith
27940 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 er.** t
27950 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 he UTF-16 native
27960 20 62 79 74 65 20 6f 72 64 65 72 20 7a 65 72 6f byte order zero
27970 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 -terminated name
27980 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
27990 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f .** fro
279a0 6d 20 77 68 69 63 68 20 74 68 65 20 4e 74 68 20 m which the Nth
279b0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 result column of
279c0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
279d0 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 0a 2a tatement] S is.*
279e0 2a 20 20 20 20 20 20 20 20 20 20 65 78 74 72 61 * extra
279f0 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 cted, or NULL if
27a00 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
27a10 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 of S is a genera
27a20 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 l expression.**
27a30 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 or if u
27a40 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 nable to allocat
27a50 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 e memory to stor
27a60 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a e the name..**.*
27a70 2a 20 7b 48 31 33 37 34 33 7d 20 54 68 65 20 5b * {H13743} The [
27a80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
27a90 61 62 6c 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 able_name(S,N)]
27aa0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
27ab0 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 s either.**
27ac0 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a the UTF-8 z
27ad0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e ero-terminated n
27ae0 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 ame of the table
27af0 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 0a from which the.
27b00 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 ** Nth
27b10 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 result column of
27b20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
27b30 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 tatement] S is e
27b40 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 xtracted,.**
27b50 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 or NULL if
27b60 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
27b70 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 of S is a genera
27b80 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 l expression.**
27b90 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 or if u
27ba0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 nable to allocat
27bb0 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 e memory to stor
27bc0 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a e the name..**.*
27bd0 2a 20 7b 48 31 33 37 34 34 7d 20 54 68 65 20 5b * {H13744} The [
27be0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
27bf0 61 62 6c 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 able_name16(S,N)
27c00 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ] interface retu
27c10 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 rns either.**
27c20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 the UTF-1
27c30 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 6 native byte or
27c40 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 der zero-termina
27c50 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 ted name of the
27c60 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 table.**
27c70 20 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 from which the
27c80 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 Nth result colu
27c90 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 mn of the [prepa
27ca0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
27cb0 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 is.**
27cc0 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 extracted, or NU
27cd0 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f LL if the Nth co
27ce0 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 lumn of S is a g
27cf0 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f eneral expressio
27d00 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 n.** or
27d10 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c if unable to al
27d20 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f locate memory to
27d30 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e store the name.
27d40 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 35 7d 20 .**.** {H13745}
27d50 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c The [sqlite3_col
27d60 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 umn_origin_name(
27d70 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 S,N)] interface
27d80 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a returns either.*
27d90 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 * the U
27da0 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e TF-8 zero-termin
27db0 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 ated name of the
27dc0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 66 72 table column fr
27dd0 6f 6d 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 om which the.**
27de0 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73 Nth res
27df0 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 ult column of th
27e00 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
27e10 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74 72 ement] S is extr
27e20 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 acted,.**
27e30 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 or NULL if th
27e40 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 e Nth column of
27e50 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 S is a general e
27e60 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 xpression.**
27e70 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62 or if unab
27e80 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d le to allocate m
27e90 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74 emory to store t
27ea0 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b he name..**.** {
27eb0 48 31 33 37 34 36 7d 20 54 68 65 20 5b 73 71 6c H13746} The [sql
27ec0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 ite3_column_orig
27ed0 69 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 in_name16(S,N)]
27ee0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
27ef0 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 s either.**
27f00 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20 the UTF-16
27f10 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
27f20 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 r zero-terminate
27f30 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 d name of the ta
27f40 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ble.**
27f50 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63 column from whic
27f60 68 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 h the Nth result
27f70 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a column of the.*
27f80 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 * [prep
27f90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
27fa0 53 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 20 S is extracted,
27fb0 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e or NULL if the N
27fc0 74 68 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20 th column.**
27fd0 20 20 20 20 20 20 6f 66 20 53 20 69 73 20 61 20 of S is a
27fe0 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 general expressi
27ff0 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 on or if unable
28000 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f to allocate memo
28010 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 ry.** t
28020 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 o store the name
28030 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 38 7d ..**.** {H13748}
28040 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 The return valu
28050 65 73 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 es from.**
28060 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c [sqlite3_col
28070 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d umn_database_nam
28080 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 e | column metad
28090 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a ata interfaces].
280a0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20 ** are
280b0 76 61 6c 69 64 20 66 6f 72 20 74 68 65 20 6c 69 valid for the li
280c0 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20 5b 70 fetime of the [p
280d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
280e0 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f t].** o
280f0 72 20 75 6e 74 69 6c 20 74 68 65 20 65 6e 63 6f r until the enco
28100 64 69 6e 67 20 69 73 20 63 68 61 6e 67 65 64 20 ding is changed
28110 62 79 20 61 6e 6f 74 68 65 72 20 6d 65 74 61 64 by another metad
28120 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ata.**
28130 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 66 interface call f
28140 6f 72 20 74 68 65 20 73 61 6d 65 20 70 72 65 70 or the same prep
28150 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 ared statement a
28160 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a nd column..**.**
28170 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a ASSUMPTIONS:.**
28180 0a 2a 2a 20 7b 41 31 33 37 35 31 7d 20 49 66 20 .** {A13751} If
28190 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 two or more thre
281a0 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 ads call one or
281b0 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 more.**
281c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
281d0 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c _database_name |
281e0 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 column metadata
281f0 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 interfaces].**
28200 20 20 20 20 20 20 20 20 20 66 6f 72 20 74 68 65 for the
28210 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 same [prepared
28220 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 statement] and r
28230 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 esult column.**
28240 20 20 20 20 20 20 20 20 20 61 74 20 74 68 65 20 at the
28250 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 same time then t
28260 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 he results are u
28270 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e ndefined..*/.con
28280 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
28290 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 _column_database
282a0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 _name(sqlite3_st
282b0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 mt*,int);.const
282c0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
282d0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 lumn_database_na
282e0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d me16(sqlite3_stm
282f0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 t*,int);.const c
28300 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c har *sqlite3_col
28310 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 umn_table_name(s
28320 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
28330 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
28340 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 qlite3_column_ta
28350 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 ble_name16(sqlit
28360 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 e3_stmt*,int);.c
28370 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
28380 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e e3_column_origin
28390 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 _name(sqlite3_st
283a0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 mt*,int);.const
283b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
283c0 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 lumn_origin_name
283d0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
283e0 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ,int);../*.** CA
283f0 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 PI3REF: Declared
28400 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 Datatype Of A Q
28410 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31 33 uery Result {H13
28420 37 36 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 760} <S10700>.**
28430 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 .** The first pa
28440 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 rameter is a [pr
28450 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
28460 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 ]..** If this st
28470 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 atement is a [SE
28480 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 LECT] statement
28490 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 and the Nth colu
284a0 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 mn of the.** ret
284b0 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 urned result set
284c0 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 of that [SELECT
284d0 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c ] is a table col
284e0 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 umn (not an.** e
284f0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 xpression or sub
28500 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 query) then the
28510 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 declared type of
28520 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f the table.** co
28530 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 lumn is returned
28540 2e 20 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f . If the Nth co
28550 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 lumn of the resu
28560 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 lt set is an.**
28570 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 expression or su
28580 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e bquery, then a N
28590 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 ULL pointer is r
285a0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 eturned..** The
285b0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 returned string
285c0 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 is always UTF-8
285d0 65 6e 63 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a 2a encoded. {END}.*
285e0 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 *.** For example
285f0 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 , given the data
28600 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a base schema:.**.
28610 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 ** CREATE TABLE
28620 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a t1(c1 VARIANT);.
28630 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f **.** and the fo
28640 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e llowing statemen
28650 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 t to be compiled
28660 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 :.**.** SELECT c
28670 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 1 + 1, c1 FROM t
28680 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 1;.**.** this ro
28690 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 utine would retu
286a0 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 rn the string "V
286b0 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 ARIANT" for the
286c0 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a second result.**
286d0 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 column (i==1),
286e0 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 and a NULL point
286f0 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 er for the first
28700 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 result column (
28710 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c i==0)..**.** SQL
28720 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 ite uses dynamic
28730 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 run-time typing
28740 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75 . So just becau
28750 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 se a column.** i
28760 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f s declared to co
28770 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c ntain a particul
28780 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 ar type does not
28790 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a mean that the.*
287a0 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e * data stored in
287b0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 that column is
287c0 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 of the declared
287d0 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 type. SQLite is
287e0 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 .** strongly typ
287f0 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 ed, but the typi
28800 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f ng is dynamic no
28810 74 20 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a t static. Type.
28820 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 ** is associated
28830 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c with individual
28840 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 values, not wit
28850 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 h the containers
28860 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 .** used to hold
28870 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a those values..*
28880 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
28890 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36 31 7d 20 .**.** {H13761}
288a0 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 A successful ca
288b0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ll to [sqlite3_c
288c0 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53 olumn_decltype(S
288d0 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 0a 2a ,N)] returns a.*
288e0 2a 20 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f * zero
288f0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d -terminated UTF-
28900 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 8 string contain
28910 69 6e 67 20 74 68 65 20 64 65 63 6c 61 72 65 64 ing the declared
28920 20 64 61 74 61 74 79 70 65 0a 2a 2a 20 20 20 20 datatype.**
28930 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 74 61 of the ta
28940 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 ble column that
28950 61 70 70 65 61 72 73 20 61 73 20 74 68 65 20 4e appears as the N
28960 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 th column (numbe
28970 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 red.**
28980 20 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 from 0) of the
28990 72 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68 result set to th
289a0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
289b0 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 ement] S..**.**
289c0 7b 48 31 33 37 36 32 7d 20 20 41 20 73 75 63 63 {H13762} A succ
289d0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b essful call to [
289e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
289f0 65 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d 0a ecltype16(S,N)].
28a00 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74 ** ret
28a10 75 72 6e 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d urns a zero-term
28a20 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20 6e 61 inated UTF-16 na
28a30 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 tive byte order
28a40 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 string.**
28a50 20 20 20 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 containing t
28a60 68 65 20 64 65 63 6c 61 72 65 64 20 64 61 74 61 he declared data
28a70 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c type of the tabl
28a80 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70 e column that ap
28a90 70 65 61 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 pears.**
28aa0 20 20 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f as the Nth co
28ab0 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20 66 lumn (numbered f
28ac0 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65 rom 0) of the re
28ad0 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65 0a sult set to the.
28ae0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70 72 ** [pr
28af0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
28b00 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 ] S..**.** {H137
28b10 36 33 7d 20 20 49 66 20 4e 20 69 73 20 6c 65 73 63} If N is les
28b20 73 20 74 68 61 6e 20 30 20 6f 72 20 4e 20 69 73 s than 0 or N is
28b30 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 6f 72 greater than or
28b40 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 20 20 20 equal to.**
28b50 20 20 20 20 20 20 20 74 68 65 20 6e 75 6d 62 65 the numbe
28b60 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 r of columns in
28b70 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
28b80 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20 atement] S,.**
28b90 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 74 or if t
28ba0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 he Nth column of
28bb0 20 53 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 S is an express
28bc0 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 20 ion or subquery
28bd0 72 61 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 rather.**
28be0 20 20 20 20 74 68 61 6e 20 61 20 74 61 62 6c 65 than a table
28bf0 20 63 6f 6c 75 6d 6e 2c 20 6f 72 20 69 66 20 61 column, or if a
28c00 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
28c10 6f 6e 20 66 61 69 6c 75 72 65 0a 2a 2a 20 20 20 on failure.**
28c20 20 20 20 20 20 20 20 20 6f 63 63 75 72 73 20 64 occurs d
28c30 75 72 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20 63 uring encoding c
28c40 6f 6e 76 65 72 73 69 6f 6e 73 2c 20 74 68 65 6e onversions, then
28c50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 61 .** ca
28c60 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
28c70 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 column_decltype(
28c80 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 S,N)] or.**
28c90 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 [sqlite3_c
28ca0 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 olumn_decltype16
28cb0 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e 20 4e 55 (S,N)] return NU
28cc0 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 LL..*/.const cha
28cd0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d r *sqlite3_colum
28ce0 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 n_decltype(sqlit
28cf0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 e3_stmt*,int);.c
28d00 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
28d10 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 e3_column_declty
28d20 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d pe16(sqlite3_stm
28d30 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 t*,int);../*.**
28d40 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 CAPI3REF: Evalua
28d50 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d te An SQL Statem
28d60 65 6e 74 20 7b 48 31 33 32 30 30 7d 20 3c 53 31 ent {H13200} <S1
28d70 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 0000>.**.** Afte
28d80 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 r a [prepared st
28d90 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 atement] has bee
28da0 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 n prepared using
28db0 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 either.** [sqli
28dc0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
28dd0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 ] or [sqlite3_pr
28de0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 epare16_v2()] or
28df0 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 one of the lega
28e00 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 cy.** interfaces
28e10 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
28e20 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 e()] or [sqlite3
28e30 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 _prepare16()], t
28e40 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 his function.**
28e50 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f must be called o
28e60 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 ne or more times
28e70 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 to evaluate the
28e80 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a statement..**.*
28e90 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 * The details of
28ea0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 the behavior of
28eb0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 the sqlite3_ste
28ec0 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 p() interface de
28ed0 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 pend.** on wheth
28ee0 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 er the statement
28ef0 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 was prepared us
28f00 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 ing the newer "v
28f10 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 2" interface.**
28f20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
28f30 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 _v2()] and [sqli
28f40 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
28f50 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 ()] or the older
28f60 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 legacy.** inter
28f70 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 face [sqlite3_pr
28f80 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 epare()] and [sq
28f90 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
28fa0 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 )]. The use of
28fb0 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 the.** new "v2"
28fc0 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 interface is rec
28fd0 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 ommended for new
28fe0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 applications bu
28ff0 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 t the legacy.**
29000 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 interface will c
29010 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 ontinue to be su
29020 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 pported..**.** I
29030 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 n the legacy int
29040 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 erface, the retu
29050 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 rn value will be
29060 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f either [SQLITE_
29070 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 BUSY],.** [SQLIT
29080 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 E_DONE], [SQLITE
29090 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 _ROW], [SQLITE_E
290a0 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 RROR], or [SQLIT
290b0 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 E_MISUSE]..** Wi
290c0 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 th the "v2" inte
290d0 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 rface, any of th
290e0 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 e other [result
290f0 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 codes] or.** [ex
29100 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
29110 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 des] might be re
29120 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a turned as well..
29130 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 **.** [SQLITE_BU
29140 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 SY] means that t
29150 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 he database engi
29160 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f ne was unable to
29170 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 acquire the.**
29180 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 database locks i
29190 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 t needs to do it
291a0 73 20 6a 6f 62 2e 20 20 49 66 20 74 68 65 20 73 s job. If the s
291b0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 tatement is a [C
291c0 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 OMMIT].** or occ
291d0 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 urs outside of a
291e0 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 n explicit trans
291f0 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 action, then you
29200 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a can retry the.*
29210 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 * statement. If
29220 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
29230 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d s not a [COMMIT]
29240 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 and occurs with
29250 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 in a.** explicit
29260 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 transaction the
29270 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c n you should rol
29280 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 lback the transa
29290 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 ction before.**
292a0 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a continuing..**.*
292b0 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 * [SQLITE_DONE]
292c0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 means that the s
292d0 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e tatement has fin
292e0 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a ished executing.
292f0 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e ** successfully.
29300 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 sqlite3_step()
29310 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 should not be c
29320 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 alled again on t
29330 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d his virtual.** m
29340 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 achine without f
29350 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 irst calling [sq
29360 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 lite3_reset()] t
29370 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 o reset the virt
29380 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 ual.** machine b
29390 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 ack to its initi
293a0 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 al state..**.**
293b0 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 If the SQL state
293c0 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 ment being execu
293d0 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 ted returns any
293e0 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 data, then [SQLI
293f0 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 TE_ROW].** is re
29400 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 turned each time
29410 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 a new row of da
29420 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 ta is ready for
29430 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 processing by th
29440 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 e.** caller. The
29450 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 values may be a
29460 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 ccessed using th
29470 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 e [column access
29480 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 functions]..**
29490 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 sqlite3_step() i
294a0 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 s called again t
294b0 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e o retrieve the n
294c0 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e ext row of data.
294d0 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 .**.** [SQLITE_E
294e0 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 RROR] means that
294f0 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f a run-time erro
29500 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e r (such as a con
29510 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 straint.** viola
29520 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 tion) has occurr
29530 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 ed. sqlite3_ste
29540 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 p() should not b
29550 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f e called again o
29560 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 n.** the VM. Mor
29570 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 e information ma
29580 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 y be found by ca
29590 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 lling [sqlite3_e
295a0 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 rrmsg()]..** Wit
295b0 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 h the legacy int
295c0 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 erface, a more s
295d0 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f pecific error co
295e0 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c de (for example,
295f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 .** [SQLITE_INTE
29600 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f RRUPT], [SQLITE_
29610 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 SCHEMA], [SQLITE
29620 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 _CORRUPT], and s
29630 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 o forth).** can
29640 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 be obtained by c
29650 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
29660 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a reset()] on the.
29670 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
29680 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65 tement]. In the
29690 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c "v2" interface,
296a0 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 .** the more spe
296b0 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 cific error code
296c0 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 is returned dir
296d0 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 ectly by sqlite3
296e0 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b _step()..**.** [
296f0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d SQLITE_MISUSE] m
29700 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 eans that the th
29710 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 is routine was c
29720 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 alled inappropri
29730 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 ately..** Perhap
29740 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 s it was called
29750 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 on a [prepared s
29760 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 tatement] that h
29770 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 as.** already be
29780 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 en [sqlite3_fina
29790 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 lize | finalized
297a0 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 ] or on one that
297b0 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 had.** previous
297c0 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c ly returned [SQL
297d0 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 ITE_ERROR] or [S
297e0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 QLITE_DONE]. Or
297f0 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 it could.** be
29800 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 the case that th
29810 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 e same database
29820 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 connection is be
29830 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 ing used by two
29840 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 or.** more threa
29850 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d ds at the same m
29860 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a oment in time..*
29870 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e *.** <b>Goofy In
29880 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f terface Alert:</
29890 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 b> In the legacy
298a0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 interface, the
298b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a sqlite3_step().*
298c0 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 * API always ret
298d0 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 urns a generic e
298e0 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 rror code, [SQLI
298f0 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f TE_ERROR], follo
29900 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f wing any.** erro
29910 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 r other than [SQ
29920 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b LITE_BUSY] and [
29930 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 SQLITE_MISUSE].
29940 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a You must call.*
29950 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 * [sqlite3_reset
29960 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
29970 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f finalize()] in o
29980 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 rder to find one
29990 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 of the.** speci
299a0 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 fic [error codes
299b0 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 ] that better de
299c0 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f scribes the erro
299d0 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 r..** We admit t
299e0 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f hat this is a go
299f0 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 ofy design. The
29a00 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 problem has bee
29a10 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 n fixed.** with
29a20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
29a30 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 ce. If you prep
29a40 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 are all of your
29a50 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a SQL statements.*
29a60 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b * using either [
29a70 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
29a80 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 v2()] or [sqlite
29a90 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
29aa0 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 ] instead.** of
29ab0 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 the legacy [sqli
29ac0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 te3_prepare()] a
29ad0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 nd [sqlite3_prep
29ae0 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 are16()] interfa
29af0 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ces,.** then the
29b00 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b more specific [
29b10 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 error codes] are
29b20 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 returned direct
29b30 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 ly.** by sqlite3
29b40 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 _step(). The us
29b50 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e e of the "v2" in
29b60 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d terface is recom
29b70 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e mended..**.** IN
29b80 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
29b90 7b 48 31 33 32 30 32 7d 20 20 49 66 20 74 68 65 {H13202} If the
29ba0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
29bb0 6d 65 6e 74 5d 20 53 20 69 73 20 72 65 61 64 79 ment] S is ready
29bc0 20 74 6f 20 62 65 20 72 75 6e 2c 20 74 68 65 6e to be run, then
29bd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 .** [s
29be0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 qlite3_step(S)]
29bf0 61 64 76 61 6e 63 65 73 20 74 68 61 74 20 70 72 advances that pr
29c00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
29c10 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 20 20 20 20 until.**
29c20 20 20 20 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f completion o
29c30 72 20 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65 r until it is re
29c40 61 64 79 20 74 6f 20 72 65 74 75 72 6e 20 61 6e ady to return an
29c50 6f 74 68 65 72 20 72 6f 77 20 6f 66 20 74 68 65 other row of the
29c60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 .** re
29c70 73 75 6c 74 20 73 65 74 2c 20 6f 72 20 75 6e 74 sult set, or unt
29c80 69 6c 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 il an [sqlite3_i
29c90 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 nterrupt | inter
29ca0 72 75 70 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 rupt].**
29cb0 20 20 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 or a run-time
29cc0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a error occurs..*
29cd0 2a 0a 2a 2a 20 7b 48 31 35 33 30 34 7d 20 20 57 *.** {H15304} W
29ce0 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 hen a call to [s
29cf0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 qlite3_step(S)]
29d00 63 61 75 73 65 73 20 74 68 65 20 5b 70 72 65 70 causes the [prep
29d10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a ared statement].
29d20 2a 2a 20 20 20 20 20 20 20 20 20 20 20 53 20 74 ** S t
29d30 6f 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 o run to complet
29d40 69 6f 6e 2c 20 74 68 65 20 66 75 6e 63 74 69 6f ion, the functio
29d50 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 n returns [SQLIT
29d60 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b E_DONE]..**.** {
29d70 48 31 35 33 30 36 7d 20 20 57 68 65 6e 20 61 20 H15306} When a
29d80 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
29d90 5f 73 74 65 70 28 53 29 5d 20 73 74 6f 70 73 20 _step(S)] stops
29da0 62 65 63 61 75 73 65 20 69 74 20 69 73 20 72 65 because it is re
29db0 61 64 79 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 ady to.**
29dc0 20 20 20 20 72 65 74 75 72 6e 20 61 6e 6f 74 68 return anoth
29dd0 65 72 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 er row of the re
29de0 73 75 6c 74 20 73 65 74 2c 20 69 74 20 72 65 74 sult set, it ret
29df0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f 57 urns [SQLITE_ROW
29e00 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 38 ]..**.** {H15308
29e10 7d 20 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 } If a call to
29e20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
29e30 5d 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 6e 0a ] encounters an.
29e40 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 ** [sq
29e50 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 lite3_interrupt
29e60 7c 20 69 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 | interrupt] or
29e70 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 a run-time error
29e80 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 ,.** i
29e90 74 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 t returns an app
29ea0 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 63 ropriate error c
29eb0 6f 64 65 20 74 68 61 74 20 69 73 20 6e 6f 74 20 ode that is not
29ec0 6f 6e 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 one of.**
29ed0 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c [SQLITE_OK],
29ee0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 6f [SQLITE_ROW], o
29ef0 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e r [SQLITE_DONE].
29f00 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 31 30 7d 20 .**.** {H15310}
29f10 20 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f If an [sqlite3_
29f20 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 interrupt | inte
29f30 72 72 75 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d rrupt] or a run-
29f40 74 69 6d 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 time error.**
29f50 20 20 20 20 20 20 20 20 6f 63 63 75 72 73 20 64 occurs d
29f60 75 72 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 uring a call to
29f70 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
29f80 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 66 ].** f
29f90 6f 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 or a [prepared s
29fa0 74 61 74 65 6d 65 6e 74 5d 20 53 20 63 72 65 61 tatement] S crea
29fb0 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 ted using.**
29fc0 20 20 20 20 20 20 20 6c 65 67 61 63 79 20 69 6e legacy in
29fd0 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 terfaces [sqlite
29fe0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 3_prepare()] or.
29ff0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 ** [sq
2a000 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
2a010 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 75 6e )], then the fun
2a020 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 65 69 ction returns ei
2a030 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 ther.**
2a040 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d [SQLITE_ERROR]
2a050 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c , [SQLITE_BUSY],
2a060 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 or [SQLITE_MISU
2a070 53 45 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 SE]..*/.int sqli
2a080 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 te3_step(sqlite3
2a090 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 _stmt*);../*.**
2a0a0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 CAPI3REF: Number
2a0b0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 of columns in a
2a0c0 20 72 65 73 75 6c 74 20 73 65 74 20 7b 48 31 33 result set {H13
2a0d0 37 37 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 770} <S10700>.**
2a0e0 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74 68 65 20 .** Returns the
2a0f0 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c 75 65 73 number of values
2a100 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 in the current
2a110 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c row of the resul
2a120 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 t set..**.** INV
2a130 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
2a140 48 31 33 37 37 31 7d 20 20 41 66 74 65 72 20 61 H13771} After a
2a150 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
2a160 33 5f 73 74 65 70 28 53 29 5d 20 74 68 61 74 20 3_step(S)] that
2a170 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
2a180 52 4f 57 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 ROW],.**
2a190 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f the [sqlite3_
2a1a0 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 20 72 data_count(S)] r
2a1b0 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 outine will retu
2a1c0 72 6e 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 rn the same valu
2a1d0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 e.** a
2a1e0 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 s the [sqlite3_c
2a1f0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 olumn_count(S)]
2a200 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 function..**.**
2a210 7b 48 31 33 37 37 32 7d 20 20 41 66 74 65 72 20 {H13772} After
2a220 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
2a230 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 61 ] has returned a
2a240 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 ny value other t
2a250 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 han.**
2a260 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 [SQLITE_ROW] or
2a270 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 before [sqlite3
2a280 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 62 65 _step(S)] has be
2a290 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 en called on the
2a2a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70 .** [p
2a2b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2a2c0 74 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 t] for the first
2a2d0 20 74 69 6d 65 20 73 69 6e 63 65 20 69 74 20 77 time since it w
2a2e0 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 as.**
2a2f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2a300 20 7c 20 70 72 65 70 61 72 65 64 5d 20 6f 72 20 | prepared] or
2a310 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 20 7c [sqlite3_reset |
2a320 20 72 65 73 65 74 5d 2c 0a 2a 2a 20 20 20 20 20 reset],.**
2a330 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 the [sqlit
2a340 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 e3_data_count(S)
2a350 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ] routine return
2a360 73 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 s zero..*/.int s
2a370 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e qlite3_data_coun
2a380 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a t(sqlite3_stmt *
2a390 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 pStmt);../*.** C
2a3a0 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 API3REF: Fundame
2a3b0 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 20 7b ntal Datatypes {
2a3c0 48 31 30 32 36 35 7d 20 3c 53 31 30 31 31 30 3e H10265} <S10110>
2a3d0 3c 53 31 30 31 32 30 3e 0a 2a 2a 20 4b 45 59 57 <S10120>.** KEYW
2a3e0 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 ORDS: SQLITE_TEX
2a3f0 54 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 36 36 7d T.**.** {H10266}
2a400 20 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 Every value in
2a410 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f SQLite has one o
2a420 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 f five fundament
2a430 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a al datatypes:.**
2a440 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
2a450 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 64-bit signed i
2a460 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 nteger.** <li> 6
2a470 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 4-bit IEEE float
2a480 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 ing point number
2a490 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a .** <li> string.
2a4a0 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 ** <li> BLOB.**
2a4b0 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 <li> NULL.** </u
2a4c0 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 l> {END}.**.** T
2a4d0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 hese constants a
2a4e0 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 re codes for eac
2a4f0 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 h of those types
2a500 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ..**.** Note tha
2a510 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 t the SQLITE_TEX
2a520 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 T constant was a
2a530 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 lso used in SQLi
2a540 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 te version 2.**
2a550 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 for a completely
2a560 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 different meani
2a570 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 ng. Software th
2a580 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 at links against
2a590 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 both.** SQLite
2a5a0 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 version 2 and SQ
2a5b0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 Lite version 3 s
2a5c0 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 hould use SQLITE
2a5d0 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 3_TEXT, not.** S
2a5e0 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 QLITE_TEXT..*/.#
2a5f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e define SQLITE_IN
2a600 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 TEGER 1.#define
2a610 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 SQLITE_FLOAT
2a620 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
2a630 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 E_BLOB 4.#de
2a640 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c fine SQLITE_NULL
2a650 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 5.#ifdef SQ
2a660 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 LITE_TEXT.# unde
2a670 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 f SQLITE_TEXT.#e
2a680 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c lse.# define SQL
2a690 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 ITE_TEXT 3.#
2a6a0 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 endif.#define SQ
2a6b0 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 LITE3_TEXT 3
2a6c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2a6d0 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 : Result Values
2a6e0 46 72 6f 6d 20 41 20 51 75 65 72 79 20 7b 48 31 From A Query {H1
2a6f0 33 38 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 3800} <S10700>.*
2a700 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c * KEYWORDS: {col
2a710 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 umn access funct
2a720 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ions}.**.** Thes
2a730 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 e routines form
2a740 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 20 the "result set
2a750 71 75 65 72 79 22 20 69 6e 74 65 72 66 61 63 65 query" interface
2a760 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f ..**.** These ro
2a770 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e utines return in
2a780 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 formation about
2a790 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 a single column
2a7a0 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a of the current.*
2a7b0 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 * result row of
2a7c0 61 20 71 75 65 72 79 2e 20 20 49 6e 20 65 76 65 a query. In eve
2a7d0 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 ry case the firs
2a7e0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 t argument is a
2a7f0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 pointer.** to th
2a800 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
2a810 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 ement] that is b
2a820 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 eing evaluated (
2a830 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d the [sqlite3_stm
2a840 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 t*].** that was
2a850 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 returned from [s
2a860 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
2a870 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 2()] or one of i
2a880 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 ts variants).**
2a890 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 and the second a
2a8a0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 rgument is the i
2a8b0 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 ndex of the colu
2a8c0 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 mn for which inf
2a8d0 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 ormation.** shou
2a8e0 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 ld be returned.
2a8f0 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f The leftmost co
2a900 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 lumn of the resu
2a910 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 lt set has the i
2a920 6e 64 65 78 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 ndex 0..**.** If
2a930 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
2a940 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 nt does not curr
2a950 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 ently point to a
2a960 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 valid row, or i
2a970 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 f the.** column
2a980 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 index is out of
2a990 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c range, the resul
2a9a0 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a t is undefined..
2a9b0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
2a9c0 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 s may only be ca
2a9d0 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f lled when the mo
2a9e0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 st recent call t
2a9f0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 o.** [sqlite3_st
2aa00 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e ep()] has return
2aa10 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 ed [SQLITE_ROW]
2aa20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b and neither.** [
2aa30 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
2aa40 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 nor [sqlite3_fi
2aa50 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 nalize()] have b
2aa60 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 een called subse
2aa70 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 quently..** If a
2aa80 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 ny of these rout
2aa90 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 ines are called
2aaa0 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 after [sqlite3_r
2aab0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 eset()] or.** [s
2aac0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2aad0 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c )] or after [sql
2aae0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 ite3_step()] has
2aaf0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d returned.** som
2ab00 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 ething other tha
2ab10 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 n [SQLITE_ROW],
2ab20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 the results are
2ab30 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 undefined..** If
2ab40 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
2ab50 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 ] or [sqlite3_re
2ab60 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 set()] or [sqlit
2ab70 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a e3_finalize()].*
2ab80 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f * are called fro
2ab90 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 m a different th
2aba0 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f read while any o
2abb0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
2abc0 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c .** are pending,
2abd0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 then the result
2abe0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e s are undefined.
2abf0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
2ac00 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 e3_column_type()
2ac10 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
2ac20 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
2ac30 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 INTEGER | dataty
2ac40 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 pe code] for the
2ac50 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 initial data ty
2ac60 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 pe.** of the res
2ac70 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 ult column. The
2ac80 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 returned value
2ac90 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 is one of [SQLIT
2aca0 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b E_INTEGER],.** [
2acb0 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b SQLITE_FLOAT], [
2acc0 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 SQLITE_TEXT], [S
2acd0 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 QLITE_BLOB], or
2ace0 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 [SQLITE_NULL].
2acf0 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 The value.** ret
2ad00 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
2ad10 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 _column_type() i
2ad20 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 s only meaningfu
2ad30 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 l if no type.**
2ad40 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 conversions have
2ad50 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73 occurred as des
2ad60 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 cribed below. A
2ad70 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 fter a type conv
2ad80 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 ersion,.** the v
2ad90 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 alue returned by
2ada0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2adb0 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 type() is undefi
2adc0 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 ned. Future.**
2add0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
2ade0 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 te may change th
2adf0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 e behavior of sq
2ae00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 lite3_column_typ
2ae10 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 e().** following
2ae20 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 a type conversi
2ae30 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 on..**.** If the
2ae40 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f result is a BLO
2ae50 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e B or UTF-8 strin
2ae60 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 g then the sqlit
2ae70 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
2ae80 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 ).** routine ret
2ae90 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
2aea0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 of bytes in that
2aeb0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e BLOB or string.
2aec0 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c .** If the resul
2aed0 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 t is a UTF-16 st
2aee0 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 ring, then sqlit
2aef0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
2af00 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 ) converts.** th
2af10 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d e string to UTF-
2af20 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 8 and then retur
2af30 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
2af40 20 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 bytes..** If th
2af50 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 e result is a nu
2af60 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e meric value then
2af70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2af80 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 bytes() uses.**
2af90 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 [sqlite3_snprint
2afa0 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 f()] to convert
2afb0 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 that value to a
2afc0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 UTF-8 string and
2afd0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 returns.** the
2afe0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
2aff0 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a in that string..
2b000 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 ** The value ret
2b010 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 urned does not i
2b020 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 nclude the zero
2b030 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 terminator at th
2b040 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 e end.** of the
2b050 73 74 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 string. For cla
2b060 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20 rity: the value
2b070 72 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 returned is the
2b080 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 number of.** byt
2b090 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 es in the string
2b0a0 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 , not the number
2b0b0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a of characters..
2b0c0 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 20 72 65 **.** Strings re
2b0d0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 turned by sqlite
2b0e0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 3_column_text()
2b0f0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 and sqlite3_colu
2b100 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 mn_text16(),.**
2b110 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e even empty strin
2b120 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a gs, are always z
2b130 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 ero terminated.
2b140 20 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 The return.** v
2b150 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 alue from sqlite
2b160 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 3_column_blob()
2b170 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 for a zero-lengt
2b180 68 20 42 4c 4f 42 20 69 73 20 61 6e 20 61 72 62 h BLOB is an arb
2b190 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 itrary.** pointe
2b1a0 72 2c 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e r, possibly even
2b1b0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
2b1c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
2b1d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
2b1e0 36 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 6() routine is s
2b1f0 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 imilar to sqlite
2b200 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
2b210 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74 .** but leaves t
2b220 68 65 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46 he result in UTF
2b230 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 -16 in native by
2b240 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 te order instead
2b250 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 54 68 of UTF-8..** Th
2b260 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f e zero terminato
2b270 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 r is not include
2b280 64 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e d in this count.
2b290 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a 65 63 .**.** The objec
2b2a0 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 t returned by [s
2b2b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 qlite3_column_va
2b2c0 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 lue()] is an.**
2b2d0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c [unprotected sql
2b2e0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
2b2f0 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 ct. An unprotec
2b300 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
2b310 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 e object.** may
2b320 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 only be used wit
2b330 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f h [sqlite3_bind_
2b340 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 value()] and [sq
2b350 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c lite3_result_val
2b360 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 ue()]..** If the
2b370 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 [unprotected sq
2b380 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
2b390 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a ect returned by.
2b3a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ** [sqlite3_colu
2b3b0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 mn_value()] is u
2b3c0 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 sed in any other
2b3d0 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 way, including
2b3e0 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 calls.** to rout
2b3f0 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 ines like [sqlit
2b400 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c e3_value_int()],
2b410 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
2b420 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b text()],.** or [
2b430 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 sqlite3_value_by
2b440 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 tes()], then the
2b450 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 behavior is und
2b460 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 efined..**.** Th
2b470 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 ese routines att
2b480 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 empt to convert
2b490 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 the value where
2b4a0 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 46 6f appropriate. Fo
2b4b0 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 r.** example, if
2b4c0 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 the internal re
2b4d0 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 presentation is
2b4e0 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 FLOAT and a text
2b4f0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 result.** is re
2b500 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 quested, [sqlite
2b510 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 3_snprintf()] is
2b520 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 used internally
2b530 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a to perform the.
2b540 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 ** conversion au
2b550 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 tomatically. Th
2b560 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c e following tabl
2b570 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f e details the co
2b580 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 nversions.** tha
2b590 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a t are applied:.*
2b5a0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
2b5b0 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 >.** <table bord
2b5c0 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c er="1">.** <tr><
2b5d0 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e th> Internal<br>
2b5e0 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 Type <th> Reques
2b5f0 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e ted<br>Type <th>
2b600 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a Conversion.**.
2b610 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c ** <tr><td> NUL
2b620 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 L <td> INTEGE
2b630 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 R <td> Result
2b640 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e is 0.** <tr><td>
2b650 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 NULL <td>
2b660 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 FLOAT <td> Re
2b670 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c sult is 0.0.** <
2b680 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 tr><td> NULL
2b690 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 <td> TEXT
2b6a0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e <td> Result is N
2b6b0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c ULL pointer.** <
2b6c0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 tr><td> NULL
2b6d0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 <td> BLOB
2b6e0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e <td> Result is N
2b6f0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c ULL pointer.** <
2b700 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 tr><td> INTEGER
2b710 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 <td> FLOAT
2b720 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f <td> Convert fro
2b730 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f m integer to flo
2b740 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 at.** <tr><td> I
2b750 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 NTEGER <td> T
2b760 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 EXT <td> ASCI
2b770 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 I rendering of t
2b780 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 he integer.** <t
2b790 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 r><td> INTEGER
2b7a0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c <td> BLOB <
2b7b0 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 td> Same as INTE
2b7c0 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 GER->TEXT.** <tr
2b7d0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c ><td> FLOAT <
2b7e0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 td> INTEGER <t
2b7f0 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 d> Convert from
2b800 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 float to integer
2b810 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c .** <tr><td> FL
2b820 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 OAT <td> TEX
2b830 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 T <td> ASCII
2b840 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 rendering of the
2b850 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 float.** <tr><t
2b860 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e d> FLOAT <td>
2b870 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 BLOB <td>
2b880 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 Same as FLOAT->T
2b890 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 EXT.** <tr><td>
2b8a0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e TEXT <td> IN
2b8b0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 TEGER <td> Use
2b8c0 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c atoi().** <tr><
2b8d0 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 td> TEXT <td
2b8e0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e > FLOAT <td>
2b8f0 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c Use atof().** <
2b900 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 tr><td> TEXT
2b910 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 <td> BLOB
2b920 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a <td> No change.*
2b930 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 * <tr><td> BLOB
2b940 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 <td> INTEGER
2b950 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 <td> Convert
2b960 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 to TEXT then use
2b970 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c atoi().** <tr><
2b980 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 td> BLOB <td
2b990 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e > FLOAT <td>
2b9a0 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 Convert to TEXT
2b9b0 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 then use atof()
2b9c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c .** <tr><td> BL
2b9d0 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 OB <td> TEX
2b9e0 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 T <td> Add a
2b9f0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 zero terminator
2ba00 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 if needed.** </t
2ba10 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b able>.** </block
2ba20 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 quote>.**.** The
2ba30 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b table above mak
2ba40 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 es reference to
2ba50 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 standard C libra
2ba60 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f ry functions ato
2ba70 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 i().** and atof(
2ba80 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 ). SQLite does
2ba90 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 not really use t
2baa0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 hese functions.
2bab0 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f It has its.** o
2bac0 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e wn equivalent in
2bad0 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e ternal routines.
2bae0 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 The atoi() and
2baf0 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 atof() names ar
2bb00 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 e.** used in the
2bb10 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 table for brevi
2bb20 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 ty and because t
2bb30 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 hey are familiar
2bb40 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 to most.** C pr
2bb50 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a ogrammers..**.**
2bb60 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 Note that when
2bb70 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 type conversions
2bb80 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 occur, pointers
2bb90 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 returned by pri
2bba0 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 or.** calls to s
2bbb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
2bbc0 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f ob(), sqlite3_co
2bbd0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 lumn_text(), and
2bbe0 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 /or.** sqlite3_c
2bbf0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d olumn_text16() m
2bc00 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 ay be invalidate
2bc10 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 d..** Type conve
2bc20 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 rsions and point
2bc30 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 er invalidations
2bc40 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 might occur.**
2bc50 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 in the following
2bc60 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 cases:.**.** <u
2bc70 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 l>.** <li> The i
2bc80 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 nitial content i
2bc90 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c s a BLOB and sql
2bca0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
2bcb0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 () or.** sq
2bcc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
2bcd0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e t16() is called.
2bce0 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 A zero-termina
2bcf0 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 tor might.**
2bd00 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 need to be add
2bd10 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 ed to the string
2bd20 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 .</li>.** <li> T
2bd30 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 he initial conte
2bd40 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 nt is UTF-8 text
2bd50 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
2bd60 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 umn_bytes16() or
2bd70 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 .** sqlite3
2bd80 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
2bd90 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 is called. The
2bda0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 content must be
2bdb0 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 converted.**
2bdc0 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c to UTF-16.</l
2bdd0 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 i>.** <li> The i
2bde0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 nitial content i
2bdf0 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e s UTF-16 text an
2be00 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e d sqlite3_column
2be10 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 _bytes() or.**
2be20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 sqlite3_colu
2be30 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c mn_text() is cal
2be40 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e led. The conten
2be50 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 t must be conver
2be60 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 ted.** to U
2be70 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f TF-8.</li>.** </
2be80 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 ul>.**.** Conver
2be90 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 sions between UT
2bea0 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 F-16be and UTF-1
2beb0 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6le are always d
2bec0 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 one in place and
2bed0 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c do.** not inval
2bee0 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f idate a prior po
2bef0 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 inter, though of
2bf00 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 course the cont
2bf10 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 ent of the buffe
2bf20 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 r.** that the pr
2bf30 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e ior pointer poin
2bf40 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 ts to will have
2bf50 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 been modified.
2bf60 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f Other kinds.** o
2bf70 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 f conversion are
2bf80 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 done in place w
2bf90 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 hen it is possib
2bfa0 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 le, but sometime
2bfb0 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f s they.** are no
2bfc0 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 t possible and i
2bfd0 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 n those cases pr
2bfe0 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 ior pointers are
2bff0 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a invalidated..**
2c000 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 .** The safest a
2c010 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 nd easiest to re
2c020 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 member policy is
2c030 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 to invoke these
2c040 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 routines.** in
2c050 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f one of the follo
2c060 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a wing ways:.**.**
2c070 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 <ul>.** <li>sq
2c080 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
2c090 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 t() followed by
2c0a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2c0b0 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 ytes()</li>.**
2c0c0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 <li>sqlite3_colu
2c0d0 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 mn_blob() follow
2c0e0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f ed by sqlite3_co
2c0f0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 lumn_bytes()</li
2c100 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 >.** <li>sqlite
2c110 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
2c120 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 ) followed by sq
2c130 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2c140 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c es16()</li>.** <
2c150 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 /ul>.**.** In ot
2c160 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 her words, you s
2c170 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 hould call sqlit
2c180 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
2c190 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c ,.** sqlite3_col
2c1a0 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 umn_blob(), or s
2c1b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
2c1c0 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 xt16() first to
2c1d0 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 force the result
2c1e0 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 .** into the des
2c1f0 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 ired format, the
2c200 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 n invoke sqlite3
2c210 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 _column_bytes()
2c220 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f or.** sqlite3_co
2c230 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 lumn_bytes16() t
2c240 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 o find the size
2c250 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 of the result.
2c260 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 Do not mix calls
2c270 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 .** to sqlite3_c
2c280 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 olumn_text() or
2c290 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2c2a0 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 lob() with calls
2c2b0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 to.** sqlite3_c
2c2c0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c olumn_bytes16(),
2c2d0 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 and do not mix
2c2e0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
2c2f0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
2c300 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 .** with calls t
2c310 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e o sqlite3_column
2c320 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 _bytes()..**.**
2c330 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 The pointers ret
2c340 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 urned are valid
2c350 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e until a type con
2c360 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 version occurs a
2c370 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 s.** described a
2c380 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b bove, or until [
2c390 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
2c3a0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 or [sqlite3_rese
2c3b0 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 t()] or.** [sqli
2c3c0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
2c3d0 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 is called. The
2c3e0 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 memory space use
2c3f0 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 d to hold string
2c400 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 s.** and BLOBs i
2c410 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 s freed automati
2c420 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f cally. Do <b>no
2c430 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 t</b> pass the p
2c440 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 ointers returned
2c450 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c .** [sqlite3_col
2c460 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 umn_blob()], [sq
2c470 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
2c480 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a t()], etc. into.
2c490 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ** [sqlite3_free
2c4a0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 ()]..**.** If a
2c4b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
2c4c0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 n error occurs d
2c4d0 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 uring the evalua
2c4e0 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f tion of any.** o
2c4f0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
2c500 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 , a default valu
2c510 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 e is returned.
2c520 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 The default valu
2c530 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 e.** is either t
2c540 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 he integer 0, th
2c550 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 e floating point
2c560 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 number 0.0, or
2c570 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 a NULL.** pointe
2c580 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 r. Subsequent c
2c590 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
2c5a0 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c _errcode()] will
2c5b0 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 return.** [SQLI
2c5c0 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a TE_NOMEM]..**.**
2c5d0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
2c5e0 2a 2a 20 7b 48 31 33 38 30 33 7d 20 54 68 65 20 ** {H13803} The
2c5f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
2c600 62 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e 74 65 72 blob(S,N)] inter
2c610 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 face converts th
2c620 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 e.** Nt
2c630 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 h column in the
2c640 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 current row of t
2c650 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f he result set fo
2c660 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 r.** th
2c670 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
2c680 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 ement] S into a
2c690 42 4c 4f 42 20 61 6e 64 20 74 68 65 6e 20 72 65 BLOB and then re
2c6a0 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 turns a.**
2c6b0 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 pointer to t
2c6c0 68 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c he converted val
2c6d0 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30 ue..**.** {H1380
2c6e0 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6} The [sqlite3_
2c6f0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 53 2c 4e column_bytes(S,N
2c700 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
2c710 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 urns the.**
2c720 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 number of b
2c730 79 74 65 73 20 69 6e 20 74 68 65 20 42 4c 4f 42 ytes in the BLOB
2c740 20 6f 72 20 73 74 72 69 6e 67 20 28 65 78 63 6c or string (excl
2c750 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 usive of the.**
2c760 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 zero te
2c770 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 rminator on the
2c780 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 string) that was
2c790 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 returned by the
2c7a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 .** mos
2c7b0 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f t recent call to
2c7c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
2c7d0 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f 72 0a 2a _blob(S,N)] or.*
2c7e0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
2c7f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
2c800 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 S,N)]..**.** {H1
2c810 33 38 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 3809} The [sqlit
2c820 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
2c830 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 6(S,N)] interfac
2c840 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a e returns the.**
2c850 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 number
2c860 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 of bytes in the
2c870 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 string (exclusi
2c880 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 ve of the.**
2c890 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 zero termi
2c8a0 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 nator on the str
2c8b0 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65 ing) that was re
2c8c0 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a turned by the.**
2c8d0 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 most r
2c8e0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 ecent call to [s
2c8f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
2c900 78 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a xt16(S,N)]..**.*
2c910 2a 20 7b 48 31 33 38 31 32 7d 20 54 68 65 20 5b * {H13812} The [
2c920 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
2c930 6f 75 62 6c 65 28 53 2c 4e 29 5d 20 69 6e 74 65 ouble(S,N)] inte
2c940 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 rface converts t
2c950 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e he.** N
2c960 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 th column in the
2c970 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 current row of
2c980 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 the result set f
2c990 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 or the.**
2c9a0 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 [prepared sta
2c9b0 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 tement] S into a
2c9c0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 floating point
2c9d0 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 value and.**
2c9e0 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 returns a
2c9f0 63 6f 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c copy of that val
2ca00 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 31 ue..**.** {H1381
2ca10 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 5} The [sqlite3_
2ca20 63 6f 6c 75 6d 6e 5f 69 6e 74 28 53 2c 4e 29 5d column_int(S,N)]
2ca30 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 interface conve
2ca40 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 rts the.**
2ca50 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 Nth column i
2ca60 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f n the current ro
2ca70 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 w of the result
2ca80 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 set for the.**
2ca90 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 [prepare
2caa0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 d statement] S i
2cab0 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 nto a 64-bit sig
2cac0 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a ned integer and.
2cad0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 ** retu
2cae0 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 20 33 32 rns the lower 32
2caf0 20 62 69 74 73 20 6f 66 20 74 68 61 74 20 69 6e bits of that in
2cb00 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 teger..**.** {H1
2cb10 33 38 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 3818} The [sqlit
2cb20 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 e3_column_int64(
2cb30 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 S,N)] interface
2cb40 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 converts the.**
2cb50 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c Nth col
2cb60 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 umn in the curre
2cb70 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 nt row of the re
2cb80 73 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65 sult set for the
2cb90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 .** [pr
2cba0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2cbb0 5d 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 ] S into a 64-bi
2cbc0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 t signed integer
2cbd0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 and.**
2cbe0 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 returns a copy
2cbf0 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e of that integer.
2cc00 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 31 7d 20 .**.** {H13821}
2cc10 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c The [sqlite3_col
2cc20 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 20 69 umn_text(S,N)] i
2cc30 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 nterface convert
2cc40 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 s the.**
2cc50 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 Nth column in
2cc60 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 the current row
2cc70 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 of the result se
2cc80 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 t for.**
2cc90 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 the [prepared
2cca0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 statement] S int
2ccb0 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 o a zero-termina
2ccc0 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 ted UTF-8.**
2ccd0 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 string and
2cce0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
2ccf0 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e er to that strin
2cd00 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 34 g..**.** {H13824
2cd10 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 } The [sqlite3_c
2cd20 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e olumn_text16(S,N
2cd30 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e )] interface con
2cd40 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 verts the.**
2cd50 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e Nth column
2cd60 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 in the current
2cd70 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c row of the resul
2cd80 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a t set for the.**
2cd90 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 [prepa
2cda0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
2cdb0 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 into a zero-ter
2cdc0 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a minated 2-byte.*
2cdd0 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e * align
2cde0 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 ed UTF-16 native
2cdf0 20 62 79 74 65 20 6f 72 64 65 72 20 73 74 72 69 byte order stri
2ce00 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a ng and returns.*
2ce10 2a 20 20 20 20 20 20 20 20 20 20 61 20 70 6f 69 * a poi
2ce20 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 nter to that str
2ce30 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 ing..**.** {H138
2ce40 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 27} The [sqlite3
2ce50 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 53 2c 4e _column_type(S,N
2ce60 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
2ce70 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 urns.**
2ce80 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f one of [SQLITE_
2ce90 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 NULL], [SQLITE_I
2cea0 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 NTEGER], [SQLITE
2ceb0 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 _FLOAT],.**
2cec0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 [SQLITE_TEX
2ced0 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 T], or [SQLITE_B
2cee0 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 LOB] as appropri
2cef0 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 ate for.**
2cf00 20 20 20 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 the Nth colu
2cf10 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e mn in the curren
2cf20 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 t row of the res
2cf30 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 ult set for.**
2cf40 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 the [pre
2cf50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2cf60 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 33 S..**.** {H1383
2cf70 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 0} The [sqlite3_
2cf80 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 53 2c 4e column_value(S,N
2cf90 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
2cfa0 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 urns a.**
2cfb0 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e pointer to an
2cfc0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 [unprotected sq
2cfd0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
2cfe0 65 63 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 ect for the.**
2cff0 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 Nth colu
2d000 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e mn in the curren
2d010 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 t row of the res
2d020 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 ult set for.**
2d030 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 the [pre
2d040 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2d050 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 S..*/.const voi
2d060 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
2d070 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 n_blob(sqlite3_s
2d080 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
2d090 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c .int sqlite3_col
2d0a0 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 umn_bytes(sqlite
2d0b0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
2d0c0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f l);.int sqlite3_
2d0d0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 column_bytes16(s
2d0e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
2d0f0 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 t iCol);.double
2d100 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
2d110 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 ouble(sqlite3_st
2d120 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
2d130 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 int sqlite3_colu
2d140 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 mn_int(sqlite3_s
2d150 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
2d160 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 .sqlite3_int64 s
2d170 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e qlite3_column_in
2d180 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 t64(sqlite3_stmt
2d190 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f *, int iCol);.co
2d1a0 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 nst unsigned cha
2d1b0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d r *sqlite3_colum
2d1c0 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 n_text(sqlite3_s
2d1d0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
2d1e0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
2d1f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
2d200 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
2d210 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 , int iCol);.int
2d220 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2d230 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d type(sqlite3_stm
2d240 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 t*, int iCol);.s
2d250 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 qlite3_value *sq
2d260 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c lite3_column_val
2d270 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ue(sqlite3_stmt*
2d280 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a , int iCol);../*
2d290 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
2d2a0 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 stroy A Prepared
2d2b0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 Statement Objec
2d2c0 74 20 7b 48 31 33 33 30 30 7d 20 3c 53 37 30 33 t {H13300} <S703
2d2d0 30 30 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 00><S30100>.**.*
2d2e0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 * The sqlite3_fi
2d2f0 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f nalize() functio
2d300 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 n is called to d
2d310 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 elete a [prepare
2d320 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a d statement]..**
2d330 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e If the statemen
2d340 74 20 77 61 73 20 65 78 65 63 75 74 65 64 20 73 t was executed s
2d350 75 63 63 65 73 73 66 75 6c 6c 79 20 6f 72 20 6e uccessfully or n
2d360 6f 74 20 65 78 65 63 75 74 65 64 20 61 74 20 61 ot executed at a
2d370 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 49 ll, then.** SQLI
2d380 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 TE_OK is returne
2d390 64 2e 20 49 66 20 65 78 65 63 75 74 69 6f 6e 20 d. If execution
2d3a0 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 of the statement
2d3b0 20 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 0a failed then an.
2d3c0 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 ** [error code]
2d3d0 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 or [extended err
2d3e0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 or code] is retu
2d3f0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 rned..**.** This
2d400 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 routine can be
2d410 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f called at any po
2d420 69 6e 74 20 64 75 72 69 6e 67 20 74 68 65 20 65 int during the e
2d430 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a xecution of the.
2d440 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
2d450 74 65 6d 65 6e 74 5d 2e 20 20 49 66 20 74 68 65 tement]. If the
2d460 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 virtual machine
2d470 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 has not.** comp
2d480 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20 leted execution
2d490 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e when this routin
2d4a0 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 e is called, tha
2d4b0 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 t is like.** enc
2d4c0 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72 ountering an err
2d4d0 6f 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 or or an [sqlite
2d4e0 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 3_interrupt | in
2d4f0 74 65 72 72 75 70 74 5d 2e 0a 2a 2a 20 49 6e 63 terrupt]..** Inc
2d500 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 65 73 20 omplete updates
2d510 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 may be rolled ba
2d520 63 6b 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69 ck and transacti
2d530 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a ons canceled,.**
2d540 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 depending on th
2d550 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c e circumstances,
2d560 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72 and the.** [err
2d570 6f 72 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 or code] returne
2d580 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 d will be [SQLIT
2d590 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 E_ABORT]..**.**
2d5a0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
2d5b0 2a 20 7b 48 31 31 33 30 32 7d 20 54 68 65 20 5b * {H11302} The [
2d5c0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
2d5d0 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 (S)] interface d
2d5e0 65 73 74 72 6f 79 73 20 74 68 65 0a 2a 2a 20 20 estroys the.**
2d5f0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 [prepare
2d600 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 d statement] S a
2d610 6e 64 20 72 65 6c 65 61 73 65 73 20 61 6c 6c 0a nd releases all.
2d620 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f ** memo
2d630 72 79 20 61 6e 64 20 66 69 6c 65 20 72 65 73 6f ry and file reso
2d640 75 72 63 65 73 20 68 65 6c 64 20 62 79 20 74 68 urces held by th
2d650 61 74 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a at object..**.**
2d660 20 7b 48 31 31 33 30 34 7d 20 49 66 20 74 68 65 {H11304} If the
2d670 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c most recent cal
2d680 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 l to [sqlite3_st
2d690 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a ep(S)] for the.*
2d6a0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 * [prep
2d6b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2d6c0 53 20 72 65 74 75 72 6e 65 64 20 61 6e 20 65 72 S returned an er
2d6d0 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 ror,.**
2d6e0 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 then [sqlite3_f
2d6f0 69 6e 61 6c 69 7a 65 28 53 29 5d 20 72 65 74 75 inalize(S)] retu
2d700 72 6e 73 20 74 68 61 74 20 73 61 6d 65 20 65 72 rns that same er
2d710 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ror..*/.int sqli
2d720 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c te3_finalize(sql
2d730 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
2d740 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2d750 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 EF: Reset A Prep
2d760 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f ared Statement O
2d770 62 6a 65 63 74 20 7b 48 31 33 33 33 30 7d 20 3c bject {H13330} <
2d780 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S70300>.**.** Th
2d790 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 e sqlite3_reset(
2d7a0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 ) function is ca
2d7b0 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 lled to reset a
2d7c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2d7d0 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 ent].** object b
2d7e0 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 ack to its initi
2d7f0 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 al state, ready
2d800 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 to be re-execute
2d810 64 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c 20 73 74 d..** Any SQL st
2d820 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 atement variable
2d830 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 s that had value
2d840 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 s bound to them
2d850 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 using.** the [sq
2d860 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 lite3_bind_blob
2d870 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a | sqlite3_bind_*
2d880 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 () API] retain t
2d890 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 heir values..**
2d8a0 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 Use [sqlite3_cle
2d8b0 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 ar_bindings()] t
2d8c0 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 o reset the bind
2d8d0 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 ings..**.** {H11
2d8e0 33 33 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 332} The [sqlite
2d8f0 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 3_reset(S)] inte
2d900 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 rface resets the
2d910 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2d920 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20 ment] S.**
2d930 20 20 20 20 62 61 63 6b 20 74 6f 20 74 68 65 20 back to the
2d940 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 beginning of its
2d950 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 program..**.**
2d960 7b 48 31 31 33 33 34 7d 20 49 66 20 74 68 65 20 {H11334} If the
2d970 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c most recent call
2d980 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 to [sqlite3_ste
2d990 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a p(S)] for the.**
2d9a0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 [prepa
2d9b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
2d9c0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 returned [SQLIT
2d9d0 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 E_ROW] or [SQLIT
2d9e0 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20 20 20 E_DONE],.**
2d9f0 20 20 20 20 20 6f 72 20 69 66 20 5b 73 71 6c 69 or if [sqli
2da00 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 te3_step(S)] has
2da10 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 never before be
2da20 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a en called on S,.
2da30 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e ** then
2da40 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
2da50 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c S)] returns [SQL
2da60 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b ITE_OK]..**.** {
2da70 48 31 31 33 33 36 7d 20 49 66 20 74 68 65 20 6d H11336} If the m
2da80 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 ost recent call
2da90 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 to [sqlite3_step
2daa0 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 (S)] for the.**
2dab0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 [prepar
2dac0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 ed statement] S
2dad0 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 indicated an err
2dae0 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 or, then.**
2daf0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 [sqlite3_re
2db00 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 set(S)] returns
2db10 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b an appropriate [
2db20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a error code]..**.
2db30 2a 2a 20 7b 48 31 31 33 33 38 7d 20 54 68 65 20 ** {H11338} The
2db40 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 [sqlite3_reset(S
2db50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 )] interface doe
2db60 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 s not change the
2db70 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 values.**
2db80 20 20 20 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 of any [sqli
2db90 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 te3_bind_blob|bi
2dba0 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b ndings] on the [
2dbb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2dbc0 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 nt] S..*/.int sq
2dbd0 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 lite3_reset(sqli
2dbe0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
2dbf0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2dc00 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 F: Create Or Red
2dc10 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 efine SQL Functi
2dc20 6f 6e 73 20 7b 48 31 36 31 30 30 7d 20 3c 53 32 ons {H16100} <S2
2dc30 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 0200>.** KEYWORD
2dc40 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 S: {function cre
2dc50 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a ation routines}.
2dc60 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 ** KEYWORDS: {ap
2dc70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
2dc80 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a d SQL function}.
2dc90 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 ** KEYWORDS: {ap
2dca0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
2dcb0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d d SQL functions}
2dcc0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 74 77 6f .**.** These two
2dcd0 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c functions (coll
2dce0 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 ectively known a
2dcf0 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 s "function crea
2dd00 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a tion routines").
2dd10 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 ** are used to a
2dd20 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 dd SQL functions
2dd30 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f or aggregates o
2dd40 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 r to redefine th
2dd50 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 e behavior.** of
2dd60 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 existing SQL fu
2dd70 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 nctions or aggre
2dd80 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 gates. The only
2dd90 20 64 69 66 66 65 72 65 6e 63 65 20 62 65 74 77 difference betw
2dda0 65 65 6e 20 74 68 65 0a 2a 2a 20 74 77 6f 20 69 een the.** two i
2ddb0 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e s that the secon
2ddc0 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 d parameter, the
2ddd0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63 name of the (sc
2dde0 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f alar) function o
2ddf0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2c 20 r.** aggregate,
2de00 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 is encoded in UT
2de10 46 2d 38 20 66 6f 72 20 73 71 6c 69 74 65 33 5f F-8 for sqlite3_
2de20 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
2de30 29 20 61 6e 64 20 55 54 46 2d 31 36 0a 2a 2a 20 ) and UTF-16.**
2de40 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 for sqlite3_crea
2de50 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e te_function16().
2de60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 .**.** The first
2de70 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
2de80 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
2de90 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 ection] to which
2dea0 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 the SQL.** func
2deb0 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 tion is to be ad
2dec0 64 65 64 2e 20 20 49 66 20 61 20 73 69 6e 67 6c ded. If a singl
2ded0 65 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 6d e program uses m
2dee0 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 ore than one dat
2def0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 abase.** connect
2df00 69 6f 6e 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 ion internally,
2df10 74 68 65 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f then SQL functio
2df20 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 ns must be added
2df30 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 20 74 6f individually to
2df40 0a 2a 2a 20 65 61 63 68 20 64 61 74 61 62 61 73 .** each databas
2df50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a e connection..**
2df60 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 .** The second p
2df70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 arameter is the
2df80 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 name of the SQL
2df90 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 function to be c
2dfa0 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 reated or.** red
2dfb0 65 66 69 6e 65 64 2e 20 20 54 68 65 20 6c 65 6e efined. The len
2dfc0 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 gth of the name
2dfd0 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 is limited to 25
2dfe0 35 20 62 79 74 65 73 2c 20 65 78 63 6c 75 73 69 5 bytes, exclusi
2dff0 76 65 20 6f 66 0a 2a 2a 20 74 68 65 20 7a 65 72 ve of.** the zer
2e000 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e o-terminator. N
2e010 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d ote that the nam
2e020 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 e length limit i
2e030 73 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a s in bytes, not.
2e040 2a 2a 20 63 68 61 72 61 63 74 65 72 73 2e 20 20 ** characters.
2e050 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 Any attempt to c
2e060 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e reate a function
2e070 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e with a longer n
2e080 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 ame.** will resu
2e090 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 45 52 lt in [SQLITE_ER
2e0a0 52 4f 52 5d 20 62 65 69 6e 67 20 72 65 74 75 72 ROR] being retur
2e0b0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 ned..**.** The t
2e0c0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 hird parameter (
2e0d0 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 nArg).** is the
2e0e0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 number of argume
2e0f0 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c nts that the SQL
2e100 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 function or.**
2e110 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e aggregate takes.
2e120 20 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 If this paramet
2e130 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 er is negative,
2e140 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e then the SQL fun
2e150 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 ction or.** aggr
2e160 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 egate may take a
2e170 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 ny number of arg
2e180 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 uments..**.** Th
2e190 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
2e1a0 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 er, eTextRep, sp
2e1b0 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 ecifies what.**
2e1c0 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 [SQLITE_UTF8 | t
2e1d0 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 ext encoding] th
2e1e0 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 is SQL function
2e1f0 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 prefers for.** i
2e200 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 ts parameters.
2e210 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e Any SQL function
2e220 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
2e230 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20 74 should be able t
2e240 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 o work.** work w
2e250 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 ith UTF-8, UTF-1
2e260 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 6le, or UTF-16be
2e270 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c . But some impl
2e280 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 ementations may
2e290 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 be.** more effic
2e2a0 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e ient with one en
2e2b0 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 coding than anot
2e2c0 68 65 72 2e 20 20 49 74 20 69 73 20 61 6c 6c 6f her. It is allo
2e2d0 77 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 wed to.** invoke
2e2e0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
2e2f0 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 function() or sq
2e300 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
2e310 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 ction16() multip
2e320 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 le.** times with
2e330 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 the same functi
2e340 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 on but with diff
2e350 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 erent values of
2e360 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 57 68 65 eTextRep..** Whe
2e370 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 n multiple imple
2e380 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 mentations of th
2e390 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 e same function
2e3a0 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 are available, S
2e3b0 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 QLite.** will pi
2e3c0 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 ck the one that
2e3d0 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 involves the lea
2e3e0 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 st amount of dat
2e3f0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a a conversion..**
2e400 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c If there is onl
2e410 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 y a single imple
2e420 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 mentation which
2e430 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 does not care wh
2e440 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 at text.** encod
2e450 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 ing is used, the
2e460 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 n the fourth arg
2e470 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 ument should be
2e480 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a [SQLITE_ANY]..**
2e490 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 70 61 .** The fifth pa
2e4a0 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 rameter is an ar
2e4b0 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e bitrary pointer.
2e4c0 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 The implementa
2e4d0 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 tion of the.** f
2e4e0 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e unction can gain
2e4f0 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 access to this
2e500 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 pointer using [s
2e510 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 qlite3_user_data
2e520 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ()]..**.** The s
2e530 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61 eventh, eighth a
2e540 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 nd ninth paramet
2e550 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 ers, xFunc, xSte
2e560 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 p and xFinal, ar
2e570 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f e.** pointers to
2e580 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 C-language func
2e590 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 tions that imple
2e5a0 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e ment the SQL fun
2e5b0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 ction or.** aggr
2e5c0 65 67 61 74 65 2e 20 41 20 73 63 61 6c 61 72 20 egate. A scalar
2e5d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 SQL function req
2e5e0 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 uires an impleme
2e5f0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 ntation of the x
2e600 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b Func.** callback
2e610 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e only, NULL poin
2e620 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70 ters should be p
2e630 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 assed as the xSt
2e640 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a ep and xFinal.**
2e650 20 70 61 72 61 6d 65 74 65 72 73 2e 20 41 6e 20 parameters. An
2e660 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 aggregate SQL fu
2e670 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 nction requires
2e680 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f an implementatio
2e690 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e n of xStep.** an
2e6a0 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c d xFinal and NUL
2e6b0 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 L should be pass
2e6c0 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f ed for xFunc. To
2e6d0 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 delete an exist
2e6e0 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 ing.** SQL funct
2e6f0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 ion or aggregate
2e700 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 , pass NULL for
2e710 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 all three functi
2e720 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a on callbacks..**
2e730 0a 2a 2a 20 49 74 20 69 73 20 70 65 72 6d 69 74 .** It is permit
2e740 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 ted to register
2e750 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 multiple impleme
2e760 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 ntations of the
2e770 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e same.** function
2e780 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 s with the same
2e790 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 name but with ei
2e7a0 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e ther differing n
2e7b0 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 umbers of.** arg
2e7c0 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 uments or differ
2e7d0 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 ing preferred te
2e7e0 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53 xt encodings. S
2e7f0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a QLite will use.*
2e800 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 * the implementa
2e810 74 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c tion most closel
2e820 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 y matches the wa
2e830 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a y in which the.*
2e840 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 * SQL function i
2e850 73 20 75 73 65 64 2e 20 20 41 20 66 75 6e 63 74 s used. A funct
2e860 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ion implementati
2e870 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 on with a non-ne
2e880 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 gative.** nArg p
2e890 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 arameter is a be
2e8a0 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 tter match than
2e8b0 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 a function imple
2e8c0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a mentation with.*
2e8d0 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 * a negative nAr
2e8e0 67 2e 20 20 41 20 66 75 6e 63 74 69 6f 6e 20 77 g. A function w
2e8f0 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72 here the preferr
2e900 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 ed text encoding
2e910 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 .** matches the
2e920 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e database encodin
2e930 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a g is a better.**
2e940 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 match than a fu
2e950 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 nction where the
2e960 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 encoding is dif
2e970 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 41 20 66 ferent. .** A f
2e980 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 unction where th
2e990 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 e encoding diffe
2e9a0 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e rence is between
2e9b0 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 UTF16le and UTF
2e9c0 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 16be.** is a clo
2e9d0 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 ser match than a
2e9e0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 function where
2e9f0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 the encoding dif
2ea00 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 ference is.** be
2ea10 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 tween UTF8 and U
2ea20 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 42 75 69 6c TF16..**.** Buil
2ea30 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d t-in functions m
2ea40 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 ay be overloaded
2ea50 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 by new applicat
2ea60 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
2ea70 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 66 69 tions..** The fi
2ea80 72 73 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d rst application-
2ea90 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
2eaa0 20 77 69 74 68 20 61 20 67 69 76 65 6e 20 6e 61 with a given na
2eab0 6d 65 20 6f 76 65 72 72 69 64 65 73 20 61 6c 6c me overrides all
2eac0 0a 2a 2a 20 62 75 69 6c 74 2d 69 6e 20 66 75 6e .** built-in fun
2ead0 63 74 69 6f 6e 73 20 69 6e 20 74 68 65 20 73 61 ctions in the sa
2eae0 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e me [database con
2eaf0 6e 65 63 74 69 6f 6e 5d 20 77 69 74 68 20 74 68 nection] with th
2eb00 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 20 e same name..**
2eb10 53 75 62 73 65 71 75 65 6e 74 20 61 70 70 6c 69 Subsequent appli
2eb20 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
2eb30 75 6e 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 unctions of the
2eb40 73 61 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79 20 6f same name only o
2eb50 76 65 72 72 69 64 65 20 0a 2a 2a 20 70 72 69 6f verride .** prio
2eb60 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 r application-de
2eb70 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 fined functions
2eb80 74 68 61 74 20 61 72 65 20 61 6e 20 65 78 61 63 that are an exac
2eb90 74 20 6d 61 74 63 68 20 66 6f 72 20 74 68 65 0a t match for the.
2eba0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 ** number of par
2ebb0 61 6d 65 74 65 72 73 20 61 6e 64 20 70 72 65 66 ameters and pref
2ebc0 65 72 72 65 64 20 65 6e 63 6f 64 69 6e 67 2e 0a erred encoding..
2ebd0 2a 2a 0a 2a 2a 20 41 6e 20 61 70 70 6c 69 63 61 **.** An applica
2ebe0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
2ebf0 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 ction is permitt
2ec00 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 ed to call other
2ec10 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 .** SQLite inter
2ec20 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c faces. However,
2ec30 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 such calls must
2ec40 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 not.** close th
2ec50 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
2ec60 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 ction nor finali
2ec70 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 ze or reset the
2ec80 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 prepared.** stat
2ec90 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 ement in which t
2eca0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 he function is r
2ecb0 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e unning..**.** IN
2ecc0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
2ecd0 7b 48 31 36 31 30 33 7d 20 54 68 65 20 5b 73 71 {H16103} The [sq
2ece0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
2ecf0 63 74 69 6f 6e 31 36 28 44 2c 58 2c 2e 2e 2e 29 ction16(D,X,...)
2ed00 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c ] interface shal
2ed10 6c 20 62 65 68 61 76 65 0a 2a 2a 20 20 20 20 20 l behave.**
2ed20 20 20 20 20 20 61 73 20 5b 73 71 6c 69 74 65 33 as [sqlite3
2ed30 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
2ed40 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 20 65 76 (D,X,...)] in ev
2ed50 65 72 79 20 77 61 79 20 65 78 63 65 70 74 20 74 ery way except t
2ed60 68 61 74 20 69 74 0a 2a 2a 20 20 20 20 20 20 20 hat it.**
2ed70 20 20 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 interprets th
2ed80 65 20 58 20 61 72 67 75 6d 65 6e 74 20 61 73 20 e X argument as
2ed90 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
2eda0 55 54 46 2d 31 36 0a 2a 2a 20 20 20 20 20 20 20 UTF-16.**
2edb0 20 20 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f native byte o
2edc0 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 rder instead of
2edd0 61 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 as zero-terminat
2ede0 65 64 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 ed UTF-8..**.**
2edf0 7b 48 31 36 31 30 36 7d 20 41 20 73 75 63 63 65 {H16106} A succe
2ee00 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e ssful invocation
2ee10 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 of the.**
2ee20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 [sqlite3_cre
2ee30 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 ate_function(D,X
2ee40 2c 4e 2c 45 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 ,N,E,...)] inter
2ee50 66 61 63 65 20 73 68 61 6c 6c 20 72 65 67 69 73 face shall regis
2ee60 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ter.**
2ee70 6f 72 20 72 65 70 6c 61 63 65 73 20 63 61 6c 6c or replaces call
2ee80 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 69 back functions i
2ee90 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 n the [database
2eea0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a connection] D.**
2eeb0 20 20 20 20 20 20 20 20 20 20 75 73 65 64 20 74 used t
2eec0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 o implement the
2eed0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d SQL function nam
2eee0 65 64 20 58 20 77 69 74 68 20 4e 20 70 61 72 61 ed X with N para
2eef0 6d 65 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 meters.**
2ef00 20 20 20 61 6e 64 20 68 61 76 69 6e 67 20 61 20 and having a
2ef10 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 preferred text e
2ef20 6e 63 6f 64 69 6e 67 20 6f 66 20 45 2e 0a 2a 2a ncoding of E..**
2ef30 0a 2a 2a 20 7b 48 31 36 31 30 39 7d 20 41 20 73 .** {H16109} A s
2ef40 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 uccessful call t
2ef50 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 o [sqlite3_creat
2ef60 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e e_function(D,X,N
2ef70 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 ,E,P,F,S,L)].**
2ef80 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 72 shall r
2ef90 65 70 6c 61 63 65 20 74 68 65 20 50 2c 20 46 2c eplace the P, F,
2efa0 20 53 2c 20 61 6e 64 20 4c 20 76 61 6c 75 65 73 S, and L values
2efb0 20 66 72 6f 6d 20 61 6e 79 20 70 72 69 6f 72 20 from any prior
2efc0 63 61 6c 6c 73 20 77 69 74 68 0a 2a 2a 20 20 20 calls with.**
2efd0 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 the same
2efe0 44 2c 20 58 2c 20 4e 2c 20 61 6e 64 20 45 20 76 D, X, N, and E v
2eff0 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 alues..**.** {H1
2f000 36 31 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 6112} The [sqlit
2f010 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
2f020 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 74 on(D,X,...)] int
2f030 65 72 66 61 63 65 20 73 68 61 6c 6c 20 66 61 69 erface shall fai
2f040 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 l.** if
2f050 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
2f060 6e 20 6e 61 6d 65 20 58 20 69 73 0a 2a 2a 20 20 n name X is.**
2f070 20 20 20 20 20 20 20 20 6c 6f 6e 67 65 72 20 74 longer t
2f080 68 61 6e 20 32 35 35 20 62 79 74 65 73 20 65 78 han 255 bytes ex
2f090 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a clusive of the z
2f0a0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a ero terminator..
2f0b0 2a 2a 0a 2a 2a 20 7b 48 31 36 31 31 38 7d 20 54 **.** {H16118} T
2f0c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 he [sqlite3_crea
2f0d0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c te_function(D,X,
2f0e0 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 69 6e N,E,P,F,S,L)] in
2f0f0 74 65 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 terface.**
2f100 20 20 20 20 73 68 61 6c 6c 20 66 61 69 6c 20 75 shall fail u
2f110 6e 6c 65 73 73 20 65 69 74 68 65 72 20 46 20 69 nless either F i
2f120 73 20 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64 s NULL and S and
2f130 20 4c 20 61 72 65 20 6e 6f 6e 2d 4e 55 4c 4c 20 L are non-NULL
2f140 6f 72 0a 2a 2a 2a 20 20 20 20 20 20 20 20 20 46 or.*** F
2f150 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 20 61 6e 64 is non-NULL and
2f160 20 53 20 61 6e 64 20 4c 20 61 72 65 20 4e 55 4c S and L are NUL
2f170 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 31 L..**.** {H16121
2f180 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 } The [sqlite3_c
2f190 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 reate_function(D
2f1a0 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 ,...)] interface
2f1b0 20 73 68 61 6c 6c 20 66 61 69 6c 73 20 77 69 74 shall fails wit
2f1c0 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 h an.**
2f1d0 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b error code of [
2f1e0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 66 20 SQLITE_BUSY] if
2f1f0 74 68 65 72 65 20 65 78 69 73 74 20 5b 70 72 65 there exist [pre
2f200 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 pared statements
2f210 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 ].** as
2f220 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 sociated with th
2f230 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
2f240 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a ection] D..**.**
2f250 20 7b 48 31 36 31 32 34 7d 20 54 68 65 20 5b 73 {H16124} The [s
2f260 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
2f270 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e nction(D,X,N,...
2f280 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 )] interface sha
2f290 6c 6c 20 66 61 69 6c 20 77 69 74 68 0a 2a 2a 20 ll fail with.**
2f2a0 20 20 20 20 20 20 20 20 20 61 6e 20 65 72 72 6f an erro
2f2b0 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 r code of [SQLIT
2f2c0 45 5f 45 52 52 4f 52 5d 20 69 66 20 70 61 72 61 E_ERROR] if para
2f2d0 6d 65 74 65 72 20 4e 20 69 73 20 6c 65 73 73 0a meter N is less.
2f2e0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 6e ** than
2f2f0 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 -1 or greater t
2f300 68 61 6e 20 31 32 37 2e 0a 2a 2a 0a 2a 2a 20 7b han 127..**.** {
2f310 48 31 36 31 32 37 7d 20 57 68 65 6e 20 4e 20 69 H16127} When N i
2f320 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 s non-negative,
2f330 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 the [sqlite3_cre
2f340 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 ate_function(D,X
2f350 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 ,N,...)].**
2f360 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 73 interface s
2f370 68 61 6c 6c 20 72 65 67 69 73 74 65 72 20 63 61 hall register ca
2f380 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e llbacks to be in
2f390 76 6f 6b 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a voked for the.**
2f3a0 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 66 75 SQL fu
2f3b0 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 nction.**
2f3c0 20 20 20 6e 61 6d 65 64 20 58 20 77 68 65 6e 20 named X when
2f3d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 the number of ar
2f3e0 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 53 guments to the S
2f3f0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a QL function is.*
2f400 2a 20 20 20 20 20 20 20 20 20 20 65 78 61 63 74 * exact
2f410 6c 79 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 ly N..**.** {H16
2f420 31 33 30 7d 20 57 68 65 6e 20 4e 20 69 73 20 2d 130} When N is -
2f430 31 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 1, the [sqlite3_
2f440 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
2f450 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 D,X,N,...)].**
2f460 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 interfac
2f470 65 20 73 68 61 6c 6c 20 72 65 67 69 73 74 65 72 e shall register
2f480 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65 callbacks to be
2f490 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 65 invoked for the
2f4a0 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 SQL.**
2f4b0 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 64 20 function named
2f4c0 58 20 77 69 74 68 20 61 6e 79 20 6e 75 6d 62 65 X with any numbe
2f4d0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a r of arguments..
2f4e0 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 33 7d 20 57 **.** {H16133} W
2f4f0 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 hen calls to [sq
2f500 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
2f510 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 ction(D,X,N,...)
2f520 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 70 ].** sp
2f530 65 63 69 66 79 20 6d 75 6c 74 69 70 6c 65 20 69 ecify multiple i
2f540 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f mplementations o
2f550 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 f the same funct
2f560 69 6f 6e 20 58 0a 2a 2a 20 20 20 20 20 20 20 20 ion X.**
2f570 20 20 61 6e 64 20 77 68 65 6e 20 6f 6e 65 20 69 and when one i
2f580 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 68 61 mplementation ha
2f590 73 20 4e 3e 3d 30 20 61 6e 64 20 74 68 65 20 6f s N>=0 and the o
2f5a0 74 68 65 72 20 68 61 73 20 4e 3d 28 2d 31 29 0a ther has N=(-1).
2f5b0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
2f5c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 implementation w
2f5d0 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 4e ith a non-zero N
2f5e0 20 73 68 61 6c 6c 20 62 65 20 70 72 65 66 65 72 shall be prefer
2f5f0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 red..**.** {H161
2f600 33 36 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20 74 36} When calls t
2f610 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 o [sqlite3_creat
2f620 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e e_function(D,X,N
2f630 2c 45 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 ,E,...)].**
2f640 20 20 20 20 20 73 70 65 63 69 66 79 20 6d 75 6c specify mul
2f650 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 tiple implementa
2f660 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d tions of the sam
2f670 65 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 e function X wit
2f680 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 h.** th
2f690 65 20 73 61 6d 65 20 6e 75 6d 62 65 72 20 6f 66 e same number of
2f6a0 20 61 72 67 75 6d 65 6e 74 73 20 4e 20 62 75 74 arguments N but
2f6b0 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 0a with different.
2f6c0 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e 63 6f ** enco
2f6d0 64 69 6e 67 73 20 45 2c 20 74 68 65 6e 20 74 68 dings E, then th
2f6e0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
2f6f0 20 77 68 65 72 65 20 45 20 6d 61 74 63 68 65 73 where E matches
2f700 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
2f710 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 database encodi
2f720 6e 67 20 73 68 61 6c 6c 20 70 72 65 66 65 72 72 ng shall preferr
2f730 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 ed..**.** {H1613
2f740 39 7d 20 46 6f 72 20 61 6e 20 61 67 67 72 65 67 9} For an aggreg
2f750 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ate SQL function
2f760 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a created using.*
2f770 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
2f780 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
2f790 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 30 2c ion(D,X,N,E,P,0,
2f7a0 53 2c 4c 29 5d 20 74 68 65 20 66 69 6e 61 6c 69 S,L)] the finali
2f7b0 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 zer.**
2f7c0 66 75 6e 63 74 69 6f 6e 20 4c 20 73 68 61 6c 6c function L shall
2f7d0 20 61 6c 77 61 79 73 20 62 65 20 69 6e 76 6f 6b always be invok
2f7e0 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 20 ed exactly once
2f7f0 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 if the.**
2f800 20 20 20 73 74 65 70 20 66 75 6e 63 74 69 6f 6e step function
2f810 20 53 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 65 S is called one
2f820 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a or more times..
2f830 2a 2a 0a 2a 2a 20 7b 48 31 36 31 34 32 7d 20 57 **.** {H16142} W
2f840 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b hen SQLite invok
2f850 65 73 20 65 69 74 68 65 72 20 74 68 65 20 78 46 es either the xF
2f860 75 6e 63 20 6f 72 20 78 53 74 65 70 20 66 75 6e unc or xStep fun
2f870 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20 20 ction of.**
2f880 20 20 20 20 20 61 6e 20 61 70 70 6c 69 63 61 74 an applicat
2f890 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
2f8a0 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 function or aggr
2f8b0 65 67 61 74 65 20 63 72 65 61 74 65 64 0a 2a 2a egate created.**
2f8c0 20 20 20 20 20 20 20 20 20 20 62 79 20 5b 73 71 by [sq
2f8d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
2f8e0 63 74 69 6f 6e 28 29 5d 20 6f 72 20 5b 73 71 6c ction()] or [sql
2f8f0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
2f900 74 69 6f 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 tion16()],.**
2f910 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 then the
2f920 61 72 72 61 79 20 6f 66 20 5b 73 71 6c 69 74 65 array of [sqlite
2f930 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 3_value] objects
2f940 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a passed as the.*
2f950 2a 20 20 20 20 20 20 20 20 20 20 74 68 69 72 64 * third
2f960 20 70 61 72 61 6d 65 74 65 72 20 73 68 61 6c 6c parameter shall
2f970 20 62 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 be [protected s
2f980 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
2f990 6a 65 63 74 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 jects..*/.int sq
2f9a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
2f9b0 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 ction(. sqlite3
2f9c0 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 *db,. const ch
2f9d0 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d ar *zFunctionNam
2f9e0 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 e,. int nArg,.
2f9f0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 int eTextRep,.
2fa00 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 void *pApp,. v
2fa10 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c oid (*xFunc)(sql
2fa20 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e ite3_context*,in
2fa30 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t,sqlite3_value*
2fa40 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 *),. void (*xSt
2fa50 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ep)(sqlite3_cont
2fa60 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
2fa70 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
2fa80 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 d (*xFinal)(sqli
2fa90 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b te3_context*).);
2faa0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 .int sqlite3_cre
2fab0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a ate_function16(.
2fac0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 sqlite3 *db,.
2fad0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 const void *zFu
2fae0 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e nctionName,. in
2faf0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 t nArg,. int eT
2fb00 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a extRep,. void *
2fb10 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 pApp,. void (*x
2fb20 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f Func)(sqlite3_co
2fb30 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 ntext*,int,sqlit
2fb40 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 e3_value**),. v
2fb50 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c oid (*xStep)(sql
2fb60 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e ite3_context*,in
2fb70 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t,sqlite3_value*
2fb80 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 *),. void (*xFi
2fb90 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e nal)(sqlite3_con
2fba0 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a text*).);../*.**
2fbb0 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 CAPI3REF: Text
2fbc0 45 6e 63 6f 64 69 6e 67 73 20 7b 48 31 30 32 36 Encodings {H1026
2fbd0 37 7d 20 3c 53 35 30 32 30 30 3e 20 3c 48 31 36 7} <S50200> <H16
2fbe0 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 100>.**.** These
2fbf0 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 constant define
2fc00 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 integer codes t
2fc10 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 hat represent th
2fc20 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 e various.** tex
2fc30 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 t encodings supp
2fc40 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e orted by SQLite.
2fc50 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
2fc60 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 TE_UTF8
2fc70 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 1.#define SQLI
2fc80 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 TE_UTF16LE
2fc90 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 2.#define SQLI
2fca0 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 TE_UTF16BE
2fcb0 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 3.#define SQLI
2fcc0 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 TE_UTF16
2fcd0 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 4 /* Use na
2fce0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 tive byte order
2fcf0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
2fd00 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 E_ANY
2fd10 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5 /* sqlite3
2fd20 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
2fd30 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 only */.#define
2fd40 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c SQLITE_UTF16_AL
2fd50 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 IGNED 8 /* s
2fd60 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
2fd70 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a llation only */.
2fd80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2fd90 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 Deprecated Func
2fda0 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 tions.** DEPRECA
2fdb0 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 TED.**.** These
2fdc0 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 functions are [d
2fdd0 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 eprecated]. In
2fde0 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 order to maintai
2fdf0 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 n.** backwards c
2fe00 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 ompatibility wit
2fe10 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 h older code, th
2fe20 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f ese functions co
2fe30 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 ntinue .** to be
2fe40 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 supported. How
2fe50 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 ever, new applic
2fe60 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 ations should av
2fe70 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f oid.** the use o
2fe80 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e f these function
2fe90 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f s. To help enco
2fea0 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 urage people to
2feb0 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 avoid.** using t
2fec0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 hese functions,
2fed0 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 we are not going
2fee0 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 to tell you wha
2fef0 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 t they do..*/.#i
2ff00 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 fndef SQLITE_OMI
2ff10 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c T_DEPRECATED.SQL
2ff20 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 ITE_DEPRECATED i
2ff30 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 nt sqlite3_aggre
2ff40 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 gate_count(sqlit
2ff50 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 e3_context*);.SQ
2ff60 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 LITE_DEPRECATED
2ff70 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 int sqlite3_expi
2ff80 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 red(sqlite3_stmt
2ff90 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 *);.SQLITE_DEPRE
2ffa0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 CATED int sqlite
2ffb0 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 3_transfer_bindi
2ffc0 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ngs(sqlite3_stmt
2ffd0 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a *, sqlite3_stmt*
2ffe0 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 );.SQLITE_DEPREC
2fff0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 ATED int sqlite3
30000 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 _global_recover(
30010 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 void);.SQLITE_DE
30020 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 PRECATED void sq
30030 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 lite3_thread_cle
30040 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 anup(void);.SQLI
30050 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e TE_DEPRECATED in
30060 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 t sqlite3_memory
30070 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 _alarm(void(*)(v
30080 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 oid*,sqlite3_int
30090 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 64,int),void*,sq
300a0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 lite3_int64);.#e
300b0 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ndif../*.** CAPI
300c0 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 3REF: Obtaining
300d0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 SQL Function Par
300e0 61 6d 65 74 65 72 20 56 61 6c 75 65 73 20 7b 48 ameter Values {H
300f0 31 35 31 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 15100} <S20200>.
30100 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 **.** The C-lang
30110 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 uage implementat
30120 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 ion of SQL funct
30130 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 ions and aggrega
30140 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 tes uses.** this
30150 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 set of interfac
30160 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 e routines to ac
30170 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 cess the paramet
30180 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 er values on.**
30190 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 the function or
301a0 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a aggregate..**.**
301b0 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 The xFunc (for
301c0 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 scalar functions
301d0 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 ) or xStep (for
301e0 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61 aggregates) para
301f0 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 meters.** to [sq
30200 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
30210 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 ction()] and [sq
30220 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
30230 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 ction16()].** de
30240 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 fine callbacks t
30250 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 hat implement th
30260 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 e SQL functions
30270 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a and aggregates..
30280 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d ** The 4th param
30290 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 eter to these ca
302a0 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 llbacks is an ar
302b0 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 ray of pointers
302c0 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 to.** [protected
302d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
302e0 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 objects. There
302f0 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f is one [sqlite3_
30300 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f value] object fo
30310 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 r.** each parame
30320 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 ter to the SQL f
30330 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 unction. These
30340 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 routines are use
30350 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 d to.** extract
30360 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 values from the
30370 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 [sqlite3_value]
30380 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 objects..**.** T
30390 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f hese routines wo
303a0 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 rk only with [pr
303b0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
303c0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a value] objects..
303d0 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 ** Any attempt t
303e0 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 o use these rout
303f0 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 ines on an [unpr
30400 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
30410 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 value].** object
30420 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 results in unde
30430 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a fined behavior..
30440 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
30450 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c ines work just l
30460 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f ike the correspo
30470 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 nding [column ac
30480 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a cess functions].
30490 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20 ** except that
304a0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 these routines t
304b0 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 ake a single [pr
304c0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
304d0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a value] object.**
304e0 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 pointer instead
304f0 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 of a [sqlite3_s
30500 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e tmt*] pointer an
30510 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c d an integer col
30520 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a umn number..**.*
30530 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 * The sqlite3_va
30540 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 lue_text16() int
30550 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 erface extracts
30560 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a a UTF-16 string.
30570 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 ** in the native
30580 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 byte-order of t
30590 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e he host machine.
305a0 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 The.** sqlite3
305b0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 _value_text16be(
305c0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 ) and sqlite3_va
305d0 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 lue_text16le() i
305e0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 nterfaces.** ext
305f0 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 ract UTF-16 stri
30600 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 ngs as big-endia
30610 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 n and little-end
30620 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 ian respectively
30630 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
30640 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 te3_value_numeri
30650 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 c_type() interfa
30660 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 ce attempts to a
30670 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 pply.** numeric
30680 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 affinity to the
30690 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 value. This mea
306a0 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d ns that an attem
306b0 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f pt is.** made to
306c0 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c convert the val
306d0 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 ue to an integer
306e0 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 or floating poi
306f0 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 nt. If.** such
30700 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 a conversion is
30710 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 possible without
30720 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 loss of informa
30730 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a tion (in other.*
30740 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 * words, if the
30750 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e value is a strin
30760 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b g that looks lik
30770 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 e a number).** t
30780 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 hen the conversi
30790 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e on is performed.
307a0 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 Otherwise no c
307b0 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 onversion occurs
307c0 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ..** The [SQLITE
307d0 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 _INTEGER | datat
307e0 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 ype] after conve
307f0 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 rsion is returne
30800 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 d..**.** Please
30810 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 pay particular a
30820 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 ttention to the
30830 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f fact that the po
30840 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a inter returned.*
30850 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f * from [sqlite3_
30860 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b value_blob()], [
30870 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
30880 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 xt()], or.** [sq
30890 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
308a0 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 16()] can be inv
308b0 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 alidated by a su
308c0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f bsequent call to
308d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c .** [sqlite3_val
308e0 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 ue_bytes()], [sq
308f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 lite3_value_byte
30900 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 s16()], [sqlite3
30910 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a _value_text()],.
30920 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 ** or [sqlite3_v
30930 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a alue_text16()]..
30940 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
30950 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c ines must be cal
30960 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d led from the sam
30970 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 e thread as.** t
30980 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 he SQL function
30990 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 that supplied th
309a0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 e [sqlite3_value
309b0 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a *] parameters..*
309c0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
309d0 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 33 7d 20 .**.** {H15103}
309e0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c The [sqlite3_val
309f0 75 65 5f 62 6c 6f 62 28 56 29 5d 20 69 6e 74 65 ue_blob(V)] inte
30a00 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 rface converts t
30a10 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b he.** [
30a20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
30a30 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
30a40 56 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 61 6e V into a BLOB an
30a50 64 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 d then.**
30a60 20 20 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 returns a poi
30a70 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6e 76 nter to the conv
30a80 65 72 74 65 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a erted value..**.
30a90 2a 2a 20 7b 48 31 35 31 30 36 7d 20 54 68 65 20 ** {H15106} The
30aa0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 [sqlite3_value_b
30ab0 79 74 65 73 28 56 29 5d 20 69 6e 74 65 72 66 61 ytes(V)] interfa
30ac0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a ce returns the.*
30ad0 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 * numbe
30ae0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
30af0 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 e BLOB or string
30b00 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 (exclusive of t
30b10 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a he.** z
30b20 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f ero terminator o
30b30 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 n the string) th
30b40 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 at was returned
30b50 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 by the.**
30b60 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 most recent c
30b70 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
30b80 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20 6f value_blob(V)] o
30b90 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 r.** [s
30ba0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
30bb0 74 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 t(V)]..**.** {H1
30bc0 35 31 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 5109} The [sqlit
30bd0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 e3_value_bytes16
30be0 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 (V)] interface r
30bf0 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 eturns the.**
30c00 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 number of
30c10 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 bytes in the st
30c20 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 ring (exclusive
30c30 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 of the.**
30c40 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 zero terminat
30c50 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 or on the string
30c60 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 ) that was retur
30c70 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 ned by the.**
30c80 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 most rece
30c90 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 nt call to [sqli
30ca0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
30cb0 28 56 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 (V)],.**
30cc0 20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 [sqlite3_value
30cd0 5f 74 65 78 74 31 36 62 65 28 56 29 5d 2c 20 6f _text16be(V)], o
30ce0 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 r [sqlite3_value
30cf0 5f 74 65 78 74 31 36 6c 65 28 56 29 5d 2e 0a 2a _text16le(V)]..*
30d00 2a 0a 2a 2a 20 7b 48 31 35 31 31 32 7d 20 54 68 *.** {H15112} Th
30d10 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 e [sqlite3_value
30d20 5f 64 6f 75 62 6c 65 28 56 29 5d 20 69 6e 74 65 _double(V)] inte
30d30 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 rface converts t
30d40 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b he.** [
30d50 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
30d60 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
30d70 56 20 69 6e 74 6f 20 61 20 66 6c 6f 61 74 69 6e V into a floatin
30d80 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 61 6e g point value an
30d90 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 d.** re
30da0 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 turns a copy of
30db0 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a that value..**.*
30dc0 2a 20 7b 48 31 35 31 31 35 7d 20 54 68 65 20 5b * {H15115} The [
30dd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e sqlite3_value_in
30de0 74 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 t(V)] interface
30df0 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 converts the.**
30e00 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 [protec
30e10 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
30e20 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f e] object V into
30e30 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 a 64-bit signed
30e40 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 integer and.**
30e50 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 returns
30e60 20 74 68 65 20 6c 6f 77 65 72 20 33 32 20 62 69 the lower 32 bi
30e70 74 73 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 ts of that integ
30e80 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31 er..**.** {H1511
30e90 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 8} The [sqlite3_
30ea0 76 61 6c 75 65 5f 69 6e 74 36 34 28 56 29 5d 20 value_int64(V)]
30eb0 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 interface conver
30ec0 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 ts the.**
30ed0 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 [protected sq
30ee0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
30ef0 65 63 74 20 56 20 69 6e 74 6f 20 61 20 36 34 2d ect V into a 64-
30f00 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 bit signed integ
30f10 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 er and.**
30f20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 returns a cop
30f30 79 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 y of that intege
30f40 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32 31 r..**.** {H15121
30f50 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 } The [sqlite3_v
30f60 61 6c 75 65 5f 74 65 78 74 28 56 29 5d 20 69 6e alue_text(V)] in
30f70 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 terface converts
30f80 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
30f90 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 [protected sqli
30fa0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
30fb0 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d t V into a zero-
30fc0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 terminated UTF-8
30fd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 .** str
30fe0 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 ing and returns
30ff0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 a pointer to tha
31000 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 t string..**.**
31010 7b 48 31 35 31 32 34 7d 20 54 68 65 20 5b 73 71 {H15124} The [sq
31020 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
31030 31 36 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 16(V)] interface
31040 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a converts the.**
31050 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 [prote
31060 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
31070 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 ue] object V int
31080 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 o a zero-termina
31090 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 ted 2-byte.**
310a0 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 aligned U
310b0 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 TF-16 native byt
310c0 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 e order.**
310d0 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 string and r
310e0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
310f0 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e to that string.
31100 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32 37 7d 20 .**.** {H15127}
31110 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c The [sqlite3_val
31120 75 65 5f 74 65 78 74 31 36 62 65 28 56 29 5d 20 ue_text16be(V)]
31130 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 interface conver
31140 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 ts the.**
31150 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 [protected sq
31160 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
31170 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 ect V into a zer
31180 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 o-terminated 2-b
31190 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 yte.**
311a0 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 62 aligned UTF-16 b
311b0 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 ig-endian.**
311c0 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 string and
311d0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
311e0 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e er to that strin
311f0 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33 30 g..**.** {H15130
31200 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 } The [sqlite3_v
31210 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56 29 alue_text16le(V)
31220 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 ] interface conv
31230 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 erts the.**
31240 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 [protected
31250 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
31260 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a bject V into a z
31270 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 ero-terminated 2
31280 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 -byte.**
31290 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 aligned UTF-16
312a0 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a little-endian.*
312b0 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e * strin
312c0 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 g and returns a
312d0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 pointer to that
312e0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 string..**.** {H
312f0 31 35 31 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 15133} The [sqli
31300 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 56 te3_value_type(V
31310 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
31320 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 urns.**
31330 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f one of [SQLITE_
31340 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 NULL], [SQLITE_I
31350 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 NTEGER], [SQLITE
31360 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 _FLOAT],.**
31370 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 [SQLITE_TEX
31380 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 T], or [SQLITE_B
31390 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 LOB] as appropri
313a0 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 ate for.**
313b0 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 the [sqlite3
313c0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 _value] object V
313d0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33 36 7d ..**.** {H15136}
313e0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 The [sqlite3_va
313f0 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 lue_numeric_type
31400 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 (V)] interface c
31410 6f 6e 76 65 72 74 73 0a 2a 2a 20 20 20 20 20 20 onverts.**
31420 20 20 20 20 74 68 65 20 5b 70 72 6f 74 65 63 74 the [protect
31430 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
31440 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 ] object V into
31450 65 69 74 68 65 72 20 61 6e 20 69 6e 74 65 67 65 either an intege
31460 72 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 r or.**
31470 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e a floating poin
31480 74 20 76 61 6c 75 65 20 69 66 20 69 74 20 63 61 t value if it ca
31490 6e 20 64 6f 20 73 6f 20 77 69 74 68 6f 75 74 20 n do so without
314a0 6c 6f 73 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 loss of.**
314b0 20 20 20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c information,
314c0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 6f 6e 65 and returns one
314d0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c of [SQLITE_NULL
314e0 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b ],.** [
314f0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c SQLITE_INTEGER],
31500 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c [SQLITE_FLOAT],
31510 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 [SQLITE_TEXT],
31520 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b or.** [
31530 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 SQLITE_BLOB] as
31540 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 appropriate for
31550 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
31560 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 [protected sqlit
31570 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
31580 20 56 20 61 66 74 65 72 20 74 68 65 20 63 6f 6e V after the con
31590 76 65 72 73 69 6f 6e 20 61 74 74 65 6d 70 74 2e version attempt.
315a0 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a .*/.const void *
315b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c sqlite3_value_bl
315c0 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ob(sqlite3_value
315d0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f *);.int sqlite3_
315e0 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 value_bytes(sqli
315f0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 te3_value*);.int
31600 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 sqlite3_value_b
31610 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 ytes16(sqlite3_v
31620 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 alue*);.double s
31630 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 qlite3_value_dou
31640 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 ble(sqlite3_valu
31650 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 e*);.int sqlite3
31660 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 _value_int(sqlit
31670 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 e3_value*);.sqli
31680 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 te3_int64 sqlite
31690 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 3_value_int64(sq
316a0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 lite3_value*);.c
316b0 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 onst unsigned ch
316c0 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 ar *sqlite3_valu
316d0 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 e_text(sqlite3_v
316e0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f alue*);.const vo
316f0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 id *sqlite3_valu
31700 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 e_text16(sqlite3
31710 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 _value*);.const
31720 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 void *sqlite3_va
31730 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c lue_text16le(sql
31740 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f ite3_value*);.co
31750 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
31760 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 3_value_text16be
31770 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
31780 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 ;.int sqlite3_va
31790 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 lue_type(sqlite3
317a0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 _value*);.int sq
317b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 lite3_value_nume
317c0 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 ric_type(sqlite3
317d0 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a _value*);../*.**
317e0 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 CAPI3REF: Obtai
317f0 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 n Aggregate Func
31800 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 7b 48 31 tion Context {H1
31810 36 32 31 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 6210} <S20200>.*
31820 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 *.** The impleme
31830 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 ntation of aggre
31840 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f gate SQL functio
31850 6e 73 20 75 73 65 20 74 68 69 73 20 72 6f 75 74 ns use this rout
31860 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a ine to allocate.
31870 2a 2a 20 61 20 73 74 72 75 63 74 75 72 65 20 66 ** a structure f
31880 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 or storing their
31890 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 state..**.** Th
318a0 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 e first time the
318b0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 sqlite3_aggrega
318c0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 72 6f 75 te_context() rou
318d0 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 66 tine is called f
318e0 6f 72 20 61 0a 2a 2a 20 70 61 72 74 69 63 75 6c or a.** particul
318f0 61 72 20 61 67 67 72 65 67 61 74 65 2c 20 53 51 ar aggregate, SQ
31900 4c 69 74 65 20 61 6c 6c 6f 63 61 74 65 73 20 6e Lite allocates n
31910 42 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c Bytes of memory,
31920 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 zeroes out that
31930 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 .** memory, and
31940 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
31950 72 20 74 6f 20 69 74 2e 20 4f 6e 20 73 65 63 6f r to it. On seco
31960 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e nd and subsequen
31970 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 t calls to.** sq
31980 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
31990 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 context() for th
319a0 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 e same aggregate
319b0 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64 65 78 2c function index,
319c0 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 .** the same buf
319d0 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e fer is returned.
319e0 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 The implementat
319f0 69 6f 6e 20 6f 66 20 74 68 65 20 61 67 67 72 65 ion of the aggre
31a00 67 61 74 65 20 63 61 6e 20 75 73 65 0a 2a 2a 20 gate can use.**
31a10 74 68 65 20 72 65 74 75 72 6e 65 64 20 62 75 66 the returned buf
31a20 66 65 72 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 fer to accumulat
31a30 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 e data..**.** SQ
31a40 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c Lite automatical
31a50 6c 79 20 66 72 65 65 73 20 74 68 65 20 61 6c 6c ly frees the all
31a60 6f 63 61 74 65 64 20 62 75 66 66 65 72 20 77 68 ocated buffer wh
31a70 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 en the aggregate
31a80 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 .** query conclu
31a90 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 des..**.** The f
31aa0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 73 irst parameter s
31ab0 68 6f 75 6c 64 20 62 65 20 61 20 63 6f 70 79 20 hould be a copy
31ac0 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 of the.** [sqlit
31ad0 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c e3_context | SQL
31ae0 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 function contex
31af0 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 t] that is the f
31b00 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a irst parameter.*
31b10 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 * to the callbac
31b20 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 k routine that i
31b30 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 mplements the ag
31b40 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e gregate function
31b50 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 ..**.** This rou
31b60 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c tine must be cal
31b70 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d led from the sam
31b80 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 e thread in whic
31b90 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 h.** the aggrega
31ba0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 te SQL function
31bb0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a is running..**.*
31bc0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
31bd0 0a 2a 2a 20 7b 48 31 36 32 31 31 7d 20 54 68 65 .** {H16211} The
31be0 20 66 69 72 73 74 20 69 6e 76 6f 63 61 74 69 6f first invocatio
31bf0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 61 67 n of [sqlite3_ag
31c00 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
31c10 43 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20 20 20 20 C,N)] for.**
31c20 20 20 20 20 20 20 61 20 70 61 72 74 69 63 75 6c a particul
31c30 61 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 61 ar instance of a
31c40 6e 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 n aggregate func
31c50 74 69 6f 6e 20 28 66 6f 72 20 61 20 70 61 72 74 tion (for a part
31c60 69 63 75 6c 61 72 0a 2a 2a 20 20 20 20 20 20 20 icular.**
31c70 20 20 20 63 6f 6e 74 65 78 74 20 43 29 20 63 61 context C) ca
31c80 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 61 uses SQLite to a
31c90 6c 6c 6f 63 61 74 65 20 4e 20 62 79 74 65 73 20 llocate N bytes
31ca0 6f 66 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 20 20 of memory,.**
31cb0 20 20 20 20 20 20 20 7a 65 72 6f 20 74 68 61 74 zero that
31cc0 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 memory, and ret
31cd0 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f urn a pointer to
31ce0 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 6d the allocated m
31cf0 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 emory..**.** {H1
31d00 36 32 31 33 7d 20 49 66 20 61 20 6d 65 6d 6f 72 6213} If a memor
31d10 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 y allocation err
31d20 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 or occurs during
31d30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
31d40 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
31d50 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 74 68 context(C,N)] th
31d60 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 en the function
31d70 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 0a 2a 2a returns 0..**.**
31d80 20 7b 48 31 36 32 31 35 7d 20 53 65 63 6f 6e 64 {H16215} Second
31d90 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 and subsequent
31da0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 0a 2a invocations of.*
31db0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
31dc0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
31dd0 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72 20 ntext(C,N)] for
31de0 74 68 65 20 73 61 6d 65 20 63 6f 6e 74 65 78 74 the same context
31df0 20 70 6f 69 6e 74 65 72 20 43 0a 2a 2a 20 20 20 pointer C.**
31e00 20 20 20 20 20 20 20 69 67 6e 6f 72 65 20 74 68 ignore th
31e10 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 61 6e e N parameter an
31e20 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 d return a point
31e30 65 72 20 74 6f 20 74 68 65 20 73 61 6d 65 0a 2a er to the same.*
31e40 2a 20 20 20 20 20 20 20 20 20 20 62 6c 6f 63 6b * block
31e50 20 6f 66 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 of memory retur
31e60 6e 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 ned by the first
31e70 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a invocation..**.
31e80 2a 2a 20 7b 48 31 36 32 31 37 7d 20 54 68 65 20 ** {H16217} The
31e90 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 memory allocated
31ea0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 by [sqlite3_agg
31eb0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 regate_context(C
31ec0 2c 4e 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 ,N)] is.**
31ed0 20 20 20 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c automaticall
31ee0 79 20 66 72 65 65 64 20 6f 6e 20 74 68 65 20 6e y freed on the n
31ef0 65 78 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ext call to [sql
31f00 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a ite3_reset()].**
31f10 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 or [sq
31f20 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
31f30 5d 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 ] for the [prepa
31f40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 63 red statement] c
31f50 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 20 20 20 ontaining.**
31f60 20 20 20 20 20 20 74 68 65 20 61 67 67 72 65 67 the aggreg
31f70 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 ate function ass
31f80 6f 63 69 61 74 65 64 20 77 69 74 68 20 63 6f 6e ociated with con
31f90 74 65 78 74 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 text C..*/.void
31fa0 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 *sqlite3_aggrega
31fb0 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 te_context(sqlit
31fc0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 e3_context*, int
31fd0 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a nBytes);../*.**
31fe0 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 CAPI3REF: User
31ff0 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f Data For Functio
32000 6e 73 20 7b 48 31 36 32 34 30 7d 20 3c 53 32 30 ns {H16240} <S20
32010 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 200>.**.** The s
32020 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 qlite3_user_data
32030 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 () interface ret
32040 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a urns a copy of.*
32050 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 * the pointer th
32060 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72 at was the pUser
32070 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 Data parameter (
32080 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 the 5th paramete
32090 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 r).** of the [sq
320a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
320b0 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 ction()].** and
320c0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
320d0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f function16()] ro
320e0 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 utines that orig
320f0 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 inally.** regist
32100 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 ered the applica
32110 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e tion defined fun
32120 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a ction. {END}.**.
32130 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
32140 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 must be called f
32150 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 rom the same thr
32160 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 ead in which.**
32170 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
32180 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
32190 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a is running..**.
321a0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
321b0 2a 0a 2a 2a 20 7b 48 31 36 32 34 33 7d 20 54 68 *.** {H16243} Th
321c0 65 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f e [sqlite3_user_
321d0 64 61 74 61 28 43 29 5d 20 69 6e 74 65 72 66 61 data(C)] interfa
321e0 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 ce returns a cop
321f0 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 y of the.**
32200 20 20 20 20 20 50 20 70 6f 69 6e 74 65 72 20 66 P pointer f
32210 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 rom the [sqlite3
32220 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
32230 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c (D,X,N,E,P,F,S,L
32240 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f )].** o
32250 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 r [sqlite3_creat
32260 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 e_function16(D,X
32270 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 ,N,E,P,F,S,L)] c
32280 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 all that.**
32290 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20 registered
322a0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
322b0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
322c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 [sqlite3_contex
322d0 74 5d 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 t] C..*/.void *s
322e0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 qlite3_user_data
322f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
32300 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
32310 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f REF: Database Co
32320 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e nnection For Fun
32330 63 74 69 6f 6e 73 20 7b 48 31 36 32 35 30 7d 20 ctions {H16250}
32340 3c 53 36 30 36 30 30 3e 3c 53 32 30 32 30 30 3e <S60600><S20200>
32350 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
32360 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 e3_context_db_ha
32370 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 ndle() interface
32380 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 returns a copy
32390 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 of.** the pointe
323a0 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 r to the [databa
323b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 se connection] (
323c0 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 the 1st paramete
323d0 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 r).** of the [sq
323e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
323f0 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 ction()].** and
32400 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
32410 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f function16()] ro
32420 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 utines that orig
32430 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 inally.** regist
32440 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 ered the applica
32450 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e tion defined fun
32460 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 ction..**.** INV
32470 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
32480 48 31 36 32 35 33 7d 20 54 68 65 20 5b 73 71 6c H16253} The [sql
32490 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f ite3_context_db_
324a0 68 61 6e 64 6c 65 28 43 29 5d 20 69 6e 74 65 72 handle(C)] inter
324b0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 face returns a c
324c0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 opy of the.**
324d0 20 20 20 20 20 20 20 44 20 70 6f 69 6e 74 65 72 D pointer
324e0 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 from the [sqlit
324f0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
32500 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 on(D,X,N,E,P,F,S
32510 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 ,L)].**
32520 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 or [sqlite3_cre
32530 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44 ate_function16(D
32540 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d ,X,N,E,P,F,S,L)]
32550 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 20 call that.**
32560 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65 registere
32570 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 d the SQL functi
32580 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 on associated wi
32590 74 68 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 th [sqlite3_cont
325a0 65 78 74 5d 20 43 2e 0a 2a 2f 0a 73 71 6c 69 74 ext] C..*/.sqlit
325b0 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 e3 *sqlite3_cont
325c0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 ext_db_handle(sq
325d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b lite3_context*);
325e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
325f0 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c : Function Auxil
32600 69 61 72 79 20 44 61 74 61 20 7b 48 31 36 32 37 iary Data {H1627
32610 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 0} <S20200>.**.*
32620 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 * The following
32630 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 two functions ma
32640 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61 y be used by sca
32650 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e lar SQL function
32660 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 s to.** associat
32670 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 e metadata with
32680 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e argument values.
32690 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c If the same val
326a0 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a ue is passed to.
326b0 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f ** multiple invo
326c0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 cations of the s
326d0 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ame SQL function
326e0 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 during query ex
326f0 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a ecution, under.*
32700 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 * some circumsta
32710 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 nces the associa
32720 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 ted metadata may
32730 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 be preserved. T
32740 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 his may.** be us
32750 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c ed, for example,
32760 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 to add a regula
32770 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 r-expression mat
32780 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 ching scalar.**
32790 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f function. The co
327a0 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f mpiled version o
327b0 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 f the regular ex
327c0 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 pression is stor
327d0 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 ed as.** metadat
327e0 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 a associated wit
327f0 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 h the SQL value
32800 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65 passed as the re
32810 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e gular expression
32820 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 .** pattern. Th
32830 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c e compiled regul
32840 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 ar expression ca
32850 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d n be reused on m
32860 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 ultiple.** invoc
32870 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 ations of the sa
32880 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 me function so t
32890 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c hat the original
328a0 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a pattern string.
328b0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 ** does not need
328c0 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 to be recompile
328d0 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 d on each invoca
328e0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 tion..**.** The
328f0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 sqlite3_get_auxd
32900 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 ata() interface
32910 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
32920 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 r to the metadat
32930 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 a.** associated
32940 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 by the sqlite3_s
32950 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e et_auxdata() fun
32960 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e ction with the N
32970 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 th argument.** v
32980 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c alue to the appl
32990 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
329a0 66 75 6e 63 74 69 6f 6e 2e 20 49 66 20 6e 6f 20 function. If no
329b0 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65 metadata has bee
329c0 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 n ever.** been s
329d0 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 et for the Nth a
329e0 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 rgument of the f
329f0 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 unction, or if t
32a00 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
32a10 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 .** function par
32a20 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 ameter has chang
32a30 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 ed since the met
32a40 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a a-data was set,.
32a50 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f ** then sqlite3_
32a60 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 get_auxdata() re
32a70 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 turns a NULL poi
32a80 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 nter..**.** The
32a90 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 sqlite3_set_auxd
32aa0 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 ata() interface
32ab0 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64 61 saves the metada
32ac0 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f ta.** pointed to
32ad0 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61 by its 3rd para
32ae0 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 meter as the met
32af0 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d adata for the N-
32b00 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f th.** argument o
32b10 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
32b20 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
32b30 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a on. Subsequent.
32b40 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 ** calls to sqli
32b50 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 te3_get_auxdata(
32b60 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 ) might return t
32b70 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 his data, if it
32b80 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 has.** not been
32b90 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 49 66 destroyed..** If
32ba0 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c it is not NULL,
32bb0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 SQLite will inv
32bc0 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 oke the destruct
32bd0 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 or.** function g
32be0 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 iven by the 4th
32bf0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
32c00 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 ite3_set_auxdata
32c10 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 () on.** the met
32c20 61 64 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 adata when the c
32c30 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e orresponding fun
32c40 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 ction parameter
32c50 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 changes.** or wh
32c60 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 en the SQL state
32c70 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 ment completes,
32c80 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 whichever comes
32c90 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c first..**.** SQL
32ca0 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 ite is free to c
32cb0 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 all the destruct
32cc0 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 or and drop meta
32cd0 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 data on any.** p
32ce0 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 arameter of any
32cf0 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 function at any
32d00 74 69 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20 time. The only
32d10 67 75 61 72 61 6e 74 65 65 20 69 73 20 74 68 61 guarantee is tha
32d20 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63 t.** the destruc
32d30 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c tor will be call
32d40 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 ed before the me
32d50 74 61 64 61 74 61 20 69 73 20 64 72 6f 70 70 65 tadata is droppe
32d60 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 d..**.** In prac
32d70 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 tice, metadata i
32d80 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 s preserved betw
32d90 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c een function cal
32da0 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 ls for.** expres
32db0 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 sions that are c
32dc0 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 onstant at compi
32dd0 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e le time. This in
32de0 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a cludes literal.*
32df0 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 53 51 4c * values and SQL
32e00 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a variables..**.*
32e10 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
32e20 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 must be called
32e30 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 from the same th
32e40 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a read in which.**
32e50 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
32e60 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a n is running..**
32e70 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
32e80 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 32 7d 20 54 **.** {H16272} T
32e90 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f he [sqlite3_get_
32ea0 61 75 78 64 61 74 61 28 43 2c 4e 29 5d 20 69 6e auxdata(C,N)] in
32eb0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
32ec0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 a pointer.**
32ed0 20 20 20 20 20 20 74 6f 20 6d 65 74 61 64 61 74 to metadat
32ee0 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 a associated wit
32ef0 68 20 74 68 65 20 4e 74 68 20 70 61 72 61 6d 65 h the Nth parame
32f00 74 65 72 20 6f 66 20 74 68 65 20 53 51 4c 20 66 ter of the SQL f
32f10 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 unction.**
32f20 20 20 20 20 77 68 6f 73 65 20 63 6f 6e 74 65 78 whose contex
32f30 74 20 69 73 20 43 2c 20 6f 72 20 4e 55 4c 4c 20 t is C, or NULL
32f40 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d if there is no m
32f50 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 etadata associat
32f60 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 ed.** w
32f70 69 74 68 20 74 68 61 74 20 70 61 72 61 6d 65 74 ith that paramet
32f80 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 er..**.** {H1627
32f90 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 4} The [sqlite3_
32fa0 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c set_auxdata(C,N,
32fb0 50 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 P,D)] interface
32fc0 61 73 73 69 67 6e 73 20 61 20 6d 65 74 61 64 61 assigns a metada
32fd0 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 ta.** p
32fe0 6f 69 6e 74 65 72 20 50 20 74 6f 20 74 68 65 20 ointer P to the
32ff0 4e 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 Nth parameter of
33000 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
33010 6e 20 77 69 74 68 20 63 6f 6e 74 65 78 74 20 43 n with context C
33020 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 36 7d ..**.** {H16276}
33030 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 SQLite will inv
33040 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 oke the destruct
33050 6f 72 20 44 20 77 69 74 68 20 61 20 73 69 6e 67 or D with a sing
33060 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 le argument.**
33070 20 20 20 20 20 20 20 20 77 68 69 63 68 20 69 73 which is
33080 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 70 6f the metadata po
33090 69 6e 74 65 72 20 50 20 66 6f 6c 6c 6f 77 69 6e inter P followin
330a0 67 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 g a call to.**
330b0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
330c0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e _set_auxdata(C,N
330d0 2c 50 2c 44 29 5d 20 77 68 65 6e 20 53 51 4c 69 ,P,D)] when SQLi
330e0 74 65 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c te ceases to hol
330f0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 d.** th
33100 65 20 6d 65 74 61 64 61 74 61 2e 0a 2a 2a 0a 2a e metadata..**.*
33110 2a 20 7b 48 31 36 32 37 37 7d 20 53 51 4c 69 74 * {H16277} SQLit
33120 65 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64 e ceases to hold
33130 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 61 6e metadata for an
33140 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 61 SQL function pa
33150 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 rameter.**
33160 20 20 20 20 77 68 65 6e 20 74 68 65 20 76 61 6c when the val
33170 75 65 20 6f 66 20 74 68 61 74 20 70 61 72 61 6d ue of that param
33180 65 74 65 72 20 63 68 61 6e 67 65 73 2e 0a 2a 2a eter changes..**
33190 0a 2a 2a 20 7b 48 31 36 32 37 38 7d 20 57 68 65 .** {H16278} Whe
331a0 6e 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 n [sqlite3_set_a
331b0 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d uxdata(C,N,P,D)]
331c0 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 is invoked, the
331d0 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 20 destructor.**
331e0 20 20 20 20 20 20 20 20 69 73 20 63 61 6c 6c 65 is calle
331f0 64 20 66 6f 72 20 61 6e 79 20 70 72 69 6f 72 20 d for any prior
33200 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 metadata associa
33210 74 65 64 20 77 69 74 68 20 74 68 65 20 73 61 6d ted with the sam
33220 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 e function.**
33230 20 20 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43 context C
33240 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20 4e and parameter N
33250 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 39 7d ..**.** {H16279}
33260 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 63 61 6c SQLite will cal
33270 6c 20 64 65 73 74 72 75 63 74 6f 72 73 20 66 6f l destructors fo
33280 72 20 61 6e 79 20 6d 65 74 61 64 61 74 61 20 69 r any metadata i
33290 74 20 69 73 20 68 6f 6c 64 69 6e 67 0a 2a 2a 20 t is holding.**
332a0 20 20 20 20 20 20 20 20 20 69 6e 20 61 20 70 61 in a pa
332b0 72 74 69 63 75 6c 61 72 20 5b 70 72 65 70 61 72 rticular [prepar
332c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 ed statement] S
332d0 77 68 65 6e 20 65 69 74 68 65 72 0a 2a 2a 20 20 when either.**
332e0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
332f0 5f 72 65 73 65 74 28 53 29 5d 20 6f 72 20 5b 73 _reset(S)] or [s
33300 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
33310 53 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a S)] is called..*
33320 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f /.void *sqlite3_
33330 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 get_auxdata(sqli
33340 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
33350 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 t N);.void sqlit
33360 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 e3_set_auxdata(s
33370 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
33380 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 int N, void*, v
33390 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b oid (*)(void*));
333a0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 .../*.** CAPI3RE
333b0 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 F: Constants Def
333c0 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 ining Special De
333d0 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f structor Behavio
333e0 72 20 7b 48 31 30 32 38 30 7d 20 3c 53 33 30 31 r {H10280} <S301
333f0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 00>.**.** These
33400 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 are special valu
33410 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 es for the destr
33420 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 uctor that is pa
33430 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a ssed in as the.*
33440 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 * final argument
33450 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b to routines lik
33460 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c e [sqlite3_resul
33470 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74 t_blob()]. If t
33480 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a he destructor.**
33490 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c argument is SQL
334a0 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d ITE_STATIC, it m
334b0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f eans that the co
334c0 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 ntent pointer is
334d0 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 constant.** and
334e0 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e will never chan
334f0 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 ge. It does not
33500 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 need to be dest
33510 72 6f 79 65 64 2e 20 20 54 68 65 0a 2a 2a 20 53 royed. The.** S
33520 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 QLITE_TRANSIENT
33530 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 value means that
33540 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c the content wil
33550 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 l likely change
33560 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 in.** the near f
33570 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 uture and that S
33580 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b QLite should mak
33590 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 e its own privat
335a0 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 e copy of.** the
335b0 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 content before
335c0 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a returning..**.**
335d0 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20 The typedef is
335e0 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 necessary to wor
335f0 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d k around problem
33600 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 s in certain.**
33610 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 C++ compilers.
33620 53 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 See ticket #2191
33630 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 ..*/.typedef voi
33640 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 d (*sqlite3_dest
33650 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 ructor_type)(voi
33660 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c d*);.#define SQL
33670 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 ITE_STATIC
33680 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 ((sqlite3_destru
33690 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 ctor_type)0).#de
336a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e fine SQLITE_TRAN
336b0 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 SIENT ((sqlite
336c0 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 3_destructor_typ
336d0 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 e)-1)../*.** CAP
336e0 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 I3REF: Setting T
336f0 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 he Result Of An
33700 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 7b 48 31 SQL Function {H1
33710 36 34 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 6400} <S20200>.*
33720 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
33730 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20 nes are used by
33740 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 the xFunc or xFi
33750 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 nal callbacks th
33760 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 at.** implement
33770 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e SQL functions an
33780 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 d aggregates. S
33790 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 ee.** [sqlite3_c
337a0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
337b0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 ] and [sqlite3_c
337c0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
337d0 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 ()].** for addit
337e0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f ional informatio
337f0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 n..**.** These f
33800 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 unctions work ve
33810 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 ry much like the
33820 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 [parameter bind
33830 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a ing] family of.*
33840 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 * functions used
33850 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 to bind values
33860 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 to host paramete
33870 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 rs in prepared s
33880 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 tatements..** Re
33890 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 fer to the [SQL
338a0 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d parameter] docum
338b0 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 entation for add
338c0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 itional informat
338d0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ion..**.** The s
338e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
338f0 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 ob() interface s
33900 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 ets the result f
33910 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 rom.** an applic
33920 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
33930 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 nction to be the
33940 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 BLOB whose cont
33950 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a ent is pointed.*
33960 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f * to by the seco
33970 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 nd parameter and
33980 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 which is N byte
33990 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 s long where N i
339a0 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 s the.** third p
339b0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 arameter..**.**
339c0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
339d0 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e lt_zeroblob() in
339e0 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65 terfaces set the
339f0 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 result of.** th
33a00 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
33a10 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 fined function t
33a20 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 o be a BLOB cont
33a30 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a aining all zero.
33a40 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 ** bytes and N b
33a50 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 ytes in size, wh
33a60 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c ere N is the val
33a70 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 ue of the 2nd pa
33a80 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 rameter..**.** T
33a90 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
33aa0 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 t_double() inter
33ab0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 face sets the re
33ac0 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 sult from.** an
33ad0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
33ae0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 ned function to
33af0 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f be a floating po
33b00 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 int value specif
33b10 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e ied.** by its 2n
33b20 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a d argument..**.*
33b30 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 * The sqlite3_re
33b40 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 sult_error() and
33b50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
33b60 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 error16() functi
33b70 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 ons.** cause the
33b80 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c implemented SQL
33b90 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 function to thr
33ba0 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e ow an exception.
33bb0 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 .** SQLite uses
33bc0 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 the string point
33bd0 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 ed to by the.**
33be0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 2nd parameter of
33bf0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
33c00 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 error() or sqlit
33c10 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 e3_result_error1
33c20 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 6().** as the te
33c30 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d xt of an error m
33c40 65 73 73 61 67 65 2e 20 20 53 51 4c 69 74 65 20 essage. SQLite
33c50 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 interprets the e
33c60 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 rror.** message
33c70 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 string from sqli
33c80 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
33c90 28 29 20 61 73 20 55 54 46 2d 38 2e 20 53 51 4c () as UTF-8. SQL
33ca0 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 ite.** interpret
33cb0 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f s the string fro
33cc0 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 m sqlite3_result
33cd0 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 _error16() as UT
33ce0 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a F-16 in native.*
33cf0 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 49 * byte order. I
33d00 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 f the third para
33d10 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
33d20 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a _result_error().
33d30 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 ** or sqlite3_re
33d40 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 sult_error16() i
33d50 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 s negative then
33d60 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 SQLite takes as
33d70 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 the error.** mes
33d80 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 sage all text up
33d90 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 through the fir
33da0 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 st zero characte
33db0 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 74 68 69 r..** If the thi
33dc0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
33dd0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
33de0 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c rror() or.** sql
33df0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
33e00 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 r16() is non-neg
33e10 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 ative then SQLit
33e20 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e e takes that man
33e30 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 y.** bytes (not
33e40 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d characters) from
33e50 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
33e60 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 er as the error
33e70 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 54 68 65 20 message..** The
33e80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
33e90 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 rror() and sqlit
33ea0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 e3_result_error1
33eb0 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6().** routines
33ec0 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 make a private c
33ed0 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 opy of the error
33ee0 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65 message text be
33ef0 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 fore.** they ret
33f00 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 urn. Hence, the
33f10 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f calling functio
33f20 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 n can deallocate
33f30 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 or.** modify th
33f40 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65 e text after the
33f50 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 y return without
33f60 20 68 61 72 6d 2e 0a 2a 2a 20 54 68 65 20 73 71 harm..** The sq
33f70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
33f80 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 or_code() functi
33f90 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 on changes the e
33fa0 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 rror code.** ret
33fb0 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 urned by SQLite
33fc0 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 as a result of a
33fd0 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e n error in a fun
33fe0 63 74 69 6f 6e 2e 20 20 42 79 20 64 65 66 61 75 ction. By defau
33ff0 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 lt,.** the error
34000 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f code is SQLITE_
34010 45 52 52 4f 52 2e 20 20 41 20 73 75 62 73 65 71 ERROR. A subseq
34020 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c uent call to sql
34030 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
34040 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 r().** or sqlite
34050 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 3_result_error16
34060 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72 () resets the er
34070 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 ror code to SQLI
34080 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 TE_ERROR..**.**
34090 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
340a0 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 lt_toobig() inte
340b0 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c rface causes SQL
340c0 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 ite to throw an
340d0 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 error.** indicat
340e0 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e ing that a strin
340f0 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 20 g or BLOB is to
34100 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e long to represen
34110 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c t..**.** The sql
34120 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 ite3_result_nome
34130 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 m() interface ca
34140 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 uses SQLite to t
34150 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a hrow an error.**
34160 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 indicating that
34170 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
34180 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a tion failed..**.
34190 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 ** The sqlite3_r
341a0 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 esult_int() inte
341b0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 rface sets the r
341c0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f eturn value.** o
341d0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
341e0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
341f0 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d on to be the 32-
34200 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 bit signed integ
34210 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 er.** value give
34220 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 n in the 2nd arg
34230 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 71 ument..** The sq
34240 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 lite3_result_int
34250 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 64() interface s
34260 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 ets the return v
34270 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 alue.** of the a
34280 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
34290 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ed function to b
342a0 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 e the 64-bit sig
342b0 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 ned integer.** v
342c0 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 alue given in th
342d0 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a e 2nd argument..
342e0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
342f0 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 3_result_null()
34300 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 interface sets t
34310 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a he return value.
34320 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 ** of the applic
34330 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
34340 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c nction to be NUL
34350 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c L..**.** The sql
34360 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
34370 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 (), sqlite3_resu
34380 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 lt_text16(),.**
34390 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
343a0 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 ext16le(), and s
343b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
343c0 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 xt16be() interfa
343d0 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 ces.** set the r
343e0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 eturn value of t
343f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
34400 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
34410 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 to be.** a text
34420 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 string which is
34430 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 represented as U
34440 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 TF-8, UTF-16 nat
34450 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a ive byte order,.
34460 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 ** UTF-16 little
34470 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d endian, or UTF-
34480 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 16 big endian, r
34490 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 espectively..**
344a0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 SQLite takes the
344b0 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f text result fro
344c0 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f m the applicatio
344d0 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e n from.** the 2n
344e0 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 d parameter of t
344f0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
34500 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 t_text* interfac
34510 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 es..** If the 3r
34520 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 d parameter to t
34530 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
34540 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 t_text* interfac
34550 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 es.** is negativ
34560 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 e, then SQLite t
34570 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 akes result text
34580 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 from the 2nd pa
34590 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 rameter.** throu
345a0 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 gh the first zer
345b0 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 o character..**
345c0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d If the 3rd param
345d0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 eter to the sqli
345e0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a te3_result_text*
345f0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 interfaces.** i
34600 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 s non-negative,
34610 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 then as many byt
34620 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 es (not characte
34630 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a rs) of the text.
34640 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 ** pointed to by
34650 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
34660 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 er are taken as
34670 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
34680 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 defined.** funct
34690 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 ion result..** I
346a0 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 f the 4th parame
346b0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ter to the sqlit
346c0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 e3_result_text*
346d0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 interfaces.** or
346e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
346f0 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 blob is a non-NU
34700 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e LL pointer, then
34710 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 SQLite calls th
34720 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 at.** function a
34730 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 s the destructor
34740 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 on the text or
34750 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e BLOB result when
34760 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 it has.** finis
34770 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 hed using that r
34780 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 esult..** If the
34790 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 4th parameter t
347a0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 o the sqlite3_re
347b0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 sult_text* inter
347c0 66 61 63 65 73 20 6f 72 0a 2a 2a 20 73 71 6c 69 faces or.** sqli
347d0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 te3_result_blob
347e0 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 is the special c
347f0 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 onstant SQLITE_S
34800 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 TATIC, then SQLi
34810 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 te.** assumes th
34820 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 at the text or B
34830 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e LOB result is in
34840 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 constant space
34850 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 and does not.**
34860 63 6f 70 79 20 74 68 65 20 69 74 20 6f 72 20 63 copy the it or c
34870 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 all a destructor
34880 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e when it has fin
34890 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 ished using that
348a0 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 result..** If t
348b0 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 he 4th parameter
348c0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
348d0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 result_text* int
348e0 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 erfaces.** or sq
348f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f lite3_result_blo
34900 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c b is the special
34910 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 constant SQLITE
34920 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 _TRANSIENT.** th
34930 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 en SQLite makes
34940 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 a copy of the re
34950 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 sult into space
34960 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a obtained from.**
34970 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
34980 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 alloc()] before
34990 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a it returns..**.*
349a0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 * The sqlite3_re
349b0 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 sult_value() int
349c0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 erface sets the
349d0 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 result of.** the
349e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
349f0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f ined function to
34a00 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a be a copy the.*
34a10 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 * [unprotected s
34a20 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
34a30 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62 ject specified b
34a40 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 y the 2nd parame
34a50 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c ter. The.** sql
34a60 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 ite3_result_valu
34a70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 e() interface ma
34a80 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 kes a copy of th
34a90 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 e [sqlite3_value
34aa0 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 ].** so that the
34ab0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d [sqlite3_value]
34ac0 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 specified in th
34ad0 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 e parameter may
34ae0 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 change or.** be
34af0 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 deallocated afte
34b00 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 r sqlite3_result
34b10 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 _value() returns
34b20 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a without harm..*
34b30 2a 20 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 * A [protected s
34b40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
34b50 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 ject may always
34b60 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e be used where an
34b70 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 .** [unprotected
34b80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
34b90 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 object is requir
34ba0 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a ed, so either.**
34bb0 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 kind of [sqlite
34bc0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
34bd0 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 can be used with
34be0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e this interface.
34bf0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 .**.** If these
34c00 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c routines are cal
34c10 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 led from within
34c20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 the different th
34c30 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 read.** than the
34c40 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 one containing
34c50 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
34c60 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
34c70 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a that received.*
34c80 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 * the [sqlite3_c
34c90 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c ontext] pointer,
34ca0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 the results are
34cb0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
34cc0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
34cd0 0a 2a 2a 20 7b 48 31 36 34 30 33 7d 20 54 68 65 .** {H16403} The
34ce0 20 64 65 66 61 75 6c 74 20 72 65 74 75 72 6e 20 default return
34cf0 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 79 20 53 value from any S
34d00 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 4e QL function is N
34d10 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 ULL..**.** {H164
34d20 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 06} The [sqlite3
34d30 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 _result_blob(C,V
34d40 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 ,N,D)] interface
34d50 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 changes the.**
34d60 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 return
34d70 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f value of functio
34d80 6e 20 43 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 n C to be a BLOB
34d90 20 74 68 61 74 20 69 73 20 4e 20 62 79 74 65 73 that is N bytes
34da0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 .** in
34db0 6c 65 6e 67 74 68 20 61 6e 64 20 77 69 74 68 20 length and with
34dc0 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 64 20 content pointed
34dd0 74 6f 20 62 79 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b to by V..**.** {
34de0 48 31 36 34 30 39 7d 20 54 68 65 20 5b 73 71 6c H16409} The [sql
34df0 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 ite3_result_doub
34e00 6c 65 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 le(C,V)] interfa
34e10 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a ce changes the.*
34e20 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 * retur
34e30 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 n value of funct
34e40 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 ion C to be the
34e50 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 floating point v
34e60 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 alue V..**.** {H
34e70 31 36 34 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 16412} The [sqli
34e80 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
34e90 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61 (C,V,N)] interfa
34ea0 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 ce changes the r
34eb0 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 eturn.**
34ec0 20 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 value of funct
34ed0 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 ion C to be an e
34ee0 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 xception with er
34ef0 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 ror code.**
34f00 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 [SQLITE_ERR
34f10 4f 52 5d 20 61 6e 64 20 61 20 55 54 46 2d 38 20 OR] and a UTF-8
34f20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 63 6f error message co
34f30 70 69 65 64 20 66 72 6f 6d 20 56 20 75 70 20 74 pied from V up t
34f40 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 o the.**
34f50 20 20 66 69 72 73 74 20 7a 65 72 6f 20 62 79 74 first zero byt
34f60 65 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 e or until N byt
34f70 65 73 20 61 72 65 20 72 65 61 64 20 69 66 20 4e es are read if N
34f80 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a is positive..**
34f90 0a 2a 2a 20 7b 48 31 36 34 31 35 7d 20 54 68 65 .** {H16415} The
34fa0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
34fb0 5f 65 72 72 6f 72 31 36 28 43 2c 56 2c 4e 29 5d _error16(C,V,N)]
34fc0 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 interface chang
34fd0 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a es the return.**
34fe0 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 value
34ff0 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f of function C to
35000 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e be an exception
35010 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 with error code
35020 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 .** [SQ
35030 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20 LITE_ERROR] and
35040 61 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 a UTF-16 native
35050 62 79 74 65 20 6f 72 64 65 72 20 65 72 72 6f 72 byte order error
35060 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 message.**
35070 20 20 20 20 20 63 6f 70 69 65 64 20 66 72 6f 6d copied from
35080 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 V up to the fir
35090 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 st zero terminat
350a0 6f 72 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 or or until N by
350b0 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 tes.**
350c0 61 72 65 20 72 65 61 64 20 69 66 20 4e 20 69 73 are read if N is
350d0 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a positive..**.**
350e0 20 7b 48 31 36 34 31 38 7d 20 54 68 65 20 5b 73 {H16418} The [s
350f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
35100 72 6f 72 5f 74 6f 6f 62 69 67 28 43 29 5d 20 69 ror_toobig(C)] i
35110 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 nterface changes
35120 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 the return.**
35130 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 value of
35140 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 the function C
35150 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 to be an excepti
35160 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f on with error co
35170 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b de.** [
35180 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 61 SQLITE_TOOBIG] a
35190 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 nd an appropriat
351a0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e e error message.
351b0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32 31 7d 20 .**.** {H16421}
351c0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 The [sqlite3_res
351d0 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 ult_error_nomem(
351e0 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 C)] interface ch
351f0 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e anges the return
35200 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c .** val
35210 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 ue of the functi
35220 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 on C to be an ex
35230 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 ception with err
35240 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 or code.**
35250 20 20 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 [SQLITE_NOME
35260 4d 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 M] and an approp
35270 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 riate error mess
35280 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 age..**.** {H164
35290 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 24} The [sqlite3
352a0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f _result_error_co
352b0 64 65 28 43 2c 45 29 5d 20 69 6e 74 65 72 66 61 de(C,E)] interfa
352c0 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 ce changes the r
352d0 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 eturn.**
352e0 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 value of the f
352f0 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 unction C to be
35300 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 an exception wit
35310 68 20 65 72 72 6f 72 20 63 6f 64 65 20 45 2e 0a h error code E..
35320 2a 2a 20 20 20 20 20 20 20 20 20 20 54 68 65 20 ** The
35330 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 error message te
35340 78 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e xt is unchanged.
35350 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32 37 7d 20 .**.** {H16427}
35360 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 The [sqlite3_res
35370 75 6c 74 5f 69 6e 74 28 43 2c 56 29 5d 20 69 6e ult_int(C,V)] in
35380 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 terface changes
35390 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
353a0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 return value of
353b0 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 function C to be
353c0 20 74 68 65 20 33 32 2d 62 69 74 20 69 6e 74 65 the 32-bit inte
353d0 67 65 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a ger value V..**.
353e0 2a 2a 20 7b 48 31 36 34 33 30 7d 20 54 68 65 20 ** {H16430} The
353f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
35400 69 6e 74 36 34 28 43 2c 56 29 5d 20 69 6e 74 65 int64(C,V)] inte
35410 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 rface changes th
35420 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 e.** re
35430 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 turn value of fu
35440 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 nction C to be t
35450 68 65 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 he 64-bit intege
35460 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a r value V..**.**
35470 20 7b 48 31 36 34 33 33 7d 20 54 68 65 20 5b 73 {H16433} The [s
35480 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 qlite3_result_nu
35490 6c 6c 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 ll(C)] interface
354a0 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 changes the.**
354b0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 return
354c0 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f value of functio
354d0 6e 20 43 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a n C to be NULL..
354e0 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 36 7d 20 54 **.** {H16436} T
354f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 he [sqlite3_resu
35500 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 lt_text(C,V,N,D)
35510 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e ] interface chan
35520 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 ges the.**
35530 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 return value
35540 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 of function C t
35550 6f 20 62 65 20 74 68 65 20 55 54 46 2d 38 20 73 o be the UTF-8 s
35560 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 tring.**
35570 20 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 V up to the fi
35580 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 rst zero if N is
35590 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 negative.**
355a0 20 20 20 20 20 20 6f 72 20 74 68 65 20 66 69 72 or the fir
355b0 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 st N bytes of V
355c0 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 if N is non-nega
355d0 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 tive..**.** {H16
355e0 34 33 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 439} The [sqlite
355f0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 3_result_text16(
35600 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 C,V,N,D)] interf
35610 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a ace changes the.
35620 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 ** retu
35630 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 rn value of func
35640 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 tion C to be the
35650 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 UTF-16 native b
35660 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 yte order.**
35670 20 20 20 20 20 20 73 74 72 69 6e 67 20 56 20 75 string V u
35680 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a p to the first z
35690 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61 ero if N is nega
356a0 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 tive.**
356b0 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 or the first N
356c0 62 79 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20 bytes of V if N
356d0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e is non-negative.
356e0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 32 7d 20 .**.** {H16442}
356f0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 The [sqlite3_res
35700 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 ult_text16be(C,V
35710 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 ,N,D)] interface
35720 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 changes the.**
35730 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 return
35740 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f value of functio
35750 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 n C to be the UT
35760 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a F-16 big-endian.
35770 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 ** stri
35780 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 ng V up to the f
35790 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 irst zero if N i
357a0 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 s negative.**
357b0 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 66 69 or the fi
357c0 72 73 74 20 4e 20 62 79 74 65 73 20 6f 72 20 56 rst N bytes or V
357d0 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 if N is non-neg
357e0 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ative..**.** {H1
357f0 36 34 34 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 6445} The [sqlit
35800 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
35810 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 le(C,V,N,D)] int
35820 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 erface changes t
35830 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 he.** r
35840 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 eturn value of f
35850 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 unction C to be
35860 74 68 65 20 55 54 46 2d 31 36 20 6c 69 74 74 6c the UTF-16 littl
35870 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 e-endian.**
35880 20 20 20 20 20 73 74 72 69 6e 67 20 56 20 75 70 string V up
35890 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 to the first ze
358a0 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 ro if N is negat
358b0 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ive.**
358c0 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 or the first N b
358d0 79 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69 ytes of V if N i
358e0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a s non-negative..
358f0 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 38 7d 20 54 **.** {H16448} T
35900 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 he [sqlite3_resu
35910 6c 74 5f 76 61 6c 75 65 28 43 2c 56 29 5d 20 69 lt_value(C,V)] i
35920 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 nterface changes
35930 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
35940 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 return value of
35950 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 function C to b
35960 65 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 e the [unprotect
35970 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
35980 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 ].** ob
35990 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ject V..**.** {H
359a0 31 36 34 35 31 7d 20 54 68 65 20 5b 73 71 6c 69 16451} The [sqli
359b0 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 te3_result_zerob
359c0 6c 6f 62 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66 lob(C,N)] interf
359d0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a ace changes the.
359e0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 ** retu
359f0 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 rn value of func
35a00 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 tion C to be an
35a10 4e 2d 62 79 74 65 20 42 4c 4f 42 20 6f 66 20 61 N-byte BLOB of a
35a20 6c 6c 20 7a 65 72 6f 73 2e 0a 2a 2a 0a 2a 2a 20 ll zeros..**.**
35a30 7b 48 31 36 34 35 34 7d 20 54 68 65 20 5b 73 71 {H16454} The [sq
35a40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
35a50 6f 72 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 or()] and [sqlit
35a60 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 e3_result_error1
35a70 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 6()].**
35a80 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b 65 interfaces make
35a90 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 69 72 a copy of their
35aa0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 error message s
35ab0 74 72 69 6e 67 73 20 62 65 66 6f 72 65 0a 2a 2a trings before.**
35ac0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e return
35ad0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 ing..**.** {H164
35ae0 35 37 7d 20 49 66 20 74 68 65 20 44 20 64 65 73 57} If the D des
35af0 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65 tructor paramete
35b00 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 r to [sqlite3_re
35b10 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c sult_blob(C,V,N,
35b20 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 D)],.**
35b30 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
35b40 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c _text(C,V,N,D)],
35b50 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
35b60 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 _text16(C,V,N,D)
35b70 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b ],.** [
35b80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
35b90 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 ext16be(C,V,N,D)
35ba0 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 ], or.**
35bb0 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c [sqlite3_resul
35bc0 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e t_text16le(C,V,N
35bd0 2c 44 29 5d 20 69 73 20 74 68 65 20 63 6f 6e 73 ,D)] is the cons
35be0 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 41 tant [SQLITE_STA
35bf0 54 49 43 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 TIC].**
35c00 20 74 68 65 6e 20 6e 6f 20 64 65 73 74 72 75 63 then no destruc
35c10 74 6f 72 20 69 73 20 65 76 65 72 20 63 61 6c 6c tor is ever call
35c20 65 64 20 6f 6e 20 74 68 65 20 70 6f 69 6e 74 65 ed on the pointe
35c30 72 20 56 20 61 6e 64 20 53 51 4c 69 74 65 0a 2a r V and SQLite.*
35c40 2a 20 20 20 20 20 20 20 20 20 20 61 73 73 75 6d * assum
35c50 65 73 20 74 68 61 74 20 56 20 69 73 20 69 6d 6d es that V is imm
35c60 75 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 utable..**.** {H
35c70 31 36 34 36 30 7d 20 49 66 20 74 68 65 20 44 20 16460} If the D
35c80 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d destructor param
35c90 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 eter to [sqlite3
35ca0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 _result_blob(C,V
35cb0 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 ,N,D)],.**
35cc0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 [sqlite3_res
35cd0 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 ult_text(C,V,N,D
35ce0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 )], [sqlite3_res
35cf0 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e ult_text16(C,V,N
35d00 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 ,D)],.**
35d10 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c [sqlite3_resul
35d20 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e t_text16be(C,V,N
35d30 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 ,D)], or.**
35d40 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 [sqlite3_re
35d50 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c sult_text16le(C,
35d60 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65 20 63 V,N,D)] is the c
35d70 6f 6e 73 74 61 6e 74 0a 2a 2a 20 20 20 20 20 20 onstant.**
35d80 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e [SQLITE_TRAN
35d90 53 49 45 4e 54 5d 20 74 68 65 6e 20 74 68 65 20 SIENT] then the
35da0 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b 65 73 interfaces makes
35db0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a a copy of the.*
35dc0 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 * conte
35dd0 6e 74 20 6f 66 20 56 20 61 6e 64 20 72 65 74 61 nt of V and reta
35de0 69 6e 73 20 74 68 65 20 63 6f 70 79 2e 0a 2a 2a ins the copy..**
35df0 0a 2a 2a 20 7b 48 31 36 34 36 33 7d 20 49 66 20 .** {H16463} If
35e00 74 68 65 20 44 20 64 65 73 74 72 75 63 74 6f 72 the D destructor
35e10 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 parameter to [s
35e20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
35e30 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a ob(C,V,N,D)],.**
35e40 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
35e50 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 e3_result_text(C
35e60 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 ,V,N,D)], [sqlit
35e70 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
35e80 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 (C,V,N,D)],.**
35e90 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
35ea0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 _result_text16be
35eb0 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a (C,V,N,D)], or.*
35ec0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
35ed0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 te3_result_text1
35ee0 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 6le(C,V,N,D)] is
35ef0 20 73 6f 6d 65 20 76 61 6c 75 65 20 6f 74 68 65 some value othe
35f00 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 r than.**
35f10 20 20 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 the constants
35f20 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d [SQLITE_STATIC]
35f30 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 54 52 41 and [SQLITE_TRA
35f40 4e 53 49 45 4e 54 5d 20 74 68 65 6e 0a 2a 2a 20 NSIENT] then.**
35f50 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 SQLite
35f60 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 will invoke the
35f70 64 65 73 74 72 75 63 74 6f 72 20 44 20 77 69 74 destructor D wit
35f80 68 20 56 20 61 73 20 69 74 73 20 6f 6e 6c 79 20 h V as its only
35f90 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 argument.**
35fa0 20 20 20 20 20 77 68 65 6e 20 69 74 20 68 61 73 when it has
35fb0 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 finished with t
35fc0 68 65 20 56 20 76 61 6c 75 65 2e 0a 2a 2f 0a 76 he V value..*/.v
35fd0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
35fe0 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f lt_blob(sqlite3_
35ff0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
36000 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 void*, int, void
36010 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 (*)(void*));.voi
36020 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
36030 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f _double(sqlite3_
36040 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 context*, double
36050 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
36060 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c result_error(sql
36070 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 ite3_context*, c
36080 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 onst char*, int)
36090 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
360a0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 esult_error16(sq
360b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
360c0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
360d0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
360e0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f result_error_too
360f0 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 big(sqlite3_cont
36100 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 ext*);.void sqli
36110 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
36120 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 _nomem(sqlite3_c
36130 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 ontext*);.void s
36140 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
36150 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 ror_code(sqlite3
36160 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b _context*, int);
36170 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
36180 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 sult_int(sqlite3
36190 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b _context*, int);
361a0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
361b0 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 sult_int64(sqlit
361c0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c e3_context*, sql
361d0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 ite3_int64);.voi
361e0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
361f0 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f _null(sqlite3_co
36200 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 ntext*);.void sq
36210 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
36220 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 t(sqlite3_contex
36230 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c t*, const char*,
36240 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f int, void(*)(vo
36250 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 id*));.void sqli
36260 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 te3_result_text1
36270 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 6(sqlite3_contex
36280 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c t*, const void*,
36290 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f int, void(*)(vo
362a0 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 id*));.void sqli
362b0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 te3_result_text1
362c0 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 6le(sqlite3_cont
362d0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 ext*, const void
362e0 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 *, int,void(*)(v
362f0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c oid*));.void sql
36300 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
36310 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 16be(sqlite3_con
36320 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 text*, const voi
36330 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 d*, int,void(*)(
36340 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 void*));.void sq
36350 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c lite3_result_val
36360 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ue(sqlite3_conte
36370 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c xt*, sqlite3_val
36380 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 ue*);.void sqlit
36390 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c e3_result_zerobl
363a0 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ob(sqlite3_conte
363b0 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a xt*, int n);../*
363c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
363d0 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 fine New Collati
363e0 6e 67 20 53 65 71 75 65 6e 63 65 73 20 7b 48 31 ng Sequences {H1
363f0 36 36 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 6600} <S20300>.*
36400 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 *.** These funct
36410 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f ions are used to
36420 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 add new collati
36430 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20 on sequences to
36440 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 the.** [database
36450 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 connection] spe
36460 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 cified as the fi
36470 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a rst argument..**
36480 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 .** The name of
36490 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f the new collatio
364a0 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 73 70 n sequence is sp
364b0 65 63 69 66 69 65 64 20 61 73 20 61 20 55 54 46 ecified as a UTF
364c0 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 -8 string.** for
364d0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
364e0 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 collation() and
364f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
36500 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a ollation_v2().**
36510 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 and a UTF-16 st
36520 72 69 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33 ring for sqlite3
36530 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
36540 6e 31 36 28 29 2e 20 49 6e 20 61 6c 6c 20 63 61 n16(). In all ca
36550 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 ses.** the name
36560 69 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 is passed as the
36570 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e second function
36580 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a argument..**.**
36590 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d The third argum
365a0 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f ent may be one o
365b0 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 f the constants
365c0 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a [SQLITE_UTF8],.*
365d0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c * [SQLITE_UTF16L
365e0 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 E] or [SQLITE_UT
365f0 46 31 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 F16BE], indicati
36600 6e 67 20 74 68 61 74 20 74 68 65 20 75 73 65 72 ng that the user
36610 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 -supplied.** rou
36620 74 69 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20 tine expects to
36630 62 65 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65 be passed pointe
36640 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e rs to strings en
36650 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d coded using UTF-
36660 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 8,.** UTF-16 lit
36670 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20 55 tle-endian, or U
36680 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e TF-16 big-endian
36690 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 , respectively.
366a0 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67 The.** third arg
366b0 75 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f ument might also
366c0 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 be [SQLITE_UTF1
366d0 36 5f 41 4c 49 47 4e 45 44 5d 20 74 6f 20 69 6e 6_ALIGNED] to in
366e0 64 69 63 61 74 65 20 74 68 61 74 0a 2a 2a 20 74 dicate that.** t
366f0 68 65 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 he routine expec
36700 74 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 ts pointers to 1
36710 36 2d 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 6-bit word align
36720 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 ed strings.** of
36730 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e UTF-16 in the n
36740 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
36750 20 6f 66 20 74 68 65 20 68 6f 73 74 20 63 6f 6d of the host com
36760 70 75 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 puter..**.** A p
36770 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75 73 ointer to the us
36780 65 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75 74 er supplied rout
36790 69 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73 73 ine must be pass
367a0 65 64 20 61 73 20 74 68 65 20 66 69 66 74 68 0a ed as the fifth.
367b0 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 ** argument. If
367c0 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 it is NULL, thi
367d0 73 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 s is the same as
367e0 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f deleting the co
367f0 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 llation.** seque
36800 6e 63 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c nce (so that SQL
36810 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 ite cannot call
36820 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20 it anymore)..**
36830 45 61 63 68 20 74 69 6d 65 20 74 68 65 20 61 70 Each time the ap
36840 70 6c 69 63 61 74 69 6f 6e 20 73 75 70 70 6c 69 plication suppli
36850 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 ed function is i
36860 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61 nvoked, it is pa
36870 73 73 65 64 0a 2a 2a 20 61 73 20 69 74 73 20 66 ssed.** as its f
36880 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 61 irst parameter a
36890 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 copy of the voi
368a0 64 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65 d* passed as the
368b0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 fourth argument
368c0 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 .** to sqlite3_c
368d0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 reate_collation(
368e0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 ) or sqlite3_cre
368f0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 ate_collation16(
36900 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d )..**.** The rem
36910 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 aining arguments
36920 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 to the applicat
36930 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 ion-supplied rou
36940 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74 72 tine are two str
36950 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 ings,.** each re
36960 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 28 presented by a (
36970 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 20 70 61 length, data) pa
36980 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 ir and encoded i
36990 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a n the encoding.*
369a0 2a 20 74 68 61 74 20 77 61 73 20 70 61 73 73 65 * that was passe
369b0 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 61 d as the third a
369c0 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 rgument when the
369d0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 collation seque
369e0 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 nce was.** regis
369f0 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20 20 54 68 tered. {END} Th
36a00 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 e application de
36a10 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 fined collation
36a20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a 2a routine should.*
36a30 2a 20 72 65 74 75 72 6e 20 6e 65 67 61 74 69 76 * return negativ
36a40 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74 e, zero or posit
36a50 69 76 65 20 69 66 20 74 68 65 20 66 69 72 73 74 ive if the first
36a60 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 string is less
36a70 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61 6c 20 74 than,.** equal t
36a80 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 o, or greater th
36a90 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 20 73 74 an the second st
36aa0 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52 49 ring. i.e. (STRI
36ab0 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a NG1 - STRING2)..
36ac0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
36ad0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
36ae0 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 on_v2() works li
36af0 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 ke sqlite3_creat
36b00 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a e_collation().**
36b10 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 except that it
36b20 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61 20 61 takes an extra a
36b30 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
36b40 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f a destructor fo
36b50 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 r.** the collati
36b60 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 on. The destruc
36b70 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68 tor is called wh
36b80 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e en the collation
36b90 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64 is.** destroyed
36ba0 20 61 6e 64 20 69 73 20 70 61 73 73 65 64 20 61 and is passed a
36bb0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75 copy of the fou
36bc0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f rth parameter vo
36bd0 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f id* pointer.** o
36be0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 f the sqlite3_cr
36bf0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 eate_collation_v
36c00 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74 69 6f 2()..** Collatio
36c10 6e 73 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 ns are destroyed
36c20 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f when they are o
36c30 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 verridden by lat
36c40 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a er calls to the.
36c50 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 ** collation cre
36c60 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 ation functions
36c70 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 64 61 74 or when the [dat
36c80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
36c90 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20 75 ] is closed.** u
36ca0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c sing [sqlite3_cl
36cb0 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e ose()]..**.** IN
36cc0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
36cd0 7b 48 31 36 36 30 33 7d 20 41 20 73 75 63 63 65 {H16603} A succe
36ce0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 74 68 ssful call to th
36cf0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 e.** [s
36d00 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
36d10 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 llation_v2(B,X,E
36d20 2c 50 2c 46 2c 44 29 5d 20 69 6e 74 65 72 66 61 ,P,F,D)] interfa
36d30 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 ce.** r
36d40 65 67 69 73 74 65 72 73 20 66 75 6e 63 74 69 6f egisters functio
36d50 6e 20 46 20 61 73 20 74 68 65 20 63 6f 6d 70 61 n F as the compa
36d60 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 75 rison function u
36d70 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 sed to.**
36d80 20 20 20 69 6d 70 6c 65 6d 65 6e 74 20 63 6f 6c implement col
36d90 6c 61 74 69 6f 6e 20 58 20 6f 6e 20 74 68 65 20 lation X on the
36da0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
36db0 74 69 6f 6e 5d 20 42 20 66 6f 72 0a 2a 2a 20 20 tion] B for.**
36dc0 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65 database
36dd0 73 20 68 61 76 69 6e 67 20 65 6e 63 6f 64 69 6e s having encodin
36de0 67 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 g E..**.** {H166
36df0 30 34 7d 20 53 51 4c 69 74 65 20 75 6e 64 65 72 04} SQLite under
36e00 73 74 61 6e 64 73 20 74 68 65 20 58 20 70 61 72 stands the X par
36e10 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 ameter to.**
36e20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 [sqlite3_c
36e30 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f reate_collation_
36e40 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d v2(B,X,E,P,F,D)]
36e50 20 61 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 as a zero-termi
36e60 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 nated.**
36e70 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 69 UTF-8 string i
36e80 6e 20 77 68 69 63 68 20 63 61 73 65 20 69 73 20 n which case is
36e90 69 67 6e 6f 72 65 64 20 66 6f 72 20 41 53 43 49 ignored for ASCI
36ea0 49 20 63 68 61 72 61 63 74 65 72 73 20 61 6e 64 I characters and
36eb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 .** is
36ec0 73 69 67 6e 69 66 69 63 61 6e 74 20 66 6f 72 20 significant for
36ed0 6e 6f 6e 2d 41 53 43 49 49 20 63 68 61 72 61 63 non-ASCII charac
36ee0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 ters..**.** {H16
36ef0 36 30 36 7d 20 53 75 63 63 65 73 73 69 76 65 20 606} Successive
36f00 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
36f10 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
36f20 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c on_v2(B,X,E,P,F,
36f30 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 D)].**
36f40 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 76 61 with the same va
36f50 6c 75 65 73 20 66 6f 72 20 42 2c 20 58 2c 20 61 lues for B, X, a
36f60 6e 64 20 45 2c 20 6f 76 65 72 72 69 64 65 20 70 nd E, override p
36f70 72 69 6f 72 20 76 61 6c 75 65 73 0a 2a 2a 20 20 rior values.**
36f80 20 20 20 20 20 20 20 20 6f 66 20 50 2c 20 46 2c of P, F,
36f90 20 61 6e 64 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 and D..**.** {H
36fa0 31 36 36 30 39 7d 20 49 66 20 74 68 65 20 64 65 16609} If the de
36fb0 73 74 72 75 63 74 6f 72 20 44 20 69 6e 20 5b 73 structor D in [s
36fc0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
36fd0 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 llation_v2(B,X,E
36fe0 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 ,P,F,D)].**
36ff0 20 20 20 20 20 69 73 20 6e 6f 74 20 4e 55 4c 4c is not NULL
37000 20 74 68 65 6e 20 69 74 20 69 73 20 63 61 6c 6c then it is call
37010 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 ed with argument
37020 20 50 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 20 P when the.**
37030 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e collatin
37040 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 g function is dr
37050 6f 70 70 65 64 20 62 79 20 53 51 4c 69 74 65 2e opped by SQLite.
37060 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31 32 7d 20 .**.** {H16612}
37070 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 A collating func
37080 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20 tion is dropped
37090 77 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 6c when it is overl
370a0 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 oaded..**.** {H1
370b0 36 36 31 35 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 6615} A collatin
370c0 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 g function is dr
370d0 6f 70 70 65 64 20 77 68 65 6e 20 74 68 65 20 64 opped when the d
370e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
370f0 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 on.** i
37100 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b s closed using [
37110 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d sqlite3_close()]
37120 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31 38 7d ..**.** {H16618}
37130 20 54 68 65 20 70 6f 69 6e 74 65 72 20 50 20 69 The pointer P i
37140 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 n [sqlite3_creat
37150 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 e_collation_v2(B
37160 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 ,X,E,P,F,D)].**
37170 20 20 20 20 20 20 20 20 20 69 73 20 70 61 73 73 is pass
37180 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 ed through as th
37190 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
371a0 72 20 74 6f 20 74 68 65 20 63 6f 6d 70 61 72 69 r to the compari
371b0 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 son.**
371c0 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20 61 function F for a
371d0 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e ll subsequent in
371e0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 46 2e 0a vocations of F..
371f0 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 31 7d 20 41 **.** {H16621} A
37200 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
37210 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
37220 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 69 on(B,X,E,P,F)] i
37230 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20 s exactly.**
37240 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 61 the same a
37250 73 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c s a call to [sql
37260 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
37270 61 74 69 6f 6e 5f 76 32 28 29 5d 20 77 69 74 68 ation_v2()] with
37280 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
37290 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65 72 73 same parameters
372a0 20 61 6e 64 20 61 20 4e 55 4c 4c 20 64 65 73 74 and a NULL dest
372b0 72 75 63 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ructor..**.** {H
372c0 31 36 36 32 34 7d 20 46 6f 6c 6c 6f 77 69 6e 67 16624} Following
372d0 20 61 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 a [sqlite3_crea
372e0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 te_collation_v2(
372f0 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 2c 0a 2a B,X,E,P,F,D)],.*
37300 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 * SQLit
37310 65 20 75 73 65 73 20 74 68 65 20 63 6f 6d 70 61 e uses the compa
37320 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 46 rison function F
37330 20 66 6f 72 20 61 6c 6c 20 74 65 78 74 20 63 6f for all text co
37340 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 mparison.**
37350 20 20 20 20 20 6f 70 65 72 61 74 69 6f 6e 73 20 operations
37360 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 on the [database
37370 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20 6f connection] B o
37380 6e 20 74 65 78 74 20 76 61 6c 75 65 73 20 74 68 n text values th
37390 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 at.** u
373a0 73 65 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 se the collating
373b0 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 64 20 sequence named
373c0 58 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 37 X..**.** {H16627
373d0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 } The [sqlite3_c
373e0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 reate_collation1
373f0 36 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 77 6f 6(B,X,E,P,F)] wo
37400 72 6b 73 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 rks the same.**
37410 20 20 20 20 20 20 20 20 20 61 73 20 5b 73 71 6c as [sql
37420 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
37430 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29 ation(B,X,E,P,F)
37440 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 ] except that th
37450 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f e.** co
37460 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69 llation name X i
37470 73 20 75 6e 64 65 72 73 74 6f 6f 64 20 61 73 20 s understood as
37480 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 UTF-16 in native
37490 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 byte order.**
374a0 20 20 20 20 20 20 20 20 69 6e 73 74 65 61 64 20 instead
374b0 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 of UTF-8..**.**
374c0 7b 48 31 36 36 33 30 7d 20 57 68 65 6e 20 6d 75 {H16630} When mu
374d0 6c 74 69 70 6c 65 20 63 6f 6d 70 61 72 69 73 6f ltiple compariso
374e0 6e 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 n functions are
374f0 61 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 74 68 available for th
37500 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 e same.**
37510 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 collating seq
37520 75 65 6e 63 65 2c 20 53 51 4c 69 74 65 20 63 68 uence, SQLite ch
37530 6f 6f 73 65 73 20 74 68 65 20 6f 6e 65 20 77 68 ooses the one wh
37540 6f 73 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e ose text encodin
37550 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 g.** re
37560 71 75 69 72 65 73 20 74 68 65 20 6c 65 61 73 74 quires the least
37570 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 76 65 amount of conve
37580 72 73 69 6f 6e 20 66 72 6f 6d 20 74 68 65 20 64 rsion from the d
37590 65 66 61 75 6c 74 0a 2a 2a 20 20 20 20 20 20 20 efault.**
375a0 20 20 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 text encoding
375b0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
375c0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
375d0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
375e0 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a n(. sqlite3*, .
375f0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e const char *zN
37600 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 ame, . int eTex
37610 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a tRep, . void*,.
37620 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 int(*xCompare)
37630 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 (void*,int,const
37640 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 void*,int,const
37650 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 void*).);.int s
37660 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
37670 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 llation_v2(. sq
37680 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 lite3*, . const
37690 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 char *zName, .
376a0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a int eTextRep, .
376b0 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a void*,. int(*
376c0 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c xCompare)(void*,
376d0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c int,const void*,
376e0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 int,const void*)
376f0 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 ,. void(*xDestr
37700 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e oy)(void*).);.in
37710 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
37720 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 _collation16(.
37730 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e sqlite3*, . con
37740 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a st void *zName,.
37750 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 int eTextRep,
37760 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 . void*,. int(
37770 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a *xCompare)(void*
37780 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a ,int,const void*
37790 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a ,int,const void*
377a0 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ).);../*.** CAPI
377b0 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 3REF: Collation
377c0 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 Needed Callbacks
377d0 20 7b 48 31 36 37 30 30 7d 20 3c 53 32 30 33 30 {H16700} <S2030
377e0 30 3e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 0>.**.** To avoi
377f0 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 d having to regi
37800 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 ster all collati
37810 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 on sequences bef
37820 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a ore a database.*
37830 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 * can be used, a
37840 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b single callback
37850 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 function may be
37860 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 registered with
37870 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 the.** [databas
37880 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f e connection] to
37890 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 be called whene
378a0 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 ver an undefined
378b0 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 collation.** se
378c0 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 quence is requir
378d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 ed..**.** If the
378e0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 function is reg
378f0 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 istered using th
37900 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 e sqlite3_collat
37910 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 ion_needed() API
37920 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 ,.** then it is
37930 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 passed the names
37940 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f of undefined co
37950 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 llation sequence
37960 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 s as strings.**
37970 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 encoded in UTF-8
37980 2e 20 7b 48 31 36 37 30 33 7d 20 49 66 20 73 71 . {H16703} If sq
37990 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
379a0 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73 needed16() is us
379b0 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 ed,.** the names
379c0 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55 are passed as U
379d0 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 TF-16 in machine
379e0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
379f0 65 72 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f er..** A call to
37a00 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e either function
37a10 20 72 65 70 6c 61 63 65 73 20 61 6e 79 20 65 78 replaces any ex
37a20 69 73 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e isting callback.
37a30 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 .**.** When the
37a40 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
37a50 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 ked, the first a
37a60 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 rgument passed i
37a70 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 s a copy.** of t
37a80 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
37a90 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f nt to sqlite3_co
37aa0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 llation_needed()
37ab0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 or.** sqlite3_c
37ac0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 ollation_needed1
37ad0 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 6(). The second
37ae0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
37af0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e database.** con
37b00 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 nection. The th
37b10 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ird argument is
37b20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 one of [SQLITE_U
37b30 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 TF8], [SQLITE_UT
37b40 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 F16BE],.** or [S
37b50 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 QLITE_UTF16LE],
37b60 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d indicating the m
37b70 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f ost desirable fo
37b80 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 rm of the collat
37b90 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 ion.** sequence
37ba0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 function require
37bb0 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 d. The fourth p
37bc0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 arameter is the
37bd0 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 name of the.** r
37be0 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f equired collatio
37bf0 6e 20 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a n sequence..**.*
37c00 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 * The callback f
37c10 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 unction should r
37c20 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69 egister the desi
37c30 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 red collation us
37c40 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
37c50 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
37c60 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 ()], [sqlite3_cr
37c70 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 eate_collation16
37c80 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 ()], or.** [sqli
37c90 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
37ca0 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a tion_v2()]..**.*
37cb0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
37cc0 0a 2a 2a 20 7b 48 31 36 37 30 32 7d 20 41 20 73 .** {H16702} A s
37cd0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 uccessful call t
37ce0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 o [sqlite3_colla
37cf0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 44 2c 50 2c tion_needed(D,P,
37d00 46 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 F)].**
37d10 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c or [sqlite3_coll
37d20 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 44 ation_needed16(D
37d30 2c 50 2c 46 29 5d 20 63 61 75 73 65 73 0a 2a 2a ,P,F)] causes.**
37d40 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 64 the [d
37d50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
37d60 6f 6e 5d 20 44 20 74 6f 20 69 6e 76 6f 6b 65 20 on] D to invoke
37d70 63 61 6c 6c 62 61 63 6b 20 46 20 77 69 74 68 20 callback F with
37d80 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 first.**
37d90 20 20 70 61 72 61 6d 65 74 65 72 20 50 20 77 68 parameter P wh
37da0 65 6e 65 76 65 72 20 69 74 20 6e 65 65 64 73 20 enever it needs
37db0 61 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e a comparison fun
37dc0 63 74 69 6f 6e 20 66 6f 72 20 61 0a 2a 2a 20 20 ction for a.**
37dd0 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e collatin
37de0 67 20 73 65 71 75 65 6e 63 65 20 74 68 61 74 20 g sequence that
37df0 69 74 20 64 6f 65 73 20 6e 6f 74 20 6b 6e 6f 77 it does not know
37e00 20 61 62 6f 75 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 about..**.** {H
37e10 31 36 37 30 34 7d 20 45 61 63 68 20 73 75 63 63 16704} Each succ
37e20 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b essful call to [
37e30 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f sqlite3_collatio
37e40 6e 5f 6e 65 65 64 65 64 28 29 5d 20 6f 72 0a 2a n_needed()] or.*
37e50 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
37e60 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 te3_collation_ne
37e70 65 64 65 64 31 36 28 29 5d 20 6f 76 65 72 72 69 eded16()] overri
37e80 64 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b des the callback
37e90 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 registered.**
37ea0 20 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73 on the s
37eb0 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f ame [database co
37ec0 6e 6e 65 63 74 69 6f 6e 5d 20 62 79 20 70 72 69 nnection] by pri
37ed0 6f 72 20 63 61 6c 6c 73 20 74 6f 20 65 69 74 68 or calls to eith
37ee0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 er.** i
37ef0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 nterface..**.**
37f00 7b 48 31 36 37 30 36 7d 20 54 68 65 20 6e 61 6d {H16706} The nam
37f10 65 20 6f 66 20 74 68 65 20 72 65 71 75 65 73 74 e of the request
37f20 65 64 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e ed collating fun
37f30 63 74 69 6f 6e 20 70 61 73 73 65 64 20 69 6e 20 ction passed in
37f40 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
37f50 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 4th parameter to
37f60 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 the callback is
37f70 20 69 6e 20 55 54 46 2d 38 20 69 66 20 74 68 65 in UTF-8 if the
37f80 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 callback.**
37f90 20 20 20 20 20 20 77 61 73 20 72 65 67 69 73 74 was regist
37fa0 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 ered using [sqli
37fb0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 te3_collation_ne
37fc0 65 64 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 eded()] and.**
37fd0 20 20 20 20 20 20 20 20 69 73 20 69 6e 20 55 54 is in UT
37fe0 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 F-16 native byte
37ff0 20 6f 72 64 65 72 20 69 66 20 74 68 65 20 63 61 order if the ca
38000 6c 6c 62 61 63 6b 20 77 61 73 0a 2a 2a 20 20 20 llback was.**
38010 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65 registere
38020 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
38030 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 _collation_neede
38040 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 d16()]..*/.int s
38050 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
38060 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 _needed(. sqlit
38070 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a e3*, . void*, .
38080 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c void(*)(void*,
38090 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 sqlite3*,int eTe
380a0 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 xtRep,const char
380b0 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 *).);.int sqlite
380c0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 3_collation_need
380d0 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a ed16(. sqlite3*
380e0 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f , . void*,. vo
380f0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 id(*)(void*,sqli
38100 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 te3*,int eTextRe
38110 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 p,const void*).)
38120 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 ;../*.** Specify
38130 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 the key for an
38140 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61 encrypted databa
38150 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e se. This routin
38160 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 e should be.** c
38170 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 alled right afte
38180 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 r sqlite3_open()
38190 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 ..**.** The code
381a0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 to implement th
381b0 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 is API is not av
381c0 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 ailable in the p
381d0 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a ublic release.**
381e0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 of SQLite..*/.i
381f0 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a nt sqlite3_key(.
38200 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
38210 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
38220 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 /* Database to
38230 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 be rekeyed */.
38240 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 const void *pKey
38250 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f , int nKey /
38260 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a * The key */.);.
38270 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 ./*.** Change th
38280 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e e key on an open
38290 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 database. If t
382a0 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 he current datab
382b0 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e ase is not.** en
382c0 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f crypted, this ro
382d0 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 utine will encry
382e0 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d pt it. If pNew=
382f0 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 =0 or nNew==0, t
38300 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 he.** database i
38310 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a s decrypted..**.
38320 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 ** The code to i
38330 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 mplement this AP
38340 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 I is not availab
38350 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 le in the public
38360 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 release.** of S
38370 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 QLite..*/.int sq
38380 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 lite3_rekey(. s
38390 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
383a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
383b0 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 Database to be
383c0 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e rekeyed */. con
383d0 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 st void *pKey, i
383e0 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 nt nKey /* T
383f0 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b he new key */.);
38400 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
38410 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 : Suspend Execut
38420 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 ion For A Short
38430 54 69 6d 65 20 7b 48 31 30 35 33 30 7d 20 3c 53 Time {H10530} <S
38440 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 40410>.**.** The
38450 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 sqlite3_sleep()
38460 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 function causes
38470 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 the current thr
38480 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 ead to suspend e
38490 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 xecution.** for
384a0 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 at least a numbe
384b0 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 r of millisecond
384c0 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 s specified in i
384d0 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a ts parameter..**
384e0 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 .** If the opera
384f0 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 ting system does
38500 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 not support sle
38510 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68 ep requests with
38520 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 .** millisecond
38530 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c time resolution,
38540 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 then the time w
38550 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 ill be rounded u
38560 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 p to.** the near
38570 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 est second. The
38580 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 number of millis
38590 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 econds of sleep
385a0 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 actually.** requ
385b0 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f ested from the o
385c0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 perating system
385d0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a is returned..**.
385e0 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d ** SQLite implem
385f0 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 ents this interf
38600 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 ace by calling t
38610 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d he xSleep().** m
38620 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 ethod of the def
38630 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 ault [sqlite3_vf
38640 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a s] object..**.**
38650 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
38660 2a 2a 20 7b 48 31 30 35 33 33 7d 20 54 68 65 20 ** {H10533} The
38670 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d [sqlite3_sleep(M
38680 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 6e 76 )] interface inv
38690 6f 6b 65 73 20 74 68 65 20 78 53 6c 65 65 70 0a okes the xSleep.
386a0 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 74 68 ** meth
386b0 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c od of the defaul
386c0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 7c 56 t [sqlite3_vfs|V
386d0 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a FS] in order to.
386e0 2a 2a 20 20 20 20 20 20 20 20 20 20 73 75 73 70 ** susp
386f0 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 end execution of
38700 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 the current thr
38710 65 61 64 20 66 6f 72 20 61 74 20 6c 65 61 73 74 ead for at least
38720 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4d 20 6d .** M m
38730 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2a 0a illiseconds..**.
38740 2a 2a 20 7b 48 31 30 35 33 36 7d 20 54 68 65 20 ** {H10536} The
38750 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d [sqlite3_sleep(M
38760 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
38770 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
38780 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d of.** m
38790 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 illiseconds of s
387a0 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 20 72 65 leep actually re
387b0 71 75 65 73 74 65 64 20 6f 66 20 74 68 65 20 6f quested of the o
387c0 70 65 72 61 74 69 6e 67 0a 2a 2a 20 20 20 20 20 perating.**
387d0 20 20 20 20 20 73 79 73 74 65 6d 2c 20 77 68 69 system, whi
387e0 63 68 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67 ch might be larg
387f0 65 72 20 74 68 61 6e 20 74 68 65 20 70 61 72 61 er than the para
38800 6d 65 74 65 72 20 4d 2e 0a 2a 2f 0a 69 6e 74 20 meter M..*/.int
38810 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e sqlite3_sleep(in
38820 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
38830 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 REF: Name Of The
38840 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 Folder Holding
38850 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 20 Temporary Files
38860 7b 48 31 30 33 31 30 7d 20 3c 53 32 30 30 30 30 {H10310} <S20000
38870 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20 >.**.** If this
38880 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 global variable
38890 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 is made to point
388a0 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 to a string whi
388b0 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d ch is.** the nam
388c0 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 e of a folder (a
388d0 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 .k.a.