0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65 /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69 e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20 ms copyright to
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a . In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73 , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d sing:.**.** M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 nd not evil..**
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 May you find
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20 forgiveness for
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 give others..**
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65 May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 aking more than
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68 ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65 that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73 library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70 ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43 rograms. If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63 -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64 ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69 ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20 s file, then it
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20 ite, is subject
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64 t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72 should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53 grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74 e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70 arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70 erimental". Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65 y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64 s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20 to SQLite. We
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74 do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 e changes.** to
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65 erfaces but rese
03b0: 72 76 65 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f rve to make mino
03c0: 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a 20 r changes if.**
03d0: 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20 experience from
03e0: 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64 use "in the wild
03f0: 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20 63 " suggest such c
0400: 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64 65 hanges are prude
0410: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66 nt..**.** The of
0420: 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67 ficial C-languag
0430: 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74 e API documentat
0440: 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69 ion for SQLite i
0450: 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f s derived.** fro
0460: 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68 m comments in th
0470: 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66 is file. This f
0480: 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68 6f ile is the autho
0490: 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a ritative source.
04a0: 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65 ** on how SQLite
04b0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
04c0: 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61 suppose to opera
04d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 te..**.** The na
04e0: 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20 me of this file
04f0: 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74 under configurat
0500: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69 ion management i
0510: 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e s "sqlite.h.in".
0520: 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65 .** The makefile
0530: 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f makes some mino
0540: 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69 r changes to thi
0550: 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 20 s file (such as
0560: 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65 inserting.** the
0570: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29 version number)
0580: 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73 and changes its
0590: 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65 name to "sqlite
05a0: 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20 3.h" as.** part
05b0: 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f of the build pro
05c0: 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23 29 cess..**.** @(#)
05d0: 20 24 49 64 3a 20 73 71 6c 69 74 65 2e 68 2e 69 $Id: sqlite.h.i
05e0: 6e 2c 76 20 31 2e 34 30 36 20 32 30 30 38 2f 31 n,v 1.406 2008/1
05f0: 30 2f 33 30 20 31 35 3a 30 33 3a 31 36 20 64 72 0/30 15:03:16 dr
0600: 68 20 45 78 70 20 24 0a 2a 2f 0a 23 69 66 6e 64 h Exp $.*/.#ifnd
0610: 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 ef _SQLITE3_H_.#
0620: 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f define _SQLITE3_
0630: 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 H_.#include <std
0640: 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 arg.h> /* Ne
0650: 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 eded for the def
0660: 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 inition of va_li
0670: 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b st */../*.** Mak
0680: 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 e sure we can ca
0690: 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66 72 ll this stuff fr
06a0: 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65 om C++..*/.#ifde
06b0: 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78 f __cplusplus.ex
06c0: 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 tern "C" {.#endi
06d0: 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 68 f.../*.** Add th
06e0: 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 e ability to ove
06f0: 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a 2a rride 'extern'.*
0700: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 /.#ifndef SQLITE
0710: 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e 65 _EXTERN.# define
0720: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 65 SQLITE_EXTERN e
0730: 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 2f 2a xtern.#endif../*
0740: 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 .** These no-op
0750: 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65 64 20 macros are used
0760: 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 in front of inte
0770: 72 66 61 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 rfaces to mark t
0780: 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 hose.** interfac
0790: 65 73 20 61 73 20 65 69 74 68 65 72 20 64 65 70 es as either dep
07a0: 72 65 63 61 74 65 64 20 6f 72 20 65 78 70 65 72 recated or exper
07b0: 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 imental. New ap
07c0: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 plications.** sh
07d0: 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 64 65 70 ould not use dep
07e0: 72 65 63 61 74 65 64 20 69 6e 74 72 66 61 63 65 recated intrface
07f0: 73 20 2d 20 74 68 65 79 20 61 72 65 20 73 75 70 s - they are sup
0800: 70 6f 72 74 20 66 6f 72 20 62 61 63 6b 77 61 72 port for backwar
0810: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c ds.** compatibil
0820: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 ity only. Appli
0830: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73 cation writers s
0840: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74 hould be aware t
0850: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e hat.** experimen
0860: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 tal interfaces a
0870: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 re subject to ch
0880: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 ange in point re
0890: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 leases..**.** Th
08a0: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20 ese macros used
08b0: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 to resolve to va
08c0: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 rious kinds of c
08d0: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68 ompiler magic th
08e0: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 at.** would gene
08f0: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 rate warning mes
0900: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20 sages when they
0910: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20 were used. But
0920: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 that.** compiler
0930: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20 magic ended up
0940: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20 generating such
0950: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20 a flurry of bug
0960: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 reports.** that
0970: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74 we have taken it
0980: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e all out and gon
0990: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 e back to using
09a0: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d simple.** noop m
09b0: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e acros..*/.#defin
09c0: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 e SQLITE_DEPRECA
09d0: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 TED.#define SQLI
09e0: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a TE_EXPERIMENTAL.
09f0: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 ./*.** Ensure th
0a00: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 ese symbols were
0a10: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20 not defined by
0a20: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65 some previous he
0a30: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 ader file..*/.#i
0a40: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 fdef SQLITE_VERS
0a50: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 ION.# undef SQLI
0a60: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 TE_VERSION.#endi
0a70: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f f.#ifdef SQLITE_
0a80: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 VERSION_NUMBER.#
0a90: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 undef SQLITE_VE
0aa0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e RSION_NUMBER.#en
0ab0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 dif../*.** CAPI3
0ac0: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d REF: Compile-Tim
0ad0: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f e Library Versio
0ae0: 6e 20 4e 75 6d 62 65 72 73 20 7b 48 31 30 30 31 n Numbers {H1001
0af0: 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a 0} <S60100>.**.*
0b00: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 * The SQLITE_VER
0b10: 53 49 4f 4e 20 61 6e 64 20 53 51 4c 49 54 45 5f SION and SQLITE_
0b20: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 23 VERSION_NUMBER #
0b30: 64 65 66 69 6e 65 73 20 69 6e 0a 2a 2a 20 74 68 defines in.** th
0b40: 65 20 73 71 6c 69 74 65 33 2e 68 20 66 69 6c 65 e sqlite3.h file
0b50: 20 73 70 65 63 69 66 79 20 74 68 65 20 76 65 72 specify the ver
0b60: 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 77 sion of SQLite w
0b70: 69 74 68 20 77 68 69 63 68 0a 2a 2a 20 74 68 61 ith which.** tha
0b80: 74 20 68 65 61 64 65 72 20 66 69 6c 65 20 69 73 t header file is
0b90: 20 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a associated..**.
0ba0: 2a 2a 20 54 68 65 20 22 76 65 72 73 69 6f 6e 22 ** The "version"
0bb0: 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 61 20 of SQLite is a
0bc0: 73 74 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6f string of the fo
0bd0: 72 6d 20 22 58 2e 59 2e 5a 22 2e 0a 2a 2a 20 54 rm "X.Y.Z"..** T
0be0: 68 65 20 70 68 72 61 73 65 20 22 61 6c 70 68 61 he phrase "alpha
0bf0: 22 20 6f 72 20 22 62 65 74 61 22 20 6d 69 67 68 " or "beta" migh
0c00: 74 20 62 65 20 61 70 70 65 6e 64 65 64 20 61 66 t be appended af
0c10: 74 65 72 20 74 68 65 20 5a 2e 0a 2a 2a 20 54 68 ter the Z..** Th
0c20: 65 20 58 20 76 61 6c 75 65 20 69 73 20 6d 61 6a e X value is maj
0c30: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 or version numbe
0c40: 72 20 61 6c 77 61 79 73 20 33 20 69 6e 20 53 51 r always 3 in SQ
0c50: 4c 69 74 65 33 2e 0a 2a 2a 20 54 68 65 20 58 20 Lite3..** The X
0c60: 76 61 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67 value only chang
0c70: 65 73 20 77 68 65 6e 20 62 61 63 6b 77 61 72 64 es when backward
0c80: 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 s compatibility
0c90: 69 73 0a 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64 is.** broken and
0ca0: 20 77 65 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65 we intend to ne
0cb0: 76 65 72 20 62 72 65 61 6b 20 62 61 63 6b 77 61 ver break backwa
0cc0: 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 rds compatibilit
0cd0: 79 2e 0a 2a 2a 20 54 68 65 20 59 20 76 61 6c 75 y..** The Y valu
0ce0: 65 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 e is the minor v
0cf0: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e ersion number an
0d00: 64 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77 d only changes w
0d10: 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 61 72 65 hen.** there are
0d20: 20 6d 61 6a 6f 72 20 66 65 61 74 75 72 65 20 65 major feature e
0d30: 6e 68 61 6e 63 65 6d 65 6e 74 73 20 74 68 61 74 nhancements that
0d40: 20 61 72 65 20 66 6f 72 77 61 72 64 73 20 63 6f are forwards co
0d50: 6d 70 61 74 69 62 6c 65 0a 2a 2a 20 62 75 74 20 mpatible.** but
0d60: 6e 6f 74 20 62 61 63 6b 77 61 72 64 73 20 63 6f not backwards co
0d70: 6d 70 61 74 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 mpatible..** The
0d80: 20 5a 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 Z value is the
0d90: 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 20 61 release number a
0da0: 6e 64 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 nd is incremente
0db0: 64 20 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72 d with.** each r
0dc0: 65 6c 65 61 73 65 20 62 75 74 20 72 65 73 65 74 elease but reset
0dd0: 73 20 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e s back to 0 when
0de0: 65 76 65 72 20 59 20 69 73 20 69 6e 63 72 65 6d ever Y is increm
0df0: 65 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 ented..**.** See
0e00: 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
0e10: 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e libversion()] an
0e20: 64 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 d [sqlite3_libve
0e30: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2e rsion_number()].
0e40: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
0e50: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 31 31 S:.**.** {H10011
0e60: 7d 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 } The SQLITE_VER
0e70: 53 49 4f 4e 20 23 64 65 66 69 6e 65 20 69 6e 20 SION #define in
0e80: 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 the sqlite3.h he
0e90: 61 64 65 72 20 66 69 6c 65 20 73 68 61 6c 6c 0a ader file shall.
0ea0: 2a 2a 20 20 20 20 20 20 20 20 20 20 65 76 61 6c ** eval
0eb0: 75 61 74 65 20 74 6f 20 61 20 73 74 72 69 6e 67 uate to a string
0ec0: 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20 69 73 literal that is
0ed0: 20 74 68 65 20 53 51 4c 69 74 65 20 76 65 72 73 the SQLite vers
0ee0: 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ion.**
0ef0: 77 69 74 68 20 77 68 69 63 68 20 74 68 65 20 68 with which the h
0f00: 65 61 64 65 72 20 66 69 6c 65 20 69 73 20 61 73 eader file is as
0f10: 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 sociated..**.**
0f20: 7b 48 31 30 30 31 34 7d 20 54 68 65 20 53 51 4c {H10014} The SQL
0f30: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 ITE_VERSION_NUMB
0f40: 45 52 20 23 64 65 66 69 6e 65 20 73 68 61 6c 6c ER #define shall
0f50: 20 72 65 73 6f 6c 76 65 20 74 6f 20 61 6e 20 69 resolve to an i
0f60: 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 nteger.**
0f70: 20 20 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 with the valu
0f80: 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 e (X*1000000 + Y
0f90: 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 *1000 + Z) where
0fa0: 20 58 2c 20 59 2c 20 61 6e 64 20 5a 0a 2a 2a 20 X, Y, and Z.**
0fb0: 20 20 20 20 20 20 20 20 20 61 72 65 20 74 68 65 are the
0fc0: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 2c 20 major version,
0fd0: 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 2c 20 61 minor version, a
0fe0: 6e 64 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 nd release numbe
0ff0: 72 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 r..*/.#define SQ
1000: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 LITE_VERSION
1010: 20 20 20 20 20 22 33 2e 36 2e 34 22 0a 23 64 65 "3.6.4".#de
1020: 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 fine SQLITE_VERS
1030: 49 4f 4e 5f 4e 55 4d 42 45 52 20 20 33 30 30 36 ION_NUMBER 3006
1040: 30 30 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 004../*.** CAPI3
1050: 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 REF: Run-Time Li
1060: 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 brary Version Nu
1070: 6d 62 65 72 73 20 7b 48 31 30 30 32 30 7d 20 3c mbers {H10020} <
1080: 53 36 30 31 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f S60100>.** KEYWO
1090: 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 RDS: sqlite3_ver
10a0: 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 sion.**.** These
10b0: 20 66 65 61 74 75 72 65 73 20 70 72 6f 76 69 64 features provid
10c0: 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 e the same infor
10d0: 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 mation as the [S
10e0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a QLITE_VERSION].*
10f0: 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 56 45 * and [SQLITE_VE
1100: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 23 64 RSION_NUMBER] #d
1110: 65 66 69 6e 65 73 20 69 6e 20 74 68 65 20 68 65 efines in the he
1120: 61 64 65 72 2c 20 62 75 74 20 61 72 65 20 61 73 ader, but are as
1130: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 sociated.** with
1140: 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 the library ins
1150: 74 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 tead of the head
1160: 65 72 20 66 69 6c 65 2e 20 20 43 61 75 74 69 6f er file. Cautio
1170: 75 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d us programmers m
1180: 69 67 68 74 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 ight.** include
1190: 61 20 63 68 65 63 6b 20 69 6e 20 74 68 65 69 72 a check in their
11a0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 application to
11b0: 76 65 72 69 66 79 20 74 68 61 74 0a 2a 2a 20 73 verify that.** s
11c0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
11d0: 6e 5f 6e 75 6d 62 65 72 28 29 20 61 6c 77 61 79 n_number() alway
11e0: 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 s returns the va
11f0: 6c 75 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 lue.** [SQLITE_V
1200: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a ERSION_NUMBER]..
1210: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
1220: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 3_libversion() f
1230: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
1240: 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 the same informa
1250: 74 69 6f 6e 20 61 73 20 69 73 0a 2a 2a 20 69 6e tion as is.** in
1260: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 the sqlite3_ver
1270: 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f sion[] string co
1280: 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 66 75 6e nstant. The fun
1290: 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 ction is provide
12a0: 64 0a 2a 2a 20 66 6f 72 20 75 73 65 20 69 6e 20 d.** for use in
12b0: 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 DLLs since DLL u
12c0: 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 sers usually do
12d0: 6e 6f 74 20 68 61 76 65 20 64 69 72 65 63 74 20 not have direct
12e0: 61 63 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 access to string
12f0: 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 .** constants wi
1300: 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 0a 2a 2a thin the DLL..**
1310: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
1320: 2a 2a 0a 2a 2a 20 7b 48 31 30 30 32 31 7d 20 54 **.** {H10021} T
1330: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 he [sqlite3_libv
1340: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d ersion_number()]
1350: 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c interface shall
1360: 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 return.**
1370: 20 20 20 20 61 6e 20 69 6e 74 65 67 65 72 20 65 an integer e
1380: 71 75 61 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f qual to [SQLITE_
1390: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e VERSION_NUMBER].
13a0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 32 32 7d 20 .**.** {H10022}
13b0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 65 72 The [sqlite3_ver
13c0: 73 69 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e sion] string con
13d0: 73 74 61 6e 74 20 73 68 61 6c 6c 20 63 6f 6e 74 stant shall cont
13e0: 61 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ain.**
13f0: 74 68 65 20 74 65 78 74 20 6f 66 20 74 68 65 20 the text of the
1400: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d [SQLITE_VERSION]
1410: 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b string..**.** {
1420: 48 31 30 30 32 33 7d 20 54 68 65 20 5b 73 71 6c H10023} The [sql
1430: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 ite3_libversion(
1440: 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c )] function shal
1450: 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 l return.**
1460: 20 20 20 20 20 61 20 70 6f 69 6e 74 65 72 20 74 a pointer t
1470: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 o the [sqlite3_v
1480: 65 72 73 69 6f 6e 5d 20 73 74 72 69 6e 67 20 63 ersion] string c
1490: 6f 6e 73 74 61 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 onstant..*/.SQLI
14a0: 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 TE_EXTERN const
14b0: 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 char sqlite3_ver
14c0: 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 sion[];.const ch
14d0: 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 ar *sqlite3_libv
14e0: 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 69 6e ersion(void);.in
14f0: 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 t sqlite3_libver
1500: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 sion_number(void
1510: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1520: 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 EF: Test To See
1530: 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 If The Library I
1540: 73 20 54 68 72 65 61 64 73 61 66 65 20 7b 48 31 s Threadsafe {H1
1550: 30 31 30 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 0100} <S60100>.*
1560: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 *.** SQLite can
1570: 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 be compiled with
1580: 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 or without mute
1590: 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 xes. When.** th
15a0: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
15b0: 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 SAFE] C preproce
15c0: 73 73 6f 72 20 6d 61 63 72 6f 20 31 20 6f 72 20 ssor macro 1 or
15d0: 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 2, mutexes.** ar
15e0: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 e enabled and SQ
15f0: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61 Lite is threadsa
1600: 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a fe. When the.**
1610: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
1620: 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c AFE] macro is 0,
1630: 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 .** the mutexes
1640: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 are omitted. W
1650: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 ithout the mutex
1660: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 es, it is not sa
1670: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c fe.** to use SQL
1680: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 ite concurrently
1690: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 from more than
16a0: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a one thread..**.*
16b0: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 * Enabling mutex
16c0: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 es incurs a meas
16d0: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e urable performan
16e0: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 ce penalty..** S
16f0: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 o if speed is of
1700: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e utmost importan
1710: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e ce, it makes sen
1720: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a se to disable.**
1730: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 the mutexes. B
1740: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 ut for maximum s
1750: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 afety, mutexes s
1760: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 hould be enabled
1770: 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 ..** The default
1780: 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 behavior is for
1790: 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 mutexes to be e
17a0: 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 nabled..**.** Th
17b0: 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e is interface can
17c0: 20 62 65 20 75 73 65 64 20 62 79 20 61 20 70 72 be used by a pr
17d0: 6f 67 72 61 6d 20 74 6f 20 6d 61 6b 65 20 73 75 ogram to make su
17e0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 re that the.** v
17f0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 ersion of SQLite
1800: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b that it is link
1810: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 ing against was
1820: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
1830: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 the desired set
1840: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c ting of the [SQL
1850: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 ITE_THREADSAFE]
1860: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 macro..**.** Thi
1870: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 s interface only
1880: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 reports on the
1890: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 compile-time mut
18a0: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 ex setting.** of
18b0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
18c0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 EADSAFE] flag.
18d0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
18e0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 piled with.** SQ
18f0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
1900: 31 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61 1 then mutexes a
1910: 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 re enabled by de
1920: 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e fault but.** can
1930: 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 be fully or par
1940: 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 tially disabled
1950: 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 using a call to
1960: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
1970: 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 )].** with the v
1980: 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e erbs [SQLITE_CON
1990: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 FIG_SINGLETHREAD
19a0: 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ], [SQLITE_CONFI
19b0: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a G_MULTITHREAD],.
19c0: 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f ** or [SQLITE_CO
19d0: 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 54 68 NFIG_MUTEX]. Th
19e0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f e return value o
19f0: 66 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 f this function
1a00: 73 68 6f 77 73 0a 2a 2a 20 6f 6e 6c 79 20 74 68 shows.** only th
1a10: 65 20 64 65 66 61 75 6c 74 20 63 6f 6d 70 69 6c e default compil
1a20: 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 2c 20 e-time setting,
1a30: 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 not any run-time
1a40: 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 74 changes.** to t
1a50: 68 61 74 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a hat setting..**.
1a60: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 ** See the [thre
1a70: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 ading mode] docu
1a80: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 mentation for ad
1a90: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 ditional informa
1aa0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 tion..**.** INVA
1ab0: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 RIANTS:.**.** {H
1ac0: 31 30 31 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 10101} The [sqli
1ad0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 te3_threadsafe()
1ae0: 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c ] function shall
1af0: 20 72 65 74 75 72 6e 20 7a 65 72 6f 20 69 66 0a return zero if.
1b00: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 ** and
1b10: 6f 6e 6c 79 20 69 66 20 53 51 4c 69 74 65 20 77 only if SQLite w
1b20: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 as compiled with
1b30: 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f mutexing code o
1b40: 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 mitted..**.** {H
1b50: 31 30 31 30 32 7d 20 54 68 65 20 76 61 6c 75 65 10102} The value
1b60: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 returned by the
1b70: 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 [sqlite3_thread
1b80: 73 61 66 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e safe()] function
1b90: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 .** sha
1ba0: 6c 6c 20 72 65 6d 61 69 6e 20 74 68 65 20 73 61 ll remain the sa
1bb0: 6d 65 20 61 63 72 6f 73 73 20 63 61 6c 6c 73 20 me across calls
1bc0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 to [sqlite3_conf
1bd0: 69 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ig()]..*/.int sq
1be0: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 lite3_threadsafe
1bf0: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 (void);../*.** C
1c00: 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 API3REF: Databas
1c10: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e e Connection Han
1c20: 64 6c 65 20 7b 48 31 32 30 30 30 7d 20 3c 53 34 dle {H12000} <S4
1c30: 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 0200>.** KEYWORD
1c40: 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e S: {database con
1c50: 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 nection} {databa
1c60: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a se connections}.
1c70: 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 **.** Each open
1c80: 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 SQLite database
1c90: 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 is represented b
1ca0: 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 y a pointer to a
1cb0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a n instance of.**
1cc0: 20 74 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 the opaque stru
1cd0: 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c cture named "sql
1ce0: 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 ite3". It is us
1cf0: 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 eful to think of
1d00: 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 an sqlite3.** p
1d10: 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a ointer as an obj
1d20: 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 ect. The [sqlit
1d30: 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c e3_open()], [sql
1d40: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 ite3_open16()],
1d50: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
1d60: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 open_v2()] inter
1d70: 66 61 63 65 73 20 61 72 65 20 69 74 73 20 63 6f faces are its co
1d80: 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 nstructors, and
1d90: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 [sqlite3_close()
1da0: 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64 65 73 74 ].** is its dest
1db0: 72 75 63 74 6f 72 2e 20 20 54 68 65 72 65 20 61 ructor. There a
1dc0: 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e re many other in
1dd0: 74 65 72 66 61 63 65 73 20 28 73 75 63 68 20 61 terfaces (such a
1de0: 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 s.** [sqlite3_pr
1df0: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 epare_v2()], [sq
1e00: 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
1e10: 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a ction()], and.**
1e20: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 [sqlite3_busy_t
1e30: 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d imeout()] to nam
1e40: 65 20 62 75 74 20 74 68 72 65 65 29 20 74 68 61 e but three) tha
1e50: 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e t are methods on
1e60: 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f an.** sqlite3 o
1e70: 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 bject..*/.typede
1e80: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
1e90: 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a sqlite3;../*.**
1ea0: 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 CAPI3REF: 64-Bi
1eb0: 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 20 t Integer Types
1ec0: 7b 48 31 30 32 30 30 7d 20 3c 53 31 30 31 31 30 {H10200} <S10110
1ed0: 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 >.** KEYWORDS: s
1ee0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 qlite_int64 sqli
1ef0: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 te_uint64.**.**
1f00: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73 Because there is
1f10: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f no cross-platfo
1f20: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 rm way to specif
1f30: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 y 64-bit integer
1f40: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 types.** SQLite
1f50: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 includes typede
1f60: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 fs for 64-bit si
1f70: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 gned and unsigne
1f80: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a d integers..**.*
1f90: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e * The sqlite3_in
1fa0: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f t64 and sqlite3_
1fb0: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 uint64 are the p
1fc0: 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65 referred type de
1fd0: 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 finitions..** Th
1fe0: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 e sqlite_int64 a
1ff0: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 nd sqlite_uint64
2000: 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f types are suppo
2010: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 rted for backwar
2020: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c ds.** compatibil
2030: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 ity only..**.**
2040: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
2050: 2a 20 7b 48 31 30 32 30 31 7d 20 54 68 65 20 5b * {H10201} The [
2060: 73 71 6c 69 74 65 5f 69 6e 74 36 34 5d 20 61 6e sqlite_int64] an
2070: 64 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 d [sqlite3_int64
2080: 5d 20 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65 ] type shall spe
2090: 63 69 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 cify.**
20a0: 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 a 64-bit signed
20b0: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 integer..**.**
20c0: 7b 48 31 30 32 30 32 7d 20 54 68 65 20 5b 73 71 {H10202} The [sq
20d0: 6c 69 74 65 5f 75 69 6e 74 36 34 5d 20 61 6e 64 lite_uint64] and
20e0: 20 5b 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 [sqlite3_uint64
20f0: 5d 20 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65 ] type shall spe
2100: 63 69 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 cify.**
2110: 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e a 64-bit unsign
2120: 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2f 0a 23 ed integer..*/.#
2130: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 ifdef SQLITE_INT
2140: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 64_TYPE. typede
2150: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 f SQLITE_INT64_T
2160: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 YPE sqlite_int64
2170: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 ;. typedef unsi
2180: 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 gned SQLITE_INT6
2190: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 4_TYPE sqlite_ui
21a0: 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 nt64;.#elif defi
21b0: 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c ned(_MSC_VER) ||
21c0: 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 defined(__BORLA
21d0: 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 NDC__). typedef
21e0: 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f __int64 sqlite_
21f0: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 int64;. typedef
2200: 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 unsigned __int6
2210: 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 4 sqlite_uint64;
2220: 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 .#else. typedef
2230: 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 long long int s
2240: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 qlite_int64;. t
2250: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 ypedef unsigned
2260: 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 long long int sq
2270: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e lite_uint64;.#en
2280: 64 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 dif.typedef sqli
2290: 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 te_int64 sqlite3
22a0: 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 _int64;.typedef
22b0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 sqlite_uint64 sq
22c0: 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f lite3_uint64;../
22d0: 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e *.** If compilin
22e0: 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f g for a processo
22f0: 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f r that lacks flo
2300: 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 ating point supp
2310: 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 ort,.** substitu
2320: 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 te integer for f
2330: 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a loating-point..*
2340: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f /.#ifdef SQLITE_
2350: 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f OMIT_FLOATING_PO
2360: 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 INT.# define dou
2370: 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 ble sqlite3_int6
2380: 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4.#endif../*.**
2390: 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e CAPI3REF: Closin
23a0: 67 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e g A Database Con
23b0: 6e 65 63 74 69 6f 6e 20 7b 48 31 32 30 31 30 7d nection {H12010}
23c0: 20 3c 53 33 30 31 30 30 3e 3c 53 34 30 32 30 30 <S30100><S40200
23d0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 >.**.** This rou
23e0: 74 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 tine is the dest
23f0: 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b ructor for the [
2400: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e sqlite3] object.
2410: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 .**.** Applicati
2420: 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 ons should [sqli
2430: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 te3_finalize | f
2440: 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 inalize] all [pr
2450: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2460: 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 s].** and [sqlit
2470: 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 e3_blob_close |
2480: 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 close] all [BLOB
2490: 20 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 handles] associ
24a0: 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 ated with.** the
24b0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 [sqlite3] objec
24c0: 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d t prior to attem
24d0: 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 pting to close t
24e0: 68 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 he object..** Th
24f0: 65 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f e [sqlite3_next_
2500: 73 74 6d 74 28 29 5d 20 69 6e 74 65 72 66 61 63 stmt()] interfac
2510: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f e can be used to
2520: 20 6c 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a 20 5b locate all.** [
2530: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2540: 6e 74 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20 nts] associated
2550: 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 with a [database
2560: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 66 20 connection] if
2570: 64 65 73 69 72 65 64 2e 0a 2a 2a 20 54 79 70 69 desired..** Typi
2580: 63 61 6c 20 63 6f 64 65 20 6d 69 67 68 74 20 6c cal code might l
2590: 6f 6f 6b 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a ook like this:.*
25a0: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
25b0: 3e 3c 70 72 65 3e 0a 2a 2a 20 73 71 6c 69 74 65 ><pre>.** sqlite
25c0: 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 3b 0a 2a 3_stmt *pStmt;.*
25d0: 2a 20 77 68 69 6c 65 28 20 28 70 53 74 6d 74 20 * while( (pStmt
25e0: 3d 20 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 = sqlite3_next_s
25f0: 74 6d 74 28 64 62 2c 20 30 29 29 21 3d 30 20 29 tmt(db, 0))!=0 )
2600: 7b 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 73 71 {.** sq
2610: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 70 lite3_finalize(p
2620: 53 74 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c Stmt);.** }.** <
2630: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
2640: 65 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73 71 6c e>.**.** If [sql
2650: 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 ite3_close()] is
2660: 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 invoked while a
2670: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 transaction is
2680: 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 open,.** the tra
2690: 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f nsaction is auto
26a0: 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 matically rolled
26b0: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 back..**.** INV
26c0: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
26d0: 48 31 32 30 31 31 7d 20 41 20 73 75 63 63 65 73 H12011} A succes
26e0: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 sful call to [sq
26f0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 lite3_close(C)]
2700: 73 68 61 6c 6c 20 64 65 73 74 72 6f 79 20 74 68 shall destroy th
2710: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 e.** [d
2720: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2730: 6f 6e 5d 20 6f 62 6a 65 63 74 20 43 2e 0a 2a 2a on] object C..**
2740: 0a 2a 2a 20 7b 48 31 32 30 31 32 7d 20 41 20 73 .** {H12012} A s
2750: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 uccessful call t
2760: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 o [sqlite3_close
2770: 28 43 29 5d 20 73 68 61 6c 6c 20 72 65 74 75 72 (C)] shall retur
2780: 6e 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a n SQLITE_OK..**.
2790: 2a 2a 20 7b 48 31 32 30 31 33 7d 20 41 20 73 75 ** {H12013} A su
27a0: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f ccessful call to
27b0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 [sqlite3_close(
27c0: 43 29 5d 20 73 68 61 6c 6c 20 72 65 6c 65 61 73 C)] shall releas
27d0: 65 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 e all.**
27e0: 20 20 6d 65 6d 6f 72 79 20 61 6e 64 20 73 79 73 memory and sys
27f0: 74 65 6d 20 72 65 73 6f 75 72 63 65 73 20 61 73 tem resources as
2800: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 5b 64 sociated with [d
2810: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2820: 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 on].**
2830: 43 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 34 C..**.** {H12014
2840: 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c } A call to [sql
2850: 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6f ite3_close(C)] o
2860: 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f n a [database co
2870: 6e 6e 65 63 74 69 6f 6e 5d 20 43 20 74 68 61 74 nnection] C that
2880: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61 73 .** has
2890: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 70 65 one or more ope
28a0: 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 n [prepared stat
28b0: 65 6d 65 6e 74 73 5d 20 73 68 61 6c 6c 20 66 61 ements] shall fa
28c0: 69 6c 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 il with.**
28d0: 20 20 20 20 61 6e 20 5b 53 51 4c 49 54 45 5f 42 an [SQLITE_B
28e0: 55 53 59 5d 20 65 72 72 6f 72 20 63 6f 64 65 2e USY] error code.
28f0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 35 7d 20 .**.** {H12015}
2900: 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 A call to [sqlit
2910: 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 77 68 65 e3_close(C)] whe
2920: 72 65 20 43 20 69 73 20 61 20 4e 55 4c 4c 20 70 re C is a NULL p
2930: 6f 69 6e 74 65 72 20 73 68 61 6c 6c 0a 2a 2a 20 ointer shall.**
2940: 20 20 20 20 20 20 20 20 20 62 65 20 61 20 68 61 be a ha
2950: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 20 72 65 74 rmless no-op ret
2960: 75 72 6e 69 6e 67 20 53 51 4c 49 54 45 5f 4f 4b urning SQLITE_OK
2970: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 39 7d ..**.** {H12019}
2980: 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 63 When [sqlite3_c
2990: 6c 6f 73 65 28 43 29 5d 20 69 73 20 69 6e 76 6f lose(C)] is invo
29a0: 6b 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 ked on a [databa
29b0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 43 se connection] C
29c0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 .** tha
29d0: 74 20 68 61 73 20 61 20 70 65 6e 64 69 6e 67 20 t has a pending
29e0: 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 transaction, the
29f0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 73 68 61 transaction sha
2a00: 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 20 20 20 20 ll be.**
2a10: 20 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a rolled back..*
2a20: 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 *.** ASSUMPTIONS
2a30: 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 30 31 36 7d :.**.** {A12016}
2a40: 20 54 68 65 20 43 20 70 61 72 61 6d 65 74 65 72 The C parameter
2a50: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f to [sqlite3_clo
2a60: 73 65 28 43 29 5d 20 6d 75 73 74 20 62 65 20 65 se(C)] must be e
2a70: 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 ither a NULL.**
2a80: 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 pointer
2a90: 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d or an [sqlite3]
2aa0: 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 object pointer
2ab0: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 20 20 20 20 obtained.**
2ac0: 20 20 20 20 20 66 72 6f 6d 20 5b 73 71 6c 69 74 from [sqlit
2ad0: 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c e3_open()], [sql
2ae0: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 ite3_open16()],
2af0: 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b or.** [
2b00: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
2b10: 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 )], and not prev
2b20: 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a iously closed..*
2b30: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c /.int sqlite3_cl
2b40: 6f 73 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a ose(sqlite3 *);.
2b50: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 ./*.** The type
2b60: 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 for a callback f
2b70: 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 unction..** This
2b80: 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 is legacy and d
2b90: 65 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 eprecated. It i
2ba0: 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 s included for h
2bb0: 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d istorical.** com
2bc0: 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 patibility and i
2bd0: 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 s not documented
2be0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 ..*/.typedef int
2bf0: 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 (*sqlite3_callb
2c00: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 ack)(void*,int,c
2c10: 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a har**, char**);.
2c20: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2c30: 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 One-Step Query
2c40: 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 Execution Interf
2c50: 61 63 65 20 7b 48 31 32 31 30 30 7d 20 3c 53 31 ace {H12100} <S1
2c60: 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 0000>.**.** The
2c70: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 sqlite3_exec() i
2c80: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f nterface is a co
2c90: 6e 76 65 6e 69 65 6e 74 20 77 61 79 20 6f 66 20 nvenient way of
2ca0: 72 75 6e 6e 69 6e 67 20 6f 6e 65 20 6f 72 20 6d running one or m
2cb0: 6f 72 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 ore.** SQL state
2cc0: 6d 65 6e 74 73 20 77 69 74 68 6f 75 74 20 68 61 ments without ha
2cd0: 76 69 6e 67 20 74 6f 20 77 72 69 74 65 20 61 20 ving to write a
2ce0: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 20 lot of C code.
2cf0: 54 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 The UTF-8 encode
2d00: 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 d.** SQL stateme
2d10: 6e 74 73 20 61 72 65 20 70 61 73 73 65 64 20 69 nts are passed i
2d20: 6e 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 n as the second
2d30: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
2d40: 69 74 65 33 5f 65 78 65 63 28 29 2e 0a 2a 2a 20 ite3_exec()..**
2d50: 54 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 61 The statements a
2d60: 72 65 20 65 76 61 6c 75 61 74 65 64 20 6f 6e 65 re evaluated one
2d70: 20 62 79 20 6f 6e 65 20 75 6e 74 69 6c 20 65 69 by one until ei
2d80: 74 68 65 72 20 61 6e 20 65 72 72 6f 72 20 6f 72 ther an error or
2d90: 0a 2a 2a 20 61 6e 20 69 6e 74 65 72 72 75 70 74 .** an interrupt
2da0: 20 69 73 20 65 6e 63 6f 75 6e 74 65 72 65 64 2c is encountered,
2db0: 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 79 20 61 or until they a
2dc0: 72 65 20 61 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 re all done. Th
2dd0: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 0a e 3rd parameter.
2de0: 2a 2a 20 69 73 20 61 6e 20 6f 70 74 69 6f 6e 61 ** is an optiona
2df0: 6c 20 63 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 l callback that
2e00: 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 is invoked once
2e10: 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20 for each row of
2e20: 61 6e 79 20 71 75 65 72 79 0a 2a 2a 20 72 65 73 any query.** res
2e30: 75 6c 74 73 20 70 72 6f 64 75 63 65 64 20 62 79 ults produced by
2e40: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
2e50: 6e 74 73 2e 20 20 54 68 65 20 35 74 68 20 70 61 nts. The 5th pa
2e60: 72 61 6d 65 74 65 72 20 74 65 6c 6c 73 20 77 68 rameter tells wh
2e70: 65 72 65 0a 2a 2a 20 74 6f 20 77 72 69 74 65 20 ere.** to write
2e80: 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 any error messag
2e90: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 72 es..**.** The er
2ea0: 72 6f 72 20 6d 65 73 73 61 67 65 20 70 61 73 73 ror message pass
2eb0: 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 ed back through
2ec0: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 the 5th paramete
2ed0: 72 20 69 73 20 68 65 6c 64 0a 2a 2a 20 69 6e 20 r is held.** in
2ee0: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 memory obtained
2ef0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 from [sqlite3_ma
2f00: 6c 6c 6f 63 28 29 5d 2e 20 20 54 6f 20 61 76 6f lloc()]. To avo
2f10: 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b id a memory leak
2f20: 2c 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 69 6e 67 ,.** the calling
2f30: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f application sho
2f40: 75 6c 64 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 uld call [sqlite
2f50: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 61 6e 79 3_free()] on any
2f60: 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 error.** messag
2f70: 65 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 e returned throu
2f80: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d gh the 5th param
2f90: 65 74 65 72 20 77 68 65 6e 20 69 74 20 68 61 73 eter when it has
2fa0: 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 0a finished using.
2fb0: 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 ** the error mes
2fc0: 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 sage..**.** If t
2fd0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
2fe0: 20 69 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 in the 2nd para
2ff0: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 6f 72 meter is NULL or
3000: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 an empty string
3010: 0a 2a 2a 20 6f 72 20 61 20 73 74 72 69 6e 67 20 .** or a string
3020: 63 6f 6e 74 61 69 6e 69 6e 67 20 6f 6e 6c 79 20 containing only
3030: 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 20 63 whitespace and c
3040: 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f omments, then no
3050: 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e SQL.** statemen
3060: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 ts are evaluated
3070: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 and the databas
3080: 65 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 e is not changed
3090: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
30a0: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 te3_exec() inter
30b0: 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e face is implemen
30c0: 74 65 64 20 69 6e 20 74 65 72 6d 73 20 6f 66 0a ted in terms of.
30d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
30e0: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 are_v2()], [sqli
30f0: 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 te3_step()], and
3100: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
3110: 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 71 ze()]..** The sq
3120: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 72 6f 75 lite3_exec() rou
3130: 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 68 69 6e tine does nothin
3140: 67 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 g to the databas
3150: 65 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 e that cannot be
3160: 20 64 6f 6e 65 0a 2a 2a 20 62 79 20 5b 73 71 6c done.** by [sql
3170: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
3180: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 )], [sqlite3_ste
3190: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 p()], and [sqlit
31a0: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a e3_finalize()]..
31b0: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
31c0: 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 31 7d :.**.** {H12101}
31d0: 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e A successful in
31e0: 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c vocation of [sql
31f0: 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c ite3_exec(D,S,C,
3200: 41 2c 45 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 A,E)].**
3210: 20 20 73 68 61 6c 6c 20 73 65 71 75 65 6e 74 69 shall sequenti
3220: 61 6c 6c 79 20 65 76 61 6c 75 61 74 65 20 61 6c ally evaluate al
3230: 6c 20 6f 66 20 74 68 65 20 55 54 46 2d 38 20 65 l of the UTF-8 e
3240: 6e 63 6f 64 65 64 2c 0a 2a 2a 20 20 20 20 20 20 ncoded,.**
3250: 20 20 20 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 semicolon-se
3260: 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 parated SQL stat
3270: 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 ements in the ze
3280: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ro-terminated.**
3290: 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 string
32a0: 20 53 20 77 69 74 68 69 6e 20 74 68 65 20 63 6f S within the co
32b0: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 ntext of the [da
32c0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
32d0: 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 n] D..**.** {H12
32e0: 31 30 32 7d 20 49 66 20 74 68 65 20 53 20 70 61 102} If the S pa
32f0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
3300: 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 te3_exec(D,S,C,A
3310: 2c 45 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 ,E)] is NULL the
3320: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 n.** th
3330: 65 20 61 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 e actions of the
3340: 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c interface shall
3350: 20 62 65 20 74 68 65 20 73 61 6d 65 20 61 73 20 be the same as
3360: 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 if the.**
3370: 20 20 20 53 20 70 61 72 61 6d 65 74 65 72 20 77 S parameter w
3380: 65 72 65 20 61 6e 20 65 6d 70 74 79 20 73 74 72 ere an empty str
3390: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 ing..**.** {H121
33a0: 30 34 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 04} The return v
33b0: 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 alue of [sqlite3
33c0: 5f 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 62 _exec()] shall b
33d0: 65 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 e [SQLITE_OK] if
33e0: 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 all.**
33f0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
3400: 72 75 6e 20 73 75 63 63 65 73 73 66 75 6c 6c 79 run successfully
3410: 20 61 6e 64 20 74 6f 20 63 6f 6d 70 6c 65 74 69 and to completi
3420: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 on..**.** {H1210
3430: 35 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 5} The return va
3440: 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f lue of [sqlite3_
3450: 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 62 65 exec()] shall be
3460: 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a an appropriate.
3470: 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 6e 2d ** non-
3480: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 zero [error code
3490: 5d 20 69 66 20 61 6e 79 20 53 51 4c 20 73 74 61 ] if any SQL sta
34a0: 74 65 6d 65 6e 74 20 66 61 69 6c 73 2e 0a 2a 2a tement fails..**
34b0: 0a 2a 2a 20 7b 48 31 32 31 30 37 7d 20 49 66 20 .** {H12107} If
34c0: 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 one or more of t
34d0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
34e0: 73 20 68 61 6e 64 65 64 20 74 6f 20 5b 73 71 6c s handed to [sql
34f0: 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 ite3_exec()].**
3500: 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 return
3510: 72 65 73 75 6c 74 73 20 61 6e 64 20 74 68 65 20 results and the
3520: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 3rd parameter is
3530: 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 0a not NULL, then.
3540: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
3550: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
3560: 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 n specified by t
3570: 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 he 3rd parameter
3580: 20 73 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 shall be.**
3590: 20 20 20 20 20 20 69 6e 76 6f 6b 65 64 20 6f 6e invoked on
35a0: 63 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20 ce for each row
35b0: 6f 66 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a of result..**.**
35c0: 20 7b 48 31 32 31 31 30 7d 20 49 66 20 74 68 65 {H12110} If the
35d0: 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
35e0: 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 76 61 6c s a non-zero val
35f0: 75 65 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 ue then [sqlite3
3600: 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20 _exec()].**
3610: 20 20 20 20 20 73 68 61 6c 6c 20 61 62 6f 72 74 shall abort
3620: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
3630: 6e 74 20 69 74 20 69 73 20 63 75 72 72 65 6e 74 nt it is current
3640: 6c 79 20 65 76 61 6c 75 61 74 69 6e 67 2c 0a 2a ly evaluating,.*
3650: 2a 20 20 20 20 20 20 20 20 20 20 73 6b 69 70 20 * skip
3660: 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 53 all subsequent S
3670: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 QL statements, a
3680: 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 nd return [SQLIT
3690: 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 E_ABORT]..**.**
36a0: 7b 48 31 32 31 31 33 7d 20 54 68 65 20 5b 73 71 {H12113} The [sq
36b0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f lite3_exec()] ro
36c0: 75 74 69 6e 65 20 73 68 61 6c 6c 20 70 61 73 73 utine shall pass
36d0: 20 69 74 73 20 34 74 68 20 70 61 72 61 6d 65 74 its 4th paramet
36e0: 65 72 20 74 68 72 6f 75 67 68 0a 2a 2a 20 20 20 er through.**
36f0: 20 20 20 20 20 20 20 61 73 20 74 68 65 20 31 73 as the 1s
3700: 74 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 t parameter of t
3710: 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a he callback..**.
3720: 2a 2a 20 7b 48 31 32 31 31 36 7d 20 54 68 65 20 ** {H12116} The
3730: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
3740: 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 routine shall s
3750: 65 74 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d et the 2nd param
3760: 65 74 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20 eter of its.**
3770: 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b callback
3780: 20 74 6f 20 62 65 20 74 68 65 20 6e 75 6d 62 65 to be the numbe
3790: 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 r of columns in
37a0: 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 the current row
37b0: 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 of.** r
37c0: 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 esult..**.** {H1
37d0: 32 31 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 2119} The [sqlit
37e0: 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 e3_exec()] routi
37f0: 6e 65 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 ne shall set the
3800: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 6f 3rd parameter o
3810: 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 f its.**
3820: 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 callback to be
3830: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 an array of poi
3840: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 nters to strings
3850: 20 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a 20 holding the.**
3860: 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 73 20 values
3870: 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20 for each column
3880: 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 in the current r
3890: 65 73 75 6c 74 20 73 65 74 20 72 6f 77 20 61 73 esult set row as
38a0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 74 .** obt
38b0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 ained from [sqli
38c0: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
38d0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 32 )]..**.** {H1212
38e0: 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 2} The [sqlite3_
38f0: 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 exec()] routine
3900: 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 34 74 shall set the 4t
3910: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 69 h parameter of i
3920: 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 ts.** c
3930: 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 61 6e allback to be an
3940: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 array of pointe
3950: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 68 6f rs to strings ho
3960: 6c 64 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 lding the.**
3970: 20 20 20 20 20 20 6e 61 6d 65 73 20 6f 66 20 72 names of r
3980: 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 61 73 esult columns as
3990: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
39a0: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e sqlite3_column_n
39b0: 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ame()]..**.** {H
39c0: 31 32 31 32 35 7d 20 49 66 20 74 68 65 20 33 72 12125} If the 3r
39d0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b d parameter to [
39e0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 sqlite3_exec()]
39f0: 69 73 20 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a 20 is NULL then.**
3a00: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
3a10: 33 5f 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 3_exec()] shall
3a20: 73 69 6c 65 6e 74 6c 79 20 64 69 73 63 61 72 64 silently discard
3a30: 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 0a query results..
3a40: 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33 31 7d 20 49 **.** {H12131} I
3a50: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 f an error occur
3a60: 73 20 77 68 69 6c 65 20 70 61 72 73 69 6e 67 20 s while parsing
3a70: 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20 61 6e or evaluating an
3a80: 79 20 6f 66 20 74 68 65 20 53 51 4c 0a 2a 2a 20 y of the SQL.**
3a90: 20 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 stateme
3aa0: 6e 74 73 20 69 6e 20 74 68 65 20 53 20 70 61 72 nts in the S par
3ab0: 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 ameter of [sqlit
3ac0: 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c e3_exec(D,S,C,A,
3ad0: 45 29 5d 20 61 6e 64 20 69 66 0a 2a 2a 20 20 20 E)] and if.**
3ae0: 20 20 20 20 20 20 20 74 68 65 20 45 20 70 61 72 the E par
3af0: 61 6d 65 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 ameter is not NU
3b00: 4c 4c 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 LL, then [sqlite
3b10: 33 5f 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 3_exec()] shall
3b20: 73 74 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 store.**
3b30: 20 20 69 6e 20 2a 45 20 61 6e 20 61 70 70 72 6f in *E an appro
3b40: 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 priate error mes
3b50: 73 61 67 65 20 77 72 69 74 74 65 6e 20 69 6e 74 sage written int
3b60: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 o memory obtaine
3b70: 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 d.** fr
3b80: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
3b90: 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 oc()]..**.** {H1
3ba0: 32 31 33 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 2134} The [sqlit
3bb0: 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c e3_exec(D,S,C,A,
3bc0: 45 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c E)] routine shal
3bd0: 6c 20 73 65 74 20 74 68 65 20 76 61 6c 75 65 20 l set the value
3be0: 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 2a of.** *
3bf0: 45 20 74 6f 20 4e 55 4c 4c 20 69 66 20 45 20 69 E to NULL if E i
3c00: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 74 s not NULL and t
3c10: 68 65 72 65 20 61 72 65 20 6e 6f 20 65 72 72 6f here are no erro
3c20: 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33 rs..**.** {H1213
3c30: 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 7} The [sqlite3_
3c40: 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d exec(D,S,C,A,E)]
3c50: 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 function shall
3c60: 73 65 74 20 74 68 65 20 5b 65 72 72 6f 72 20 63 set the [error c
3c70: 6f 64 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 ode].**
3c80: 20 61 6e 64 20 6d 65 73 73 61 67 65 20 61 63 63 and message acc
3c90: 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c essible via [sql
3ca0: 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c ite3_errcode()],
3cb0: 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 .** [s
3cc0: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f qlite3_extended_
3cd0: 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 errcode()],.**
3ce0: 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
3cf0: 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 _errmsg()], and
3d00: 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 [sqlite3_errmsg1
3d10: 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 6()]..**.** {H12
3d20: 31 33 38 7d 20 49 66 20 74 68 65 20 53 20 70 61 138} If the S pa
3d30: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
3d40: 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 te3_exec(D,S,C,A
3d50: 2c 45 29 5d 20 69 73 20 4e 55 4c 4c 20 6f 72 20 ,E)] is NULL or
3d60: 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 an.** e
3d70: 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 63 mpty string or c
3d80: 6f 6e 74 61 69 6e 73 20 6e 6f 74 68 69 6e 67 20 ontains nothing
3d90: 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69 74 65 other than white
3da0: 73 70 61 63 65 2c 20 63 6f 6d 6d 65 6e 74 73 2c space, comments,
3db0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 .** and
3dc0: 2f 6f 72 20 73 65 6d 69 63 6f 6c 6f 6e 73 2c 20 /or semicolons,
3dd0: 74 68 65 6e 20 72 65 73 75 6c 74 73 20 6f 66 20 then results of
3de0: 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 [sqlite3_errcode
3df0: 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 ()],.**
3e00: 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 [sqlite3_extend
3e10: 65 64 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a ed_errcode()],.*
3e20: 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
3e30: 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 te3_errmsg()], a
3e40: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d nd [sqlite3_errm
3e50: 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 sg16()].**
3e60: 20 20 20 20 73 68 61 6c 6c 20 72 65 73 65 74 20 shall reset
3e70: 74 6f 20 69 6e 64 69 63 61 74 65 20 6e 6f 20 65 to indicate no e
3e80: 72 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 rrors..**.** ASS
3e90: 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 UMPTIONS:.**.**
3ea0: 7b 41 31 32 31 34 31 7d 20 54 68 65 20 66 69 72 {A12141} The fir
3eb0: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
3ec0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
3ed0: 20 6d 75 73 74 20 62 65 20 61 6e 20 76 61 6c 69 must be an vali
3ee0: 64 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20 20 20 d and open.**
3ef0: 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 [database
3f00: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a connection]..**
3f10: 0a 2a 2a 20 7b 41 31 32 31 34 32 7d 20 54 68 65 .** {A12142} The
3f20: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
3f30: 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 62 65 tion must not be
3f40: 20 63 6c 6f 73 65 64 20 77 68 69 6c 65 0a 2a 2a closed while.**
3f50: 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
3f60: 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 e3_exec()] is ru
3f70: 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 nning..**.** {A1
3f80: 32 31 34 33 7d 20 54 68 65 20 63 61 6c 6c 69 6e 2143} The callin
3f90: 67 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c g function shoul
3fa0: 64 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 66 d use [sqlite3_f
3fb0: 72 65 65 28 29 5d 20 74 6f 20 66 72 65 65 0a 2a ree()] to free.*
3fc0: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6d * the m
3fd0: 65 6d 6f 72 79 20 74 68 61 74 20 2a 65 72 72 6d emory that *errm
3fe0: 73 67 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 sg is left point
3ff0: 69 6e 67 20 61 74 20 6f 6e 63 65 20 74 68 65 20 ing at once the
4000: 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 error.**
4010: 20 20 6d 65 73 73 61 67 65 20 69 73 20 6e 6f 20 message is no
4020: 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a longer needed..*
4030: 2a 0a 2a 2a 20 7b 41 31 32 31 34 35 7d 20 54 68 *.** {A12145} Th
4040: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
4050: 74 65 78 74 20 69 6e 20 74 68 65 20 32 6e 64 20 text in the 2nd
4060: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 parameter to [sq
4070: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a lite3_exec()].**
4080: 20 20 20 20 20 20 20 20 20 20 6d 75 73 74 20 72 must r
4090: 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 emain unchanged
40a0: 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 65 while [sqlite3_e
40b0: 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e xec()] is runnin
40c0: 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 g..*/.int sqlite
40d0: 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 3_exec(. sqlite
40e0: 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 3*,
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4100: 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 /* An open
4110: 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f database */. co
4120: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 nst char *sql,
4130: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4140: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 /* SQL
4150: 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 to be evaluated
4160: 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 */. int (*callb
4170: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 ack)(void*,int,c
4180: 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 har**,char**),
4190: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 /* Callback func
41a0: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a tion */. void *
41b0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
41c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
41d0: 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 /* 1st argu
41e0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b ment to callback
41f0: 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 */. char **err
4200: 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 msg
4210: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4220: 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 /* Error msg wr
4230: 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b itten here */.);
4240: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
4250: 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b : Result Codes {
4260: 48 31 30 32 31 30 7d 20 3c 53 31 30 37 30 30 3e H10210} <S10700>
4270: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 .** KEYWORDS: SQ
4280: 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 LITE_OK {error c
4290: 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 ode} {error code
42a0: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 s}.** KEYWORDS:
42b0: 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 {result code} {r
42c0: 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a esult codes}.**.
42d0: 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 ** Many SQLite f
42e0: 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 unctions return
42f0: 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c an integer resul
4300: 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 t code from the
4310: 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 set shown.** her
4320: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e e in order to in
4330: 64 69 63 61 74 65 73 20 73 75 63 63 65 73 73 20 dicates success
4340: 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a or failure..**.*
4350: 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 * New error code
4360: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 s may be added i
4370: 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e n future version
4380: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a s of SQLite..**.
4390: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 ** See also: [SQ
43a0: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 LITE_IOERR_READ
43b0: 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c | extended resul
43c0: 74 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 t codes].*/.#def
43d0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 ine SQLITE_OK
43e0: 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 0 /* S
43f0: 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 uccessful result
4400: 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 */./* beginning
4410: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 -of-error-codes
4420: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4430: 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 E_ERROR 1
4440: 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 /* SQL error
4450: 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 or missing datab
4460: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ase */.#define S
4470: 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 QLITE_INTERNAL
4480: 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 2 /* Intern
4490: 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 al logic error i
44a0: 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 n SQLite */.#def
44b0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 ine SQLITE_PERM
44c0: 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 3 /* A
44d0: 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e ccess permission
44e0: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 denied */.#defi
44f0: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 ne SQLITE_ABORT
4500: 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 4 /* Ca
4510: 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 llback routine r
4520: 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 equested an abor
4530: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
4540: 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 ITE_BUSY
4550: 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 5 /* The data
4560: 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 base file is loc
4570: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ked */.#define S
4580: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 QLITE_LOCKED
4590: 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 6 /* A tabl
45a0: 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 e in the databas
45b0: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 e is locked */.#
45c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f define SQLITE_NO
45d0: 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f MEM 7 /
45e0: 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 * A malloc() fai
45f0: 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 led */.#define S
4600: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 QLITE_READONLY
4610: 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 8 /* Attemp
4620: 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 t to write a rea
4630: 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a donly database *
4640: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4650: 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 _INTERRUPT 9
4660: 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 /* Operation t
4670: 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c erminated by sql
4680: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
4690: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
46a0: 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 E_IOERR 10
46b0: 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 /* Some kind
46c0: 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f of disk I/O erro
46d0: 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 r occurred */.#d
46e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 efine SQLITE_COR
46f0: 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a RUPT 11 /*
4700: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69 The database di
4710: 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 sk image is malf
4720: 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 ormed */.#define
4730: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 SQLITE_NOTFOUND
4740: 20 20 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20 12 /* NOT
4750: 55 53 45 44 2e 20 54 61 62 6c 65 20 6f 72 20 72 USED. Table or r
4760: 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20 ecord not found
4770: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4780: 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 E_FULL 13
4790: 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 /* Insertion
47a0: 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 failed because d
47b0: 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 atabase is full
47c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
47d0: 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 E_CANTOPEN 14
47e0: 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 /* Unable to
47f0: 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 open the databas
4800: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e e file */.#defin
4810: 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f e SQLITE_PROTOCO
4820: 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54 L 15 /* NOT
4830: 20 55 53 45 44 2e 20 44 61 74 61 62 61 73 65 20 USED. Database
4840: 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 lock protocol er
4850: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ror */.#define S
4860: 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 QLITE_EMPTY
4870: 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 16 /* Databa
4880: 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 se is empty */.#
4890: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 define SQLITE_SC
48a0: 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f HEMA 17 /
48b0: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 * The database s
48c0: 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f chema changed */
48d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
48e0: 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 TOOBIG 18
48f0: 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c /* String or BL
4900: 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 OB exceeds size
4910: 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 limit */.#define
4920: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
4930: 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 NT 19 /* Abor
4940: 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 t due to constra
4950: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f int violation */
4960: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4970: 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 MISMATCH 20
4980: 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 /* Data type mi
4990: 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e smatch */.#defin
49a0: 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 e SQLITE_MISUSE
49b0: 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 21 /* Lib
49c0: 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 rary used incorr
49d0: 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 ectly */.#define
49e0: 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 SQLITE_NOLFS
49f0: 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 22 /* Uses
4a00: 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 OS features not
4a10: 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f supported on ho
4a20: 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 st */.#define SQ
4a30: 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 LITE_AUTH
4a40: 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 23 /* Authori
4a50: 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f zation denied */
4a60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4a70: 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 FORMAT 24
4a80: 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 /* Auxiliary da
4a90: 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 tabase format er
4aa0: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ror */.#define S
4ab0: 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 QLITE_RANGE
4ac0: 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 25 /* 2nd pa
4ad0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
4ae0: 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 e3_bind out of r
4af0: 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ange */.#define
4b00: 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 SQLITE_NOTADB
4b10: 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 26 /* File
4b20: 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e opened that is n
4b30: 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 ot a database fi
4b40: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 le */.#define SQ
4b50: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 LITE_ROW
4b60: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 100 /* sqlite3
4b70: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 _step() has anot
4b80: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f her row ready */
4b90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4ba0: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 DONE 101
4bb0: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 /* sqlite3_step
4bc0: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 () has finished
4bd0: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 executing */./*
4be0: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 end-of-error-cod
4bf0: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 es */../*.** CAP
4c00: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 I3REF: Extended
4c10: 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 Result Codes {H1
4c20: 30 32 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 0220} <S10700>.*
4c30: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 * KEYWORDS: {ext
4c40: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 ended error code
4c50: 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f } {extended erro
4c60: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 r codes}.** KEYW
4c70: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 ORDS: {extended
4c80: 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 result code} {ex
4c90: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
4ca0: 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 des}.**.** In it
4cb0: 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 s default config
4cc0: 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 uration, SQLite
4cd0: 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 API routines ret
4ce0: 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e urn one of 26 in
4cf0: 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 teger.** [SQLITE
4d00: 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 _OK | result cod
4d10: 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 es]. However, e
4d20: 78 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 xperience has sh
4d30: 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 own that many of
4d40: 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 .** these result
4d50: 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 codes are too c
4d60: 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 oarse-grained.
4d70: 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 They do not prov
4d80: 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 ide as.** much i
4d90: 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 nformation about
4da0: 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f problems as pro
4db0: 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c grammers might l
4dc0: 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f ike. In an effo
4dd0: 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 rt to.** address
4de0: 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 this, newer ver
4df0: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 sions of SQLite
4e00: 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 (version 3.3.8 a
4e10: 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 nd later) includ
4e20: 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 e.** support for
4e30: 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 additional resu
4e40: 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 lt codes that pr
4e50: 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 ovide more detai
4e60: 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a led information.
4e70: 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e ** about errors.
4e80: 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 The extended re
4e90: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 sult codes are e
4ea0: 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c nabled or disabl
4eb0: 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 ed.** on a per d
4ec0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
4ed0: 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 on basis using t
4ee0: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 he.** [sqlite3_e
4ef0: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 xtended_result_c
4f00: 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a odes()] API..**.
4f10: 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 ** Some of the a
4f20: 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 vailable extende
4f30: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 d result codes a
4f40: 72 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a re listed here..
4f50: 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 ** One may expec
4f60: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 t the number of
4f70: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
4f80: 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 codes will be ex
4f90: 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d pand.** over tim
4fa0: 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 e. Software tha
4fb0: 74 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 t uses extended
4fc0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f result codes sho
4fd0: 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f uld expect.** to
4fe0: 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 see new result
4ff0: 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 codes in future
5000: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 releases of SQLi
5010: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 te..**.** The SQ
5020: 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 LITE_OK result c
5030: 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 ode will never b
5040: 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 e extended. It
5050: 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 will always.** b
5060: 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a e exactly zero..
5070: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
5080: 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 33 7d :.**.** {H10223}
5090: 20 54 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 The symbolic na
50a0: 6d 65 20 66 6f 72 20 61 6e 20 65 78 74 65 6e 64 me for an extend
50b0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 73 ed result code s
50c0: 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a hall contains.**
50d0: 20 20 20 20 20 20 20 20 20 20 61 20 72 65 6c 61 a rela
50e0: 74 65 64 20 70 72 69 6d 61 72 79 20 72 65 73 75 ted primary resu
50f0: 6c 74 20 63 6f 64 65 20 61 73 20 61 20 70 72 65 lt code as a pre
5100: 66 69 78 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 fix..**.** {H102
5110: 32 34 7d 20 50 72 69 6d 61 72 79 20 72 65 73 75 24} Primary resu
5120: 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73 20 73 68 lt code names sh
5130: 61 6c 6c 20 63 6f 6e 74 61 69 6e 20 61 20 73 69 all contain a si
5140: 6e 67 6c 65 20 22 5f 22 20 63 68 61 72 61 63 74 ngle "_" charact
5150: 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 er..**.** {H1022
5160: 35 7d 20 45 78 74 65 6e 64 65 64 20 72 65 73 75 5} Extended resu
5170: 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73 20 73 68 lt code names sh
5180: 61 6c 6c 20 63 6f 6e 74 61 69 6e 20 74 77 6f 20 all contain two
5190: 6f 72 20 6d 6f 72 65 20 22 5f 22 20 63 68 61 72 or more "_" char
51a0: 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 acters..**.** {H
51b0: 31 30 32 32 36 7d 20 54 68 65 20 6e 75 6d 65 72 10226} The numer
51c0: 69 63 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 65 ic value of an e
51d0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
51e0: 6f 64 65 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 ode shall contai
51f0: 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 n the.**
5200: 20 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 numeric value
5210: 6f 66 20 69 74 73 20 63 6f 72 72 65 73 70 6f 6e of its correspon
5220: 64 69 6e 67 20 70 72 69 6d 61 72 79 20 72 65 73 ding primary res
5230: 75 6c 74 20 63 6f 64 65 20 69 6e 0a 2a 2a 20 20 ult code in.**
5240: 20 20 20 20 20 20 20 20 69 74 73 20 6c 65 61 73 its leas
5250: 74 20 73 69 67 6e 69 66 69 63 61 6e 74 20 38 20 t significant 8
5260: 62 69 74 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 bits..*/.#define
5270: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 SQLITE_IOERR_RE
5280: 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 AD
5290: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
52a0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (1<<8)).#define
52b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f SQLITE_IOERR_SHO
52c0: 52 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 RT_READ (
52d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
52e0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 2<<8)).#define S
52f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 QLITE_IOERR_WRIT
5300: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 E (S
5310: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 QLITE_IOERR | (3
5320: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5330: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 LITE_IOERR_FSYNC
5340: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
5350: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c LITE_IOERR | (4<
5360: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5370: 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 ITE_IOERR_DIR_FS
5380: 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c YNC (SQL
5390: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c ITE_IOERR | (5<<
53a0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
53b0: 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 TE_IOERR_TRUNCAT
53c0: 45 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 E (SQLI
53d0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 TE_IOERR | (6<<8
53e0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
53f0: 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 E_IOERR_FSTAT
5400: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
5410: 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 E_IOERR | (7<<8)
5420: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5430: 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 _IOERR_UNLOCK
5440: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5450: 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 _IOERR | (8<<8))
5460: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5470: 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 IOERR_RDLOCK
5480: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5490: 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a IOERR | (9<<8)).
54a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
54b0: 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 OERR_DELETE
54c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
54d0: 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a OERR | (10<<8)).
54e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
54f0: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 OERR_BLOCKED
5500: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
5510: 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a OERR | (11<<8)).
5520: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5530: 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 OERR_NOMEM
5540: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
5550: 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a OERR | (12<<8)).
5560: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5570: 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 OERR_ACCESS
5580: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
5590: 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a OERR | (13<<8)).
55a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
55b0: 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 OERR_CHECKRESERV
55c0: 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 EDLOCK (SQLITE_I
55d0: 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a OERR | (14<<8)).
55e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
55f0: 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 OERR_LOCK
5600: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
5610: 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a OERR | (15<<8)).
5620: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
5630: 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 Flags For File
5640: 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 20 Open Operations
5650: 7b 48 31 30 32 33 30 7d 20 3c 48 31 31 31 32 30 {H10230} <H11120
5660: 3e 20 3c 48 31 32 37 30 30 3e 0a 2a 2a 0a 2a 2a > <H12700>.**.**
5670: 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 These bit value
5680: 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 s are intended f
5690: 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a or use in the.**
56a0: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 3rd parameter t
56b0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f o the [sqlite3_o
56c0: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 pen_v2()] interf
56d0: 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 ace and.** in th
56e0: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 4th parameter
56f0: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 to the xOpen met
5700: 68 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 hod of the.** [s
5710: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
5720: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ct..*/.#define S
5730: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
5740: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 NLY 0x00
5750: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 000001.#define S
5760: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
5770: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 RITE 0x00
5780: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 000002.#define S
5790: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
57a0: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 E 0x00
57b0: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 000004.#define S
57c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 QLITE_OPEN_DELET
57d0: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 EONCLOSE 0x00
57e0: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 000008.#define S
57f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 QLITE_OPEN_EXCLU
5800: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 SIVE 0x00
5810: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 000010.#define S
5820: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f QLITE_OPEN_MAIN_
5830: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 DB 0x00
5840: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 000100.#define S
5850: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
5860: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 DB 0x00
5870: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 000200.#define S
5880: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 QLITE_OPEN_TRANS
5890: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 IENT_DB 0x00
58a0: 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 000400.#define S
58b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f QLITE_OPEN_MAIN_
58c0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 JOURNAL 0x00
58d0: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 000800.#define S
58e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
58f0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 JOURNAL 0x00
5900: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 001000.#define S
5910: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f QLITE_OPEN_SUBJO
5920: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 URNAL 0x00
5930: 30 30 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53 002000.#define S
5940: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 QLITE_OPEN_MASTE
5950: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 R_JOURNAL 0x00
5960: 30 30 34 30 30 30 0a 23 64 65 66 69 6e 65 20 53 004000.#define S
5970: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 QLITE_OPEN_NOMUT
5980: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 EX 0x00
5990: 30 30 38 30 30 30 0a 23 64 65 66 69 6e 65 20 53 008000.#define S
59a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d QLITE_OPEN_FULLM
59b0: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30 UTEX 0x00
59c0: 30 31 30 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 010000../*.** CA
59d0: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 PI3REF: Device C
59e0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 7b haracteristics {
59f0: 48 31 30 32 34 30 7d 20 3c 48 31 31 31 32 30 3e H10240} <H11120>
5a00: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 .**.** The xDevi
5a10: 63 65 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d ceCapabilities m
5a20: 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 ethod of the [sq
5a30: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
5a40: 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 ].** object retu
5a50: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 rns an integer w
5a60: 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 hich is a vector
5a70: 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a of the these.**
5a80: 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 bit values expr
5a90: 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 essing I/O chara
5aa0: 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 cteristics of th
5ab0: 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a e mass storage.*
5ac0: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f * device that ho
5ad0: 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 lds the file tha
5ae0: 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 t the [sqlite3_i
5af0: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 o_methods].** re
5b00: 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 fers to..**.** T
5b10: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
5b20: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 ATOMIC property
5b30: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 means that all w
5b40: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 rites of.** any
5b50: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e size are atomic.
5b60: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 The SQLITE_IOC
5b70: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c AP_ATOMICnnn val
5b80: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 ues.** mean that
5b90: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b writes of block
5ba0: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 s that are nnn b
5bb0: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 ytes in size and
5bc0: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 .** are aligned
5bd0: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 to an address wh
5be0: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 ich is an intege
5bf0: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a r multiple of.**
5c00: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e nnn are atomic.
5c10: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 The SQLITE_IOC
5c20: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 AP_SAFE_APPEND v
5c30: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 alue means.** th
5c40: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 at when data is
5c50: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 appended to a fi
5c60: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 le, the data is
5c70: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 appended.** firs
5c80: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 t then the size
5c90: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 of the file is e
5ca0: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 xtended, never t
5cb0: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 he other.** way
5cc0: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c around. The SQL
5cd0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e ITE_IOCAP_SEQUEN
5ce0: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 TIAL property me
5cf0: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f ans that.** info
5d00: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 rmation is writt
5d10: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 en to disk in th
5d20: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 e same order as
5d30: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 calls.** to xWri
5d40: 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 te()..*/.#define
5d50: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
5d60: 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 30 78 OMIC 0x
5d70: 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 00000001.#define
5d80: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
5d90: 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 30 78 OMIC512 0x
5da0: 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 00000002.#define
5db0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
5dc0: 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 30 78 OMIC1K 0x
5dd0: 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 00000004.#define
5de0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
5df0: 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 30 78 OMIC2K 0x
5e00: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 00000008.#define
5e10: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
5e20: 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 30 78 OMIC4K 0x
5e30: 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 00000010.#define
5e40: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
5e50: 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 30 78 OMIC8K 0x
5e60: 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 00000020.#define
5e70: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
5e80: 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 30 78 OMIC16K 0x
5e90: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 00000040.#define
5ea0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
5eb0: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 30 78 OMIC32K 0x
5ec0: 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 00000080.#define
5ed0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
5ee0: 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 30 78 OMIC64K 0x
5ef0: 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 00000100.#define
5f00: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 SQLITE_IOCAP_SA
5f10: 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78 FE_APPEND 0x
5f20: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 00000200.#define
5f30: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 SQLITE_IOCAP_SE
5f40: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78 QUENTIAL 0x
5f50: 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 00000400../*.**
5f60: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c CAPI3REF: File L
5f70: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 48 ocking Levels {H
5f80: 31 30 32 35 30 7d 20 3c 48 31 31 31 32 30 3e 20 10250} <H11120>
5f90: 3c 48 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 <H11310>.**.** S
5fa0: 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f QLite uses one o
5fb0: 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 f these integer
5fc0: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 values as the se
5fd0: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 cond.** argument
5fe0: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b to calls it mak
5ff0: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 es to the xLock(
6000: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 ) and xUnlock()
6010: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e methods.** of an
6020: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
6030: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f hods] object..*/
6040: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6050: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 LOCK_NONE
6060: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0.#define SQL
6070: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 ITE_LOCK_SHARED
6080: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 1.#define
6090: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 SQLITE_LOCK_RES
60a0: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 ERVED 2.#de
60b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b fine SQLITE_LOCK
60c0: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 _PENDING 3
60d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
60e0: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 LOCK_EXCLUSIVE
60f0: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 4../*.** CAPI
6100: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 3REF: Synchroniz
6110: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 ation Type Flags
6120: 20 7b 48 31 30 32 36 30 7d 20 3c 48 31 31 31 32 {H10260} <H1112
6130: 30 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 0>.**.** When SQ
6140: 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 Lite invokes the
6150: 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 xSync() method
6160: 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 of an.** [sqlite
6170: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
6180: 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 ject it uses a c
6190: 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a ombination of.**
61a0: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 these integer v
61b0: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 alues as the sec
61c0: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a ond argument..**
61d0: 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c .** When the SQL
61e0: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c ITE_SYNC_DATAONL
61f0: 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 Y flag is used,
6200: 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 it means that th
6210: 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 e.** sync operat
6220: 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 ion only needs t
6230: 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 o flush data to
6240: 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 mass storage. I
6250: 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 node.** informat
6260: 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 ion need not be
6270: 66 6c 75 73 68 65 64 2e 20 54 68 65 20 53 51 4c flushed. The SQL
6280: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 ITE_SYNC_NORMAL
6290: 66 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f flag means.** to
62a0: 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e use normal fsyn
62b0: 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 20 54 c() semantics. T
62c0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 he SQLITE_SYNC_F
62d0: 55 4c 4c 20 66 6c 61 67 20 6d 65 61 6e 73 0a 2a ULL flag means.*
62e0: 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 2d * to use Mac OS-
62f0: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 X style fullsync
6300: 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e instead of fsyn
6310: 63 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 c()..*/.#define
6320: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d SQLITE_SYNC_NORM
6330: 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30 AL 0x0000
6340: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
6350: 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 _SYNC_FULL
6360: 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 0x00003.#def
6370: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f ine SQLITE_SYNC_
6380: 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 DATAONLY 0x
6390: 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 00010../*.** CAP
63a0: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 I3REF: OS Interf
63b0: 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 ace Open File Ha
63c0: 6e 64 6c 65 20 7b 48 31 31 31 31 30 7d 20 3c 53 ndle {H11110} <S
63d0: 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 20110>.**.** An
63e0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f [sqlite3_file] o
63f0: 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 bject represents
6400: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e an open file in
6410: 20 74 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 the OS.** inter
6420: 66 61 63 65 20 6c 61 79 65 72 2e 20 20 49 6e 64 face layer. Ind
6430: 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 ividual OS inter
6440: 66 61 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 face implementat
6450: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e ions will.** wan
6460: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 t to subclass th
6470: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 is object by app
6480: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 ending additiona
6490: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 l fields.** for
64a0: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 their own use.
64b0: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 The pMethods ent
64c0: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 ry is a pointer
64d0: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 to an.** [sqlite
64e0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
64f0: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 ject that define
6500: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 s methods for pe
6510: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 rforming.** I/O
6520: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 operations on th
6530: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a e open file..*/.
6540: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
6550: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 qlite3_file sqli
6560: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 te3_file;.struct
6570: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a sqlite3_file {.
6580: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 const struct s
6590: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
65a0: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a s *pMethods; /*
65b0: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 Methods for an
65c0: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a open file */.};.
65d0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
65e0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 OS Interface Fi
65f0: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f le Virtual Metho
6600: 64 73 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 32 ds Object {H1112
6610: 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 0} <S20110>.**.*
6620: 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 * Every file ope
6630: 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 ned by the [sqli
6640: 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20 6d te3_vfs] xOpen m
6650: 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 ethod populates
6660: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 an.** [sqlite3_f
6670: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c ile] object (or,
6680: 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 more commonly,
6690: 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 a subclass of th
66a0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 e.** [sqlite3_fi
66b0: 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 le] object) with
66c0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
66d0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 instance of thi
66e0: 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 s object..** Thi
66f0: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 s object defines
6700: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 the methods use
6710: 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 d to perform var
6720: 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a ious operations.
6730: 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f ** against the o
6740: 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 pen file represe
6750: 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c nted by the [sql
6760: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 ite3_file] objec
6770: 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 t..**.** The fla
6780: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 gs argument to x
6790: 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 Sync may be one
67a0: 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f of [SQLITE_SYNC_
67b0: 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 NORMAL] or.** [S
67c0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d QLITE_SYNC_FULL]
67d0: 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f . The first cho
67e0: 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 ice is the norma
67f0: 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 l fsync()..** Th
6800: 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 e second choice
6810: 69 73 20 61 20 4d 61 63 20 4f 53 2d 58 20 73 74 is a Mac OS-X st
6820: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 yle fullsync. T
6830: 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f he [SQLITE_SYNC_
6840: 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 DATAONLY].** fla
6850: 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e g may be ORed in
6860: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 to indicate tha
6870: 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 t only the data
6880: 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 of the file.** a
6890: 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 nd not its inode
68a0: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e needs to be syn
68b0: 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 ced..**.** The i
68c0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f nteger values to
68d0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e xLock() and xUn
68e0: 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f lock() are one o
68f0: 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 f.** <ul>.** <li
6900: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e > [SQLITE_LOCK_N
6910: 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 ONE],.** <li> [S
6920: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 QLITE_LOCK_SHARE
6930: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c D],.** <li> [SQL
6940: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 ITE_LOCK_RESERVE
6950: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c D],.** <li> [SQL
6960: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 ITE_LOCK_PENDING
6970: 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 ], or.** <li> [S
6980: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 QLITE_LOCK_EXCLU
6990: 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a SIVE]..** </ul>.
69a0: 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 ** xLock() incre
69b0: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 ases the lock. x
69c0: 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 Unlock() decreas
69d0: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 es the lock..**
69e0: 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 The xCheckReserv
69f0: 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 edLock() method
6a00: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 checks whether a
6a10: 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ny database conn
6a20: 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 ection,.** eithe
6a30: 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 r in this proces
6a40: 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 s or in some oth
6a50: 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 er process, is h
6a60: 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 olding a RESERVE
6a70: 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f D,.** PENDING, o
6a80: 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b r EXCLUSIVE lock
6a90: 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 on the file. I
6aa0: 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a t returns true.*
6ab0: 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b * if such a lock
6ac0: 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 exists and fals
6ad0: 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a e otherwise..**.
6ae0: 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 ** The xFileCont
6af0: 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 rol() method is
6b00: 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 a generic interf
6b10: 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 ace that allows
6b20: 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d custom.** VFS im
6b30: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f plementations to
6b40: 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f directly contro
6b50: 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 l an open file u
6b60: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c sing the.** [sql
6b70: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
6b80: 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 l()] interface.
6b90: 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 The second "op"
6ba0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a argument is an.
6bb0: 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 ** integer opcod
6bc0: 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 e. The third ar
6bd0: 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 gument is a gene
6be0: 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 ric pointer inte
6bf0: 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 nded to.** point
6c00: 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 to a structure
6c10: 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e that may contain
6c20: 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 arguments or sp
6c30: 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a ace in which to.
6c40: 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 ** write return
6c50: 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 values. Potenti
6c60: 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c al uses for xFil
6c70: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 eControl() might
6c80: 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 be.** functions
6c90: 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b to enable block
6ca0: 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 ing locks with t
6cb0: 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e imeouts, to chan
6cc0: 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e ge the.** lockin
6cd0: 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 g strategy (for
6ce0: 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 example to use d
6cf0: 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 ot-file locks),
6d00: 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 to inquire.** ab
6d10: 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f out the status o
6d20: 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 f a lock, or to
6d30: 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b break stale lock
6d40: 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a s. The SQLite.*
6d50: 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 * core reserves
6d60: 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 all opcodes less
6d70: 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 than 100 for it
6d80: 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 s own use..** A
6d90: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f [SQLITE_FCNTL_LO
6da0: 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f CKSTATE | list o
6db0: 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 f opcodes] less
6dc0: 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 than 100 is avai
6dd0: 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 lable..** Applic
6de0: 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 ations that defi
6df0: 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c ne a custom xFil
6e00: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 eControl method
6e10: 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 should use opcod
6e20: 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 es.** greater th
6e30: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 an 100 to avoid
6e40: 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a conflicts..**.**
6e50: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 The xSectorSize
6e60: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e () method return
6e70: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a s the sector siz
6e80: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 e of the.** devi
6e90: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 ce that underlie
6ea0: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 s the file. The
6eb0: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 sector size is
6ec0: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 the.** minimum w
6ed0: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 rite that can be
6ee0: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f performed witho
6ef0: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a ut disturbing.**
6f00: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 other bytes in
6f10: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 the file. The x
6f20: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 DeviceCharacteri
6f30: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f stics().** metho
6f40: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 d returns a bit
6f50: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e vector describin
6f60: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 g behaviors of t
6f70: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 he.** underlying
6f80: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c device:.**.** <
6f90: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c ul>.** <li> [SQL
6fa0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
6fb0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
6fc0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 E_IOCAP_ATOMIC51
6fd0: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 2].** <li> [SQLI
6fe0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 TE_IOCAP_ATOMIC1
6ff0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
7000: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 TE_IOCAP_ATOMIC2
7010: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
7020: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 TE_IOCAP_ATOMIC4
7030: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
7040: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 TE_IOCAP_ATOMIC8
7050: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
7060: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 TE_IOCAP_ATOMIC1
7070: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 6K].** <li> [SQL
7080: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
7090: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 32K].** <li> [SQ
70a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
70b0: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 C64K].** <li> [S
70c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 QLITE_IOCAP_SAFE
70d0: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e _APPEND].** <li>
70e0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 [SQLITE_IOCAP_S
70f0: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f EQUENTIAL].** </
7100: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 ul>.**.** The SQ
7110: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
7120: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 C property means
7130: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 that all writes
7140: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 of.** any size
7150: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 are atomic. The
7160: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
7170: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a OMICnnn values.*
7180: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 * mean that writ
7190: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 es of blocks tha
71a0: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 t are nnn bytes
71b0: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 in size and.** a
71c0: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e re aligned to an
71d0: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 address which i
71e0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c s an integer mul
71f0: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 tiple of.** nnn
7200: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 are atomic. The
7210: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 SQLITE_IOCAP_SA
7220: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 FE_APPEND value
7230: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 means.** that wh
7240: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e en data is appen
7250: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 ded to a file, t
7260: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e he data is appen
7270: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 ded.** first the
7280: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 n the size of th
7290: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 e file is extend
72a0: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 ed, never the ot
72b0: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e her.** way aroun
72c0: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 d. The SQLITE_I
72d0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 OCAP_SEQUENTIAL
72e0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 property means t
72f0: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 hat.** informati
7300: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f on is written to
7310: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d disk in the sam
7320: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 e order as calls
7330: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e .** to xWrite().
7340: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
7350: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 ct sqlite3_io_me
7360: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f thods sqlite3_io
7370: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 _methods;.struct
7380: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 sqlite3_io_meth
7390: 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 ods {. int iVer
73a0: 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 sion;. int (*xC
73b0: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 lose)(sqlite3_fi
73c0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 le*);. int (*xR
73d0: 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ead)(sqlite3_fil
73e0: 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 e*, void*, int i
73f0: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 Amt, sqlite3_int
7400: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 64 iOfst);. int
7410: 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 (*xWrite)(sqlit
7420: 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 e3_file*, const
7430: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c void*, int iAmt,
7440: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 sqlite3_int64 i
7450: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 Ofst);. int (*x
7460: 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 Truncate)(sqlite
7470: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 3_file*, sqlite3
7480: 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 _int64 size);.
7490: 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c int (*xSync)(sql
74a0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 ite3_file*, int
74b0: 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a flags);. int (*
74c0: 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 xFileSize)(sqlit
74d0: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 e3_file*, sqlite
74e0: 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 3_int64 *pSize);
74f0: 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 . int (*xLock)(
7500: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
7510: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e nt);. int (*xUn
7520: 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 lock)(sqlite3_fi
7530: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 le*, int);. int
7540: 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 (*xCheckReserve
7550: 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 dLock)(sqlite3_f
7560: 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f ile*, int *pResO
7570: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 ut);. int (*xFi
7580: 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 leControl)(sqlit
7590: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 e3_file*, int op
75a0: 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 , void *pArg);.
75b0: 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 int (*xSectorSi
75c0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ze)(sqlite3_file
75d0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 *);. int (*xDev
75e0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 iceCharacteristi
75f0: 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 cs)(sqlite3_file
7600: 2a 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f *);. /* Additio
7610: 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 nal methods may
7620: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 be added in futu
7630: 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d re releases */.}
7640: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
7650: 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 F: Standard File
7660: 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 Control Opcodes
7670: 20 7b 48 31 31 33 31 30 7d 20 3c 53 33 30 38 30 {H11310} <S3080
7680: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 0>.**.** These i
7690: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 nteger constants
76a0: 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 are opcodes for
76b0: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f the xFileContro
76c0: 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 l method.** of t
76d0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d he [sqlite3_io_m
76e0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 ethods] object a
76f0: 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 nd for the [sqli
7700: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
7710: 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 ()].** interface
7720: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c ..**.** The [SQL
7730: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 ITE_FCNTL_LOCKST
7740: 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 ATE] opcode is u
7750: 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e sed for debuggin
7760: 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f g. This.** opco
7770: 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 de causes the xF
7780: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f ileControl metho
7790: 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 d to write the c
77a0: 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a urrent state of.
77b0: 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 ** the lock (one
77c0: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b of [SQLITE_LOCK
77d0: 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f _NONE], [SQLITE_
77e0: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a LOCK_SHARED],.**
77f0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 [SQLITE_LOCK_RE
7800: 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 SERVED], [SQLITE
7810: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 _LOCK_PENDING],
7820: 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f or [SQLITE_LOCK_
7830: 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 EXCLUSIVE]).** i
7840: 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 nto an integer t
7850: 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 hat the pArg arg
7860: 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e ument points to.
7870: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 This capability
7880: 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 .** is used duri
7890: 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f ng testing and o
78a0: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 nly needs to be
78b0: 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 supported when S
78c0: 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 QLITE_TEST.** is
78d0: 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65 defined..*/.#de
78e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
78f0: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 L_LOCKSTATE
7900: 20 20 20 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 1../*.** CAPI
7910: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 3REF: Mutex Hand
7920: 6c 65 20 7b 48 31 37 31 31 30 7d 20 3c 53 32 30 le {H17110} <S20
7930: 31 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 130>.**.** The m
7940: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 utex module with
7950: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 in SQLite define
7960: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 s [sqlite3_mutex
7970: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 ] to be an.** ab
7980: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 stract type for
7990: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 a mutex object.
79a0: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 The SQLite core
79b0: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 never looks.**
79c0: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 at the internal
79d0: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f representation o
79e0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 f an [sqlite3_mu
79f0: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a tex]. It only.*
7a00: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 * deals with poi
7a10: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 nters to the [sq
7a20: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a lite3_mutex] obj
7a30: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 ect..**.** Mutex
7a40: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 es are created u
7a50: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 sing [sqlite3_mu
7a60: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f tex_alloc()]..*/
7a70: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
7a80: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 sqlite3_mutex sq
7a90: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a lite3_mutex;../*
7aa0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 .** CAPI3REF: OS
7ab0: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 Interface Objec
7ac0: 74 20 7b 48 31 31 31 34 30 7d 20 3c 53 32 30 31 t {H11140} <S201
7ad0: 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 00>.**.** An ins
7ae0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c tance of the sql
7af0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 ite3_vfs object
7b00: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 defines the inte
7b10: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a rface between.**
7b20: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 the SQLite core
7b30: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 and the underly
7b40: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 ing operating sy
7b50: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 stem. The "vfs"
7b60: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 .** in the name
7b70: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 of the object st
7b80: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 ands for "virtua
7b90: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a l file system"..
7ba0: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 **.** The value
7bb0: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 of the iVersion
7bc0: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c field is initial
7bd0: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 ly 1 but may be
7be0: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 larger in.** fut
7bf0: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 ure versions of
7c00: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f SQLite. Additio
7c10: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 nal fields may b
7c20: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 e appended to th
7c30: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 is.** object whe
7c40: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 n the iVersion v
7c50: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 alue is increase
7c60: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 d. Note that th
7c70: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f e structure.** o
7c80: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 f the sqlite3_vf
7c90: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 s object changes
7ca0: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 in the transact
7cb0: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 ion between.** S
7cc0: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e QLite version 3.
7cd0: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 5.9 and 3.6.0 an
7ce0: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 d yet the iVersi
7cf0: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 on field was not
7d00: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a .** modified..**
7d10: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 .** The szOsFile
7d20: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 field is the si
7d30: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 ze of the subcla
7d40: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 ssed [sqlite3_fi
7d50: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 le].** structure
7d60: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 used by this VF
7d70: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 S. mxPathname i
7d80: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 s the maximum le
7d90: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 ngth of.** a pat
7da0: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 hname in this VF
7db0: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 S..**.** Registe
7dc0: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 red sqlite3_vfs
7dd0: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 objects are kept
7de0: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 on a linked lis
7df0: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 t formed by.** t
7e00: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 he pNext pointer
7e10: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f . The [sqlite3_
7e20: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a vfs_register()].
7e30: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ** and [sqlite3_
7e40: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 vfs_unregister()
7e50: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e ] interfaces man
7e60: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a age this list.**
7e70: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 in a thread-saf
7e80: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c e way. The [sql
7e90: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d ite3_vfs_find()]
7ea0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 interface.** se
7eb0: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e arches the list.
7ec0: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 Neither the ap
7ed0: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e plication code n
7ee0: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d or the VFS.** im
7ef0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f plementation sho
7f00: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 uld use the pNex
7f10: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a t pointer..**.**
7f20: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 The pNext field
7f30: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 is the only fie
7f40: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 ld in the sqlite
7f50: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 3_vfs.** structu
7f60: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 re that SQLite w
7f70: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e ill ever modify.
7f80: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e SQLite will on
7f90: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 ly access.** or
7fa0: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c modify this fiel
7fb0: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 d while holding
7fc0: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 a particular sta
7fd0: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 tic mutex..** Th
7fe0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 e application sh
7ff0: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 ould never modif
8000: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 y anything withi
8010: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 n the sqlite3_vf
8020: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 s.** object once
8030: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 the object has
8040: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e been registered.
8050: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 .**.** The zName
8060: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 field holds the
8070: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 name of the VFS
8080: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 module. The na
8090: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e me must.** be un
80a0: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 ique across all
80b0: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a VFS modules..**.
80c0: 2a 2a 20 7b 48 31 31 31 34 31 7d 20 53 51 4c 69 ** {H11141} SQLi
80d0: 74 65 20 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 te will guarante
80e0: 65 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 e that the zFile
80f0: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 name parameter t
8100: 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 o xOpen.** is ei
8110: 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e ther a NULL poin
8120: 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 ter or string ob
8130: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 tained.** from x
8140: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 2e 20 FullPathname().
8150: 20 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 SQLite further
8160: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a guarantees that.
8170: 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 ** the string wi
8180: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 ll be valid and
8190: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 unchanged until
81a0: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 xClose() is.** c
81b0: 61 6c 6c 65 64 2e 20 7b 45 4e 44 7d 20 20 42 65 alled. {END} Be
81c0: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 cause of the pre
81d0: 76 69 6f 75 73 20 73 65 6e 74 65 6e 73 65 2c 0a vious sentense,.
81e0: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f ** the [sqlite3_
81f0: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 file] can safely
8200: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 store a pointer
8210: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e to the.** filen
8220: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 ame if it needs
8230: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 to remember the
8240: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d filename for som
8250: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 e reason..** If
8260: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 the zFilename pa
8270: 72 61 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e rameter is xOpen
8280: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
8290: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a er then xOpen.**
82a0: 20 6d 75 73 74 20 69 6e 76 69 74 65 20 69 74 73 must invite its
82b0: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e own temporary n
82c0: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 ame for the file
82d0: 2e 20 20 57 68 65 6e 65 76 65 72 20 74 68 65 20 . Whenever the
82e0: 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 .** xFilename pa
82f0: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 rameter is NULL
8300: 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 it will also be
8310: 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 the case that th
8320: 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d e.** flags param
8330: 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 eter will includ
8340: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 e [SQLITE_OPEN_D
8350: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a ELETEONCLOSE]..*
8360: 2a 0a 2a 2a 20 7b 48 31 31 31 34 32 7d 20 54 68 *.** {H11142} Th
8370: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 e flags argument
8380: 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c to xOpen() incl
8390: 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 udes all bits se
83a0: 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 t in.** the flag
83b0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 s argument to [s
83c0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
83d0: 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 ]. Or if [sqlit
83e0: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 e3_open()].** or
83f0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
8400: 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 ()] is used, the
8410: 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 n flags includes
8420: 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 at least.** [SQ
8430: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
8440: 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f ITE] | [SQLITE_O
8450: 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 7b 45 4e PEN_CREATE]. {EN
8460: 44 7d 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 D}.** If xOpen()
8470: 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 opens a file re
8480: 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 ad-only then it
8490: 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 sets *pOutFlags
84a0: 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 to.** include [S
84b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
84c0: 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 NLY]. Other bit
84d0: 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 s in *pOutFlags
84e0: 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a may be set..**.*
84f0: 2a 20 7b 48 31 31 31 34 33 7d 20 53 51 4c 69 74 * {H11143} SQLit
8500: 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 e will also add
8510: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f one of the follo
8520: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 wing flags to th
8530: 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c e xOpen().** cal
8540: 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 l, depending on
8550: 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 the object being
8560: 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c opened:.**.** <
8570: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 ul>.** <li> [SQ
8580: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 LITE_OPEN_MAIN_D
8590: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c B].** <li> [SQL
85a0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f ITE_OPEN_MAIN_JO
85b0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 URNAL].** <li>
85c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d [SQLITE_OPEN_TEM
85d0: 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b P_DB].** <li> [
85e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 SQLITE_OPEN_TEMP
85f0: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 _JOURNAL].** <li
8600: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
8610: 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a TRANSIENT_DB].**
8620: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
8630: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a PEN_SUBJOURNAL].
8640: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
8650: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 _OPEN_MASTER_JOU
8660: 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b RNAL].** </ul> {
8670: 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 END}.**.** The f
8680: 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e ile I/O implemen
8690: 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 tation can use t
86a0: 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 he object type f
86b0: 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 lags to.** chang
86c0: 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 e the way it dea
86d0: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 ls with files.
86e0: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 For example, an
86f0: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 application.** t
8700: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 hat does not car
8710: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 e about crash re
8720: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 covery or rollba
8730: 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a ck might make.**
8740: 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a the open of a j
8750: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f ournal file a no
8760: 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 -op. Writes to
8770: 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 this journal wou
8780: 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f ld.** also be no
8790: 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 -ops, and any at
87a0: 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 tempt to read th
87b0: 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 e journal would
87c0: 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 return.** SQLITE
87d0: 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 _IOERR. Or the
87e0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d implementation m
87f0: 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 ight recognize t
8800: 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a hat a database.*
8810: 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 * file will be d
8820: 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 oing page-aligne
8830: 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 d sector reads a
8840: 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 nd writes in a r
8850: 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 andom.** order a
8860: 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f nd set up its I/
8870: 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f O subsystem acco
8880: 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 rdingly..**.** S
8890: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f QLite might also
88a0: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 add one of the
88b0: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 following flags
88c0: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 to the xOpen met
88d0: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a hod:.**.** <ul>.
88e0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
88f0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f OPEN_DELETEONCLO
8900: 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c SE].** <li> [SQL
8910: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 ITE_OPEN_EXCLUSI
8920: 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a VE].** </ul>.**.
8930: 2a 2a 20 7b 48 31 31 31 34 35 7d 20 54 68 65 20 ** {H11145} The
8940: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c [SQLITE_OPEN_DEL
8950: 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 ETEONCLOSE] flag
8960: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 means the file
8970: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c should be.** del
8980: 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 eted when it is
8990: 63 6c 6f 73 65 64 2e 20 20 7b 48 31 31 31 34 36 closed. {H11146
89a0: 7d 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 } The [SQLITE_OP
89b0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 EN_DELETEONCLOSE
89c0: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 ].** will be set
89d0: 20 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61 62 for TEMP datab
89e0: 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 61 ases, journals a
89f0: 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61 nd for subjourna
8a00: 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 ls..**.** {H1114
8a10: 37 7d 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 7} The [SQLITE_O
8a20: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 PEN_EXCLUSIVE] f
8a30: 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 lag means the fi
8a40: 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 le should be ope
8a50: 6e 65 64 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 ned.** for exclu
8a60: 73 69 76 65 20 61 63 63 65 73 73 2e 20 20 54 68 sive access. Th
8a70: 69 73 20 66 6c 61 67 20 69 73 20 73 65 74 20 66 is flag is set f
8a80: 6f 72 20 61 6c 6c 20 66 69 6c 65 73 20 65 78 63 or all files exc
8a90: 65 70 74 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d ept.** for the m
8aa0: 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c ain database fil
8ab0: 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 38 e..**.** {H11148
8ac0: 7d 20 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 } At least szOsF
8ad0: 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d ile bytes of mem
8ae0: 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 ory are allocate
8af0: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 d by SQLite.** t
8b00: 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c o hold the [sql
8b10: 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 ite3_file] struc
8b20: 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 ture passed as t
8b30: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 he third.** argu
8b40: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 7b ment to xOpen. {
8b50: 45 4e 44 7d 20 20 54 68 65 20 78 4f 70 65 6e 20 END} The xOpen
8b60: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 method does not
8b70: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 have to.** alloc
8b80: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72 ate the structur
8b90: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 e; it should jus
8ba0: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 0a 2a 2a t fill it in..**
8bb0: 0a 2a 2a 20 7b 48 31 31 31 34 39 7d 20 54 68 65 .** {H11149} The
8bc0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 flags argument
8bd0: 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 to xAccess() may
8be0: 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 be [SQLITE_ACCE
8bf0: 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f SS_EXISTS].** to
8c00: 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 test for the ex
8c10: 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c istence of a fil
8c20: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 e, or [SQLITE_AC
8c30: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 CESS_READWRITE]
8c40: 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 to.** test wheth
8c50: 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 er a file is rea
8c60: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 dable and writab
8c70: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 le, or [SQLITE_A
8c80: 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 CCESS_READ].** t
8c90: 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 o test whether a
8ca0: 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 file is at leas
8cb0: 74 20 72 65 61 64 61 62 6c 65 2e 20 7b 45 4e 44 t readable. {END
8cc0: 7d 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 } The file can
8cd0: 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 be a.** director
8ce0: 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 35 30 y..**.** {H11150
8cf0: 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c } SQLite will al
8d00: 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 ways allocate at
8d10: 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d least mxPathnam
8d20: 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 e+1 bytes for th
8d30: 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 e.** output buff
8d40: 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 er xFullPathname
8d50: 2e 20 7b 48 31 31 31 35 31 7d 20 54 68 65 20 65 . {H11151} The e
8d60: 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 xact size of the
8d70: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a output buffer.*
8d80: 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 * is also passed
8d90: 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 as a parameter
8da0: 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 to both methods
8db0: 2e 20 7b 45 4e 44 7d 20 20 49 66 20 74 68 65 20 . {END} If the
8dc0: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a output buffer.**
8dd0: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e is not large en
8de0: 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 ough, [SQLITE_CA
8df0: 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 NTOPEN] should b
8e00: 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 e returned. Sinc
8e10: 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e e this is.** han
8e20: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 dled as a fatal
8e30: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c error by SQLite,
8e40: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 vfs implementat
8e50: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 ions should ende
8e60: 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 avor.** to preve
8e70: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 nt this by setti
8e80: 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f ng mxPathname to
8e90: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 a sufficiently
8ea0: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a large value..**.
8eb0: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 ** The xRandomne
8ec0: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 ss(), xSleep(),
8ed0: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 and xCurrentTime
8ee0: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a () interfaces.**
8ef0: 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c are not strictl
8f00: 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 y a part of the
8f10: 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 filesystem, but
8f20: 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c they are.** incl
8f30: 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 uded in the VFS
8f40: 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f structure for co
8f50: 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 mpleteness..** T
8f60: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 he xRandomness()
8f70: 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 function attemp
8f80: 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 ts to return nBy
8f90: 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 tes bytes.** of
8fa0: 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e good-quality ran
8fb0: 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 domness into zOu
8fc0: 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 t. The return v
8fd0: 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 alue is.** the a
8fe0: 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 ctual number of
8ff0: 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e bytes of randomn
9000: 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a ess obtained..**
9010: 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 The xSleep() me
9020: 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 thod causes the
9030: 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 calling thread t
9040: 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a o sleep for at.*
9050: 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 * least the numb
9060: 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e er of microsecon
9070: 64 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78 ds given. The x
9080: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a CurrentTime().**
9090: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 method returns
90a0: 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d a Julian Day Num
90b0: 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 ber for the curr
90c0: 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d ent date and tim
90d0: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 e..*/.typedef st
90e0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 ruct sqlite3_vfs
90f0: 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 73 74 sqlite3_vfs;.st
9100: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 ruct sqlite3_vfs
9110: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f {. int iVersio
9120: 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a n; /*
9130: 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69 Structure versi
9140: 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 69 on number */. i
9150: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 nt szOsFile;
9160: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 /* Size
9170: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 of subclassed sq
9180: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 lite3_file */.
9190: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 int mxPathname;
91a0: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 /* Maxi
91b0: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d mum file pathnam
91c0: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 e length */. sq
91d0: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 lite3_vfs *pNext
91e0: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 ; /* Next r
91f0: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f egistered VFS */
9200: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
9210: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e Name; /* N
9220: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 ame of this virt
9230: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 ual file system
9240: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 */. void *pAppD
9250: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a ata; /*
9260: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c Pointer to appl
9270: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 ication-specific
9280: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 data */. int (
9290: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f *xOpen)(sqlite3_
92a0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
92b0: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 *zName, sqlite3
92c0: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 _file*,.
92d0: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 int flags
92e0: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 , int *pOutFlags
92f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 );. int (*xDele
9300: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a te)(sqlite3_vfs*
9310: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
9320: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 ame, int syncDir
9330: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 );. int (*xAcce
9340: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ss)(sqlite3_vfs*
9350: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
9360: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 ame, int flags,
9370: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 int *pResOut);.
9380: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 int (*xFullPath
9390: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 name)(sqlite3_vf
93a0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a s*, const char *
93b0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c zName, int nOut,
93c0: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 char *zOut);.
93d0: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 void *(*xDlOpen)
93e0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
93f0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 onst char *zFile
9400: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a name);. void (*
9410: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 xDlError)(sqlite
9420: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 3_vfs*, int nByt
9430: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 e, char *zErrMsg
9440: 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c );. void *(*xDl
9450: 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 Sym)(sqlite3_vfs
9460: 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 *,void*, const c
9470: 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 3b 0a 20 har *zSymbol);.
9480: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 void (*xDlClose
9490: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
94a0: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a void*);. int (*
94b0: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c xRandomness)(sql
94c0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e ite3_vfs*, int n
94d0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 Byte, char *zOut
94e0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 );. int (*xSlee
94f0: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c p)(sqlite3_vfs*,
9500: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 int microsecond
9510: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 s);. int (*xCur
9520: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 rentTime)(sqlite
9530: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3_vfs*, double*)
9540: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 ;. int (*xGetLa
9550: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 stError)(sqlite3
9560: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 _vfs*, int, char
9570: 20 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69 *);. /* New fi
9580: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 elds may be appe
9590: 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 nded in figure v
95a0: 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 ersions. The iV
95b0: 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 ersion. ** valu
95c0: 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 e will increment
95d0: 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 whenever this h
95e0: 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f appens. */.};../
95f0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
9600: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 lags for the xAc
9610: 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 20 cess VFS method
9620: 7b 48 31 31 31 39 30 7d 20 3c 48 31 31 31 34 30 {H11190} <H11140
9630: 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 39 31 7d >.**.** {H11191}
9640: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 These integer c
9650: 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 onstants can be
9660: 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 used as the thir
9670: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a d parameter to.*
9680: 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 * the xAccess me
9690: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 thod of an [sqli
96a0: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e te3_vfs] object.
96b0: 20 7b 45 4e 44 7d 20 20 54 68 65 79 20 64 65 74 {END} They det
96c0: 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b ermine.** what k
96d0: 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f ind of permissio
96e0: 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d ns the xAccess m
96f0: 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 ethod is looking
9700: 20 66 6f 72 2e 0a 2a 2a 20 7b 48 31 31 31 39 32 for..** {H11192
9710: 7d 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 } With SQLITE_AC
9720: 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 CESS_EXISTS, the
9730: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a xAccess method.
9740: 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 ** simply checks
9750: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c whether the fil
9760: 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 7b 48 31 e exists..** {H1
9770: 31 31 39 33 7d 20 57 69 74 68 20 53 51 4c 49 54 1193} With SQLIT
9780: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 E_ACCESS_READWRI
9790: 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 TE, the xAccess
97a0: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 method.** checks
97b0: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c whether the fil
97c0: 65 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 e is both readab
97d0: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e le and writable.
97e0: 0a 2a 2a 20 7b 48 31 31 31 39 34 7d 20 57 69 74 .** {H11194} Wit
97f0: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f h SQLITE_ACCESS_
9800: 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 READ, the xAcces
9810: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 s method.** chec
9820: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 ks whether the f
9830: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e ile is readable.
9840: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
9850: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 TE_ACCESS_EXISTS
9860: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 0.#define SQ
9870: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
9880: 57 52 49 54 45 20 31 0a 23 64 65 66 69 6e 65 20 WRITE 1.#define
9890: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 SQLITE_ACCESS_RE
98a0: 41 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a AD 2../*.**
98b0: 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 CAPI3REF: Initi
98c0: 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 alize The SQLite
98d0: 20 4c 69 62 72 61 72 79 20 7b 48 31 30 31 33 30 Library {H10130
98e0: 7d 20 3c 53 32 30 30 30 30 3e 3c 53 33 30 31 30 } <S20000><S3010
98f0: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 0>.**.** The sql
9900: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
9910: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 ) routine initia
9920: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c lizes the.** SQL
9930: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 ite library. Th
9940: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f e sqlite3_shutdo
9950: 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 wn() routine.**
9960: 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 deallocates any
9970: 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 resources that w
9980: 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 ere allocated by
9990: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
99a0: 69 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 ize()..**.** A c
99b0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 all to sqlite3_i
99c0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 nitialize() is a
99d0: 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 n "effective" ca
99e0: 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 ll if it is.** t
99f0: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 he first time sq
9a00: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
9a10: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 () is invoked du
9a20: 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d ring the lifetim
9a30: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 e of.** the proc
9a40: 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 ess, or if it is
9a50: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 the first time
9a60: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
9a70: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a ze() is invoked.
9a80: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 ** following a c
9a90: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 all to sqlite3_s
9aa0: 68 75 74 64 6f 77 6e 28 29 2e 20 20 4f 6e 6c 79 hutdown(). Only
9ab0: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 an effective ca
9ac0: 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 ll.** of sqlite3
9ad0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f _initialize() do
9ae0: 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a es any initializ
9af0: 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 ation. All othe
9b00: 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 r calls.** are h
9b10: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 0a armless no-ops..
9b20: 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 **.** Among othe
9b30: 72 20 74 68 69 6e 67 73 2c 20 73 71 6c 69 74 65 r things, sqlite
9b40: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 3_initialize() s
9b50: 68 61 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 hall invoke.** s
9b60: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
9b70: 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 73 71 . Similarly, sq
9b80: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
9b90: 0a 2a 2a 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 .** shall invoke
9ba0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
9bb0: 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c )..**.** The sql
9bc0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
9bd0: 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ) routine return
9be0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e s [SQLITE_OK] on
9bf0: 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 49 66 20 success..** If
9c00: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c for some reason,
9c10: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
9c20: 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 ize() is unable
9c30: 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a to initialize.**
9c40: 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 the library (pe
9c50: 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 rhaps it is unab
9c60: 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 le to allocate a
9c70: 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 needed resource
9c80: 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 such.** as a mu
9c90: 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 tex) it returns
9ca0: 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 an [error code]
9cb0: 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 other than [SQLI
9cc0: 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 TE_OK]..**.** Th
9cd0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
9ce0: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 lize() routine i
9cf0: 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 s called interna
9d00: 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 lly by many othe
9d10: 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 r.** SQLite inte
9d20: 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 rfaces so that a
9d30: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 n application us
9d40: 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e ually does not n
9d50: 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 eed to.** invoke
9d60: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
9d70: 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 ize() directly.
9d80: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 For example, [s
9d90: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a qlite3_open()].*
9da0: 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f * calls sqlite3_
9db0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 initialize() so
9dc0: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 the SQLite libra
9dd0: 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d ry will be autom
9de0: 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 atically.** init
9df0: 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 ialized when [sq
9e00: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 lite3_open()] is
9e10: 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 called if it ha
9e20: 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c s not be initial
9e30: 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e ized.** already.
9e40: 20 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 However, if SQ
9e50: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
9e60: 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 with the [SQLIT
9e70: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d E_OMIT_AUTOINIT]
9e80: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 .** compile-time
9e90: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 option, then th
9ea0: 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c e automatic call
9eb0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 s to sqlite3_ini
9ec0: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 tialize().** are
9ed0: 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 omitted and the
9ee0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
9ef0: 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 t call sqlite3_i
9f00: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 nitialize() dire
9f10: 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f ctly.** prior to
9f20: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 using any other
9f30: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
9f40: 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 e. For maximum
9f50: 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 portability,.**
9f60: 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 it is recommende
9f70: 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 d that applicati
9f80: 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b ons always invok
9f90: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
9fa0: 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 lize().** direct
9fb0: 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e ly prior to usin
9fc0: 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 g any other SQLi
9fd0: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 te interface. F
9fe0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a uture releases.*
9ff0: 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 * of SQLite may
a000: 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 require this. I
a010: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 n other words, t
a020: 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 he behavior exhi
a030: 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 bited.** when SQ
a040: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
a050: 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d with [SQLITE_OM
a060: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 IT_AUTOINIT] mig
a070: 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a ht become the.**
a080: 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f default behavio
a090: 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 r in some future
a0a0: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 release of SQLi
a0b0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 te..**.** The sq
a0c0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 lite3_os_init()
a0d0: 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 routine does ope
a0e0: 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 rating-system sp
a0f0: 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 ecific.** initia
a100: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 lization of the
a110: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 SQLite library.
a120: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f The sqlite3_os_
a130: 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 end().** routine
a140: 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 undoes the effe
a150: 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 ct of sqlite3_os
a160: 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 _init(). Typica
a170: 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f l tasks.** perfo
a180: 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f rmed by these ro
a190: 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 utines include a
a1a0: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 llocation or dea
a1b0: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 llocation.** of
a1c0: 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 static resources
a1d0: 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e , initialization
a1e0: 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 of global varia
a1f0: 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 bles,.** setting
a200: 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 up a default [s
a210: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 qlite3_vfs] modu
a220: 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 le, or setting u
a230: 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 p.** a default c
a240: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 onfiguration usi
a250: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ng [sqlite3_conf
a260: 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ig()]..**.** The
a270: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f application sho
a280: 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 uld never invoke
a290: 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f either sqlite3_
a2a0: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 os_init().** or
a2b0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 sqlite3_os_end()
a2c0: 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 directly. The
a2d0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 application shou
a2e0: 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a ld only invoke.*
a2f0: 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 * sqlite3_initia
a300: 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 lize() and sqlit
a310: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 e3_shutdown().
a320: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 The sqlite3_os_i
a330: 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 nit().** interfa
a340: 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 ce is called aut
a350: 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 omatically by sq
a360: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
a370: 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 () and.** sqlite
a380: 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 3_os_end() is ca
a390: 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f lled by sqlite3_
a3a0: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 shutdown(). App
a3b0: 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c ropriate.** impl
a3c0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 ementations for
a3d0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
a3e0: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 ) and sqlite3_os
a3f0: 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 _end().** are bu
a400: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 ilt into SQLite
a410: 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 when it is compi
a420: 6c 65 64 20 66 6f 72 20 75 6e 69 78 2c 20 77 69 led for unix, wi
a430: 6e 64 6f 77 73 2c 20 6f 72 20 6f 73 2f 32 2e 0a ndows, or os/2..
a440: 2a 2a 20 57 68 65 6e 20 62 75 69 6c 74 20 66 6f ** When built fo
a450: 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d r other platform
a460: 73 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 s (using the [SQ
a470: 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d LITE_OS_OTHER=1]
a480: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a compile-time.**
a490: 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 option) the app
a4a0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 lication must su
a4b0: 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 pply a suitable
a4c0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 implementation f
a4d0: 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 or.** sqlite3_os
a4e0: 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 _init() and sqli
a4f0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 te3_os_end(). A
a500: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 n application-su
a510: 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d pplied.** implem
a520: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 entation of sqli
a530: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 te3_os_init() or
a540: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
a550: 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e ).** must return
a560: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 [SQLITE_OK] on
a570: 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 success and some
a580: 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f other [error co
a590: 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c de] upon.** fail
a5a0: 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ure..*/.int sqli
a5b0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 te3_initialize(v
a5c0: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 oid);.int sqlite
a5d0: 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3_shutdown(void)
a5e0: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 ;.int sqlite3_os
a5f0: 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 _init(void);.int
a600: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
a610: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 void);../*.** CA
a620: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 PI3REF: Configur
a630: 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c ing The SQLite L
a640: 69 62 72 61 72 79 20 7b 48 31 34 31 30 30 7d 20 ibrary {H14100}
a650: 3c 53 32 30 30 30 30 3e 3c 53 33 30 32 30 30 3e <S20000><S30200>
a660: 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c .** EXPERIMENTAL
a670: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
a680: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 e3_config() inte
a690: 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f rface is used to
a6a0: 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e make global con
a6b0: 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 figuration.** ch
a6c0: 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 anges to SQLite
a6d0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 in order to tune
a6e0: 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 SQLite to the s
a6f0: 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 pecific needs of
a700: 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 .** the applicat
a710: 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c ion. The defaul
a720: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 t configuration
a730: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 is recommended f
a740: 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 or most.** appli
a750: 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 cations and so t
a760: 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 his routine is u
a770: 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 sually not neces
a780: 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 sary. It is.**
a790: 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 provided to supp
a7a0: 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 ort rare applica
a7b0: 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 tions with unusu
a7c0: 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 al needs..**.**
a7d0: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 The sqlite3_conf
a7e0: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 ig() interface i
a7f0: 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 s not threadsafe
a800: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 . The applicati
a810: 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 on.** must insur
a820: 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 e that no other
a830: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
a840: 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 s are invoked by
a850: 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 other.** thread
a860: 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f s while sqlite3_
a870: 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e config() is runn
a880: 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 ing. Furthermor
a890: 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 e, sqlite3_confi
a8a0: 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 g().** may only
a8b0: 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 be invoked prior
a8c0: 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 to library init
a8d0: 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 ialization using
a8e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 .** [sqlite3_ini
a8f0: 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 tialize()] or af
a900: 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 ter shutdown by
a910: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 [sqlite3_shutdow
a920: 6e 28 29 5d 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 n()]..** Note, h
a930: 6f 77 65 76 65 72 2c 20 74 68 61 74 20 73 71 6c owever, that sql
a940: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 ite3_config() ca
a950: 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 n be called as p
a960: 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d art of the.** im
a970: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
a980: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 an application-d
a990: 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f efined [sqlite3_
a9a0: 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a os_init()]..**.*
a9b0: 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 * The first argu
a9c0: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f ment to sqlite3_
a9d0: 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 config() is an i
a9e0: 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 nteger.** [SQLIT
a9f0: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
aa00: 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 HREAD | configur
aa10: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 ation option] th
aa20: 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a at determines.**
aa30: 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f what property o
aa40: 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 f SQLite is to b
aa50: 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 e configured. S
aa60: 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 ubsequent argume
aa70: 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 nts.** vary depe
aa80: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51 nding on the [SQ
aa90: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 LITE_CONFIG_SING
aaa0: 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 LETHREAD | confi
aab0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d guration option]
aac0: 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 .** in the first
aad0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a argument..**.**
aae0: 20 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 When a configur
aaf0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 ation option is
ab00: 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e set, sqlite3_con
ab10: 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 fig() returns [S
ab20: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 49 66 QLITE_OK]..** If
ab30: 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 the option is u
ab40: 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 nknown or SQLite
ab50: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 is unable to se
ab60: 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 t the option.**
ab70: 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e then this routin
ab80: 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d e returns a non-
ab90: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 zero [error code
aba0: 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 ]..**.** INVARIA
abb0: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 NTS:.**.** {H141
abc0: 30 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 03} A successful
abd0: 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b invocation of [
abe0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
abf0: 5d 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 0a 2a ] shall return.*
ac00: 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 * [SQLI
ac10: 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 TE_OK]..**.** {H
ac20: 31 34 31 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 14106} The [sqli
ac30: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e te3_config()] in
ac40: 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 terface shall re
ac50: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 turn [SQLITE_MIS
ac60: 55 53 45 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 USE].**
ac70: 20 69 66 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 if it is invoke
ac80: 64 20 69 6e 20 62 65 74 77 65 65 6e 20 63 61 6c d in between cal
ac90: 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 69 ls to [sqlite3_i
aca0: 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 nitialize()] and
acb0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
acc0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
acd0: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 32 30 ]..**.** {H14120
ace0: 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 } A successful c
acf0: 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
ad00: 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f config]([SQLITE_
ad10: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 CONFIG_SINGLETHR
ad20: 45 41 44 5d 29 0a 2a 2a 20 20 20 20 20 20 20 20 EAD]).**
ad30: 20 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 shall set the
ad40: 64 65 66 61 75 6c 74 20 5b 74 68 72 65 61 64 69 default [threadi
ad50: 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 ng mode] to Sing
ad60: 6c 65 2d 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a le-thread..**.**
ad70: 20 7b 48 31 34 31 32 33 7d 20 41 20 73 75 63 63 {H14123} A succ
ad80: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b essful call to [
ad90: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 sqlite3_config](
ada0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
adb0: 55 4c 54 49 54 48 52 45 41 44 5d 29 0a 2a 2a 20 ULTITHREAD]).**
adc0: 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 73 shall s
add0: 65 74 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b et the default [
ade0: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
adf0: 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e to Multi-thread.
ae00: 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 32 36 7d 20 .**.** {H14126}
ae10: 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c A successful cal
ae20: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f l to [sqlite3_co
ae30: 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f nfig]([SQLITE_CO
ae40: 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d NFIG_SERIALIZED]
ae50: 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 ).** sh
ae60: 61 6c 6c 20 73 65 74 20 74 68 65 20 64 65 66 61 all set the defa
ae70: 75 6c 74 20 5b 74 68 72 65 61 64 69 6e 67 20 6d ult [threading m
ae80: 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a ode] to Serializ
ae90: 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 32 ed..**.** {H1412
aea0: 39 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 9} A successful
aeb0: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
aec0: 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 _config]([SQLITE
aed0: 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2c 58 _CONFIG_MUTEX],X
aee0: 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 ).** wh
aef0: 65 72 65 20 58 20 69 73 20 61 20 70 6f 69 6e 74 ere X is a point
af00: 65 72 20 74 6f 20 61 6e 20 69 6e 69 74 69 61 6c er to an initial
af10: 69 7a 65 64 20 5b 73 71 6c 69 74 65 33 5f 6d 75 ized [sqlite3_mu
af20: 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 tex_methods].**
af30: 20 20 20 20 20 20 20 20 20 6f 62 6a 65 63 74 20 object
af40: 73 68 61 6c 6c 20 63 61 75 73 65 20 61 6c 6c 20 shall cause all
af50: 73 75 62 73 65 71 75 65 6e 74 20 6d 75 74 65 78 subsequent mutex
af60: 20 6f 70 65 72 61 74 69 6f 6e 73 20 70 65 72 66 operations perf
af70: 6f 72 6d 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 ormed.**
af80: 20 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 75 by SQLite to u
af90: 73 65 20 74 68 65 20 6d 75 74 65 78 20 6d 65 74 se the mutex met
afa0: 68 6f 64 73 20 74 68 61 74 20 77 65 72 65 20 70 hods that were p
afb0: 72 65 73 65 6e 74 20 69 6e 20 58 0a 2a 2a 20 20 resent in X.**
afc0: 20 20 20 20 20 20 20 20 64 75 72 69 6e 67 20 74 during t
afd0: 68 65 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 he call to [sqli
afe0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a te3_config()]..*
aff0: 2a 0a 2a 2a 20 7b 48 31 34 31 33 32 7d 20 41 20 *.** {H14132} A
b000: 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 successful call
b010: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 to [sqlite3_conf
b020: 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ig]([SQLITE_CONF
b030: 49 47 5f 47 45 54 4d 55 54 45 58 5d 2c 58 29 0a IG_GETMUTEX],X).
b040: 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 72 ** wher
b050: 65 20 58 20 69 73 20 61 20 70 6f 69 6e 74 65 72 e X is a pointer
b060: 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f to an [sqlite3_
b070: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 6f mutex_methods] o
b080: 62 6a 65 63 74 20 0a 2a 2a 20 20 20 20 20 20 20 bject .**
b090: 20 20 20 73 68 61 6c 6c 20 6f 76 65 72 77 72 69 shall overwri
b0a0: 74 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f te the content o
b0b0: 66 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 f [sqlite3_mutex
b0c0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 _methods] object
b0d0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 .** wit
b0e0: 68 20 74 68 65 20 6d 75 74 65 78 20 6d 65 74 68 h the mutex meth
b0f0: 6f 64 73 20 63 75 72 72 65 6e 74 6c 79 20 69 6e ods currently in
b100: 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 2e 0a use by SQLite..
b110: 2a 2a 0a 2a 2a 20 7b 48 31 34 31 33 35 7d 20 41 **.** {H14135} A
b120: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c successful call
b130: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e to [sqlite3_con
b140: 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e fig]([SQLITE_CON
b150: 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2c 4d 29 0a 2a FIG_MALLOC],M).*
b160: 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 72 65 * where
b170: 20 4d 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 M is a pointer
b180: 74 6f 20 61 6e 20 69 6e 69 74 69 61 6c 69 7a 65 to an initialize
b190: 64 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d d [sqlite3_mem_m
b1a0: 65 74 68 6f 64 73 5d 0a 2a 2a 20 20 20 20 20 20 ethods].**
b1b0: 20 20 20 20 6f 62 6a 65 63 74 20 73 68 61 6c 6c object shall
b1c0: 20 63 61 75 73 65 20 61 6c 6c 20 73 75 62 73 65 cause all subse
b1d0: 71 75 65 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c quent memory all
b1e0: 6f 63 61 74 69 6f 6e 20 6f 70 65 72 61 74 69 6f ocation operatio
b1f0: 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 ns.** p
b200: 65 72 66 6f 72 6d 65 64 20 62 79 20 53 51 4c 69 erformed by SQLi
b210: 74 65 20 74 6f 20 75 73 65 20 74 68 65 20 6d 65 te to use the me
b220: 74 68 6f 64 73 20 74 68 61 74 20 77 65 72 65 20 thods that were
b230: 70 72 65 73 65 6e 74 20 69 6e 20 0a 2a 2a 20 20 present in .**
b240: 20 20 20 20 20 20 20 20 4d 20 64 75 72 69 6e 67 M during
b250: 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 5b 73 71 the call to [sq
b260: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e lite3_config()].
b270: 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 33 38 7d 20 .**.** {H14138}
b280: 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c A successful cal
b290: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f l to [sqlite3_co
b2a0: 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f nfig]([SQLITE_CO
b2b0: 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2c NFIG_GETMALLOC],
b2c0: 4d 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 M).** w
b2d0: 68 65 72 65 20 4d 20 69 73 20 61 20 70 6f 69 6e here M is a poin
b2e0: 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 ter to an [sqlit
b2f0: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 e3_mem_methods]
b300: 6f 62 6a 65 63 74 20 73 68 61 6c 6c 0a 2a 2a 20 object shall.**
b310: 20 20 20 20 20 20 20 20 20 6f 76 65 72 77 72 69 overwri
b320: 74 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f te the content o
b330: 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d f [sqlite3_mem_m
b340: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 77 ethods] object w
b350: 69 74 68 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 ith .**
b360: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f the memory allo
b370: 63 61 74 69 6f 6e 20 6d 65 74 68 6f 64 73 20 63 cation methods c
b380: 75 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 20 urrently in use
b390: 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 by.** S
b3a0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 QLite..**.** {H1
b3b0: 34 31 34 31 7d 20 41 20 73 75 63 63 65 73 73 66 4141} A successf
b3c0: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 ul call to [sqli
b3d0: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c te3_config]([SQL
b3e0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 ITE_CONFIG_MEMST
b3f0: 41 54 55 53 5d 2c 31 29 0a 2a 2a 20 20 20 20 20 ATUS],1).**
b400: 20 20 20 20 20 73 68 61 6c 6c 20 65 6e 61 62 6c shall enabl
b410: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c e the memory all
b420: 6f 63 61 74 69 6f 6e 20 73 74 61 74 75 73 20 63 ocation status c
b430: 6f 6c 6c 65 63 74 69 6f 6e 20 6c 6f 67 69 63 2e ollection logic.
b440: 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 34 34 7d 20 .**.** {H14144}
b450: 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c A successful cal
b460: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f l to [sqlite3_co
b470: 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f nfig]([SQLITE_CO
b480: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 2c NFIG_MEMSTATUS],
b490: 30 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 0).** s
b4a0: 68 61 6c 6c 20 64 69 73 61 62 6c 65 20 74 68 65 hall disable the
b4b0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
b4c0: 6f 6e 20 73 74 61 74 75 73 20 63 6f 6c 6c 65 63 on status collec
b4d0: 74 69 6f 6e 20 6c 6f 67 69 63 2e 0a 2a 2a 0a 2a tion logic..**.*
b4e0: 2a 20 7b 48 31 34 31 34 37 7d 20 54 68 65 20 6d * {H14147} The m
b4f0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
b500: 20 73 74 61 74 75 73 20 63 6f 6c 6c 65 63 74 69 status collecti
b510: 6f 6e 20 6c 6f 67 69 63 20 73 68 61 6c 6c 20 62 on logic shall b
b520: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e e.** en
b530: 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 abled by default
b540: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 35 30 7d ..**.** {H14150}
b550: 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 A successful ca
b560: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ll to [sqlite3_c
b570: 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 onfig]([SQLITE_C
b580: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 2c 53 ONFIG_SCRATCH],S
b590: 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 20 20 20 20 20 ,Z,N).**
b5a0: 20 20 77 68 65 72 65 20 5a 20 61 6e 64 20 4e 20 where Z and N
b5b0: 61 72 65 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 are non-negative
b5c0: 20 69 6e 74 65 67 65 72 73 20 61 6e 64 20 0a 2a integers and .*
b5d0: 2a 20 20 20 20 20 20 20 20 20 20 53 20 69 73 20 * S is
b5e0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
b5f0: 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 aligned memory b
b600: 75 66 66 65 72 20 6e 6f 74 20 6c 65 73 73 20 74 uffer not less t
b610: 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 han.**
b620: 5a 2a 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a Z*N bytes in siz
b630: 65 20 73 68 61 6c 6c 20 63 61 75 73 65 20 53 20 e shall cause S
b640: 74 6f 20 62 65 20 75 73 65 64 20 62 79 20 74 68 to be used by th
b650: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 e.** [s
b660: 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 6c cratch memory al
b670: 6c 6f 63 61 74 6f 72 5d 20 66 6f 72 20 61 73 20 locator] for as
b680: 6d 61 6e 79 20 61 73 20 4e 20 73 69 6d 75 6c 61 many as N simula
b690: 74 61 6e 65 6f 75 73 0a 2a 2a 20 20 20 20 20 20 taneous.**
b6a0: 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 allocations
b6b0: 65 61 63 68 20 6f 66 20 73 69 7a 65 20 5a 2e 0a each of size Z..
b6c0: 2a 2a 0a 2a 2a 20 7b 48 31 34 31 35 33 7d 20 41 **.** {H14153} A
b6d0: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c successful call
b6e0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e to [sqlite3_con
b6f0: 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e fig]([SQLITE_CON
b700: 46 49 47 5f 53 43 52 41 54 43 48 5d 2c 53 2c 5a FIG_SCRATCH],S,Z
b710: 2c 4e 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ,N).**
b720: 77 68 65 72 65 20 53 20 69 73 20 61 20 4e 55 4c where S is a NUL
b730: 4c 20 70 6f 69 6e 74 65 72 20 73 68 61 6c 6c 20 L pointer shall
b740: 64 69 73 61 62 6c 65 20 74 68 65 0a 2a 2a 20 20 disable the.**
b750: 20 20 20 20 20 20 20 20 5b 73 63 72 61 74 63 68 [scratch
b760: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
b770: 72 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 35 r]..**.** {H1415
b780: 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 6} A successful
b790: 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 call to.**
b7a0: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e [sqlite3_con
b7b0: 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e fig]([SQLITE_CON
b7c0: 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2c 53 FIG_PAGECACHE],S
b7d0: 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 20 20 20 20 20 ,Z,N).**
b7e0: 20 20 77 68 65 72 65 20 5a 20 61 6e 64 20 4e 20 where Z and N
b7f0: 61 72 65 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 are non-negative
b800: 20 69 6e 74 65 67 65 72 73 20 61 6e 64 20 0a 2a integers and .*
b810: 2a 20 20 20 20 20 20 20 20 20 20 53 20 69 73 20 * S is
b820: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
b830: 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 aligned memory b
b840: 75 66 66 65 72 20 6e 6f 74 20 6c 65 73 73 20 74 uffer not less t
b850: 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 han.**
b860: 5a 2a 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a Z*N bytes in siz
b870: 65 20 73 68 61 6c 6c 20 63 61 75 73 65 20 53 20 e shall cause S
b880: 74 6f 20 62 65 20 75 73 65 64 20 62 79 20 74 68 to be used by th
b890: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 e.** [p
b8a0: 61 67 65 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 agecache memory
b8b0: 61 6c 6c 6f 63 61 74 6f 72 5d 20 66 6f 72 20 61 allocator] for a
b8c0: 73 20 6d 61 6e 79 20 61 73 20 4e 20 73 69 6d 75 s many as N simu
b8d0: 6c 61 74 61 6e 65 6f 75 73 0a 2a 2a 20 20 20 20 lataneous.**
b8e0: 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e allocation
b8f0: 73 20 65 61 63 68 20 6f 66 20 73 69 7a 65 20 5a s each of size Z
b900: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 35 39 7d ..**.** {H14159}
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 53 20 69 73 20 61 20 4e 55 4c where S is a NUL
b980: 4c 20 70 6f 69 6e 74 65 72 20 73 68 61 6c 6c 20 L pointer shall
b990: 64 69 73 61 62 6c 65 20 74 68 65 0a 2a 2a 20 20 disable the.**
b9a0: 20 20 20 20 20 20 20 20 5b 70 61 67 65 63 61 63 [pagecac
b9b0: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
b9c0: 74 6f 72 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 tor]..**.** {H14
b9d0: 31 36 32 7d 20 41 20 73 75 63 63 65 73 73 66 75 162} A successfu
b9e0: 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 l call to [sqlit
b9f0: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 e3_config]([SQLI
ba00: 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 2c TE_CONFIG_HEAP],
ba10: 48 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 20 20 20 20 H,Z,N).**
ba20: 20 20 20 77 68 65 72 65 20 5a 20 61 6e 64 20 4e where Z and N
ba30: 20 61 72 65 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 are non-negativ
ba40: 65 20 69 6e 74 65 67 65 72 73 20 61 6e 64 20 0a e integers and .
ba50: 2a 2a 20 20 20 20 20 20 20 20 20 20 48 20 69 73 ** H is
ba60: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
ba70: 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 aligned memory
ba80: 62 75 66 66 65 72 20 6e 6f 74 20 6c 65 73 73 20 buffer not less
ba90: 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 than.**
baa0: 20 5a 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 Z bytes in size
bab0: 20 73 68 61 6c 6c 20 65 6e 61 62 6c 65 20 74 68 shall enable th
bac0: 65 20 5b 6d 65 6d 73 79 73 35 5d 20 6d 65 6d 6f e [memsys5] memo
bad0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 0a 2a 2a 20 ry allocator.**
bae0: 20 20 20 20 20 20 20 20 20 61 6e 64 20 63 61 75 and cau
baf0: 73 65 20 69 74 20 74 6f 20 75 73 65 20 62 75 66 se it to use buf
bb00: 66 65 72 20 53 20 61 73 20 69 74 73 20 6d 65 6d fer S as its mem
bb10: 6f 72 79 20 73 6f 75 72 63 65 20 61 6e 64 20 74 ory source and t
bb20: 6f 20 75 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 o use.**
bb30: 20 20 61 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f a minimum allo
bb40: 63 61 74 69 6f 6e 20 73 69 7a 65 20 6f 66 20 4e cation size of N
bb50: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 36 35 7d ..**.** {H14165}
bb60: 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 A successful ca
bb70: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ll to [sqlite3_c
bb80: 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 onfig]([SQLITE_C
bb90: 4f 4e 46 49 47 5f 48 45 41 50 5d 2c 48 2c 5a 2c ONFIG_HEAP],H,Z,
bba0: 4e 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 N).** w
bbb0: 68 65 72 65 20 48 20 69 73 20 61 20 4e 55 4c 4c here H is a NULL
bbc0: 20 70 6f 69 6e 74 65 72 20 73 68 61 6c 6c 20 64 pointer shall d
bbd0: 69 73 61 62 6c 65 20 74 68 65 0a 2a 2a 20 20 20 isable the.**
bbe0: 20 20 20 20 20 20 20 5b 6d 65 6d 73 79 73 35 5d [memsys5]
bbf0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
bc00: 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 36 38 r..**.** {H14168
bc10: 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 } A successful c
bc20: 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
bc30: 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f config]([SQLITE_
bc40: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
bc50: 5d 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 20 20 20 20 ],Z,N).**
bc60: 20 20 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74 shall cause t
bc70: 68 65 20 64 65 66 61 75 6c 74 20 5b 6c 6f 6f 6b he default [look
bc80: 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c aside memory all
bc90: 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 ocator] configur
bca0: 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 ation.**
bcb0: 20 20 66 6f 72 20 6e 65 77 20 5b 64 61 74 61 62 for new [datab
bcc0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d ase connections]
bcd0: 20 74 6f 20 62 65 20 4e 20 73 6c 6f 74 73 20 6f to be N slots o
bce0: 66 20 5a 20 62 79 74 65 73 20 65 61 63 68 2e 0a f Z bytes each..
bcf0: 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 */.SQLITE_EXPERI
bd00: 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 MENTAL int sqlit
bd10: 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e e3_config(int, .
bd20: 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ..);../*.** CAPI
bd30: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 3REF: Configure
bd40: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
bd50: 69 6f 6e 73 20 20 7b 48 31 34 32 30 30 7d 20 3c ions {H14200} <
bd60: 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52 S20000>.** EXPER
bd70: 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 IMENTAL.**.** Th
bd80: 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e e sqlite3_db_con
bd90: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 fig() interface
bda0: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 is used to make
bdb0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a configuration.**
bdc0: 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 changes to a [d
bdd0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
bde0: 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 on]. The interf
bdf0: 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 ace is similar t
be00: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f o.** [sqlite3_co
be10: 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 nfig()] except t
be20: 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 hat the changes
be30: 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c apply to a singl
be40: 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 e.** [database c
be50: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 onnection] (spec
be60: 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 ified in the fir
be70: 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 20 20 54 st argument). T
be80: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 64 62 he.** sqlite3_db
be90: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 _config() interf
bea0: 61 63 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 ace can only be
beb0: 75 73 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 used immediately
bec0: 20 61 66 74 65 72 0a 2a 2a 20 74 68 65 20 64 61 after.** the da
bed0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
bee0: 6e 20 69 73 20 63 72 65 61 74 65 64 20 75 73 69 n is created usi
bef0: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ng [sqlite3_open
bf00: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
bf10: 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b _open16()], or [
bf20: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
bf30: 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 )]. .**.** The
bf40: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
bf50: 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f to sqlite3_db_co
bf60: 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 nfig(D,V,...) i
bf70: 73 20 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 s the.** configu
bf80: 72 61 74 69 6f 6e 20 76 65 72 62 20 2d 20 61 6e ration verb - an
bf90: 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 integer code th
bfa0: 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 at indicates wha
bfb0: 74 0a 2a 2a 20 61 73 70 65 63 74 20 6f 66 20 74 t.** aspect of t
bfc0: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
bfd0: 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e nection] is bein
bfe0: 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a g configured..**
bff0: 20 54 68 65 20 6f 6e 6c 79 20 63 68 6f 69 63 65 The only choice
c000: 20 66 6f 72 20 74 68 69 73 20 76 61 6c 75 65 20 for this value
c010: 69 73 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e is [SQLITE_DBCON
c020: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a FIG_LOOKASIDE]..
c030: 2a 2a 20 4e 65 77 20 76 65 72 62 73 20 61 72 65 ** New verbs are
c040: 20 6c 69 6b 65 6c 79 20 74 6f 20 62 65 20 61 64 likely to be ad
c050: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
c060: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
c070: 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 ..** Additional
c080: 61 72 67 75 6d 65 6e 74 73 20 64 65 70 65 6e 64 arguments depend
c090: 20 6f 6e 20 74 68 65 20 76 65 72 62 2e 0a 2a 2a on the verb..**
c0a0: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
c0b0: 2a 2a 0a 2a 2a 20 7b 48 31 34 32 30 33 7d 20 41 **.** {H14203} A
c0c0: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
c0d0: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 3_db_config(D,V,
c0e0: 2e 2e 2e 29 5d 20 73 68 61 6c 6c 20 72 65 74 75 ...)] shall retu
c0f0: 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 0a 2a rn [SQLITE_OK].*
c100: 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 61 6e * if an
c110: 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 63 61 d only if the ca
c120: 6c 6c 20 69 73 20 73 75 63 63 65 73 73 66 75 6c ll is successful
c130: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 32 30 36 7d ..**.** {H14206}
c140: 20 49 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 If one or more
c150: 73 6c 6f 74 73 20 6f 66 20 74 68 65 20 5b 6c 6f slots of the [lo
c160: 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 okaside memory a
c170: 6c 6c 6f 63 61 74 6f 72 5d 20 66 6f 72 0a 2a 2a llocator] for.**
c180: 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 [datab
c190: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
c1a0: 44 20 61 72 65 20 69 6e 20 75 73 65 2c 20 74 68 D are in use, th
c1b0: 65 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 en a call to.**
c1c0: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
c1d0: 33 5f 64 62 5f 63 6f 6e 66 69 67 5d 28 44 2c 5b 3_db_config](D,[
c1e0: 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
c1f0: 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 LOOKASIDE],...)
c200: 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 shall.**
c210: 20 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 5b fail with an [
c220: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 72 65 74 SQLITE_BUSY] ret
c230: 75 72 6e 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 urn code..**.**
c240: 7b 48 31 34 32 30 39 7d 20 41 20 73 75 63 63 65 {H14209} A succe
c250: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a ssful call to .*
c260: 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
c270: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 5d 28 44 te3_db_config](D
c280: 2c 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 ,[SQLITE_DBCONFI
c290: 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 42 2c 5a G_LOOKASIDE],B,Z
c2a0: 2c 4e 29 20 77 68 65 72 65 0a 2a 2a 20 20 20 20 ,N) where.**
c2b0: 20 20 20 20 20 20 44 20 69 73 20 61 6e 20 6f 70 D is an op
c2c0: 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e en [database con
c2d0: 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5a 20 61 nection] and Z a
c2e0: 6e 64 20 4e 20 61 72 65 20 70 6f 73 69 74 69 76 nd N are positiv
c2f0: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e e.** in
c300: 74 65 67 65 72 73 20 61 6e 64 20 42 20 69 73 20 tegers and B is
c310: 61 6e 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 an aligned buffe
c320: 72 20 61 74 20 6c 65 61 73 74 20 5a 2a 4e 20 62 r at least Z*N b
c330: 79 74 65 73 20 69 6e 20 73 69 7a 65 0a 2a 2a 20 ytes in size.**
c340: 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 63 shall c
c350: 61 75 73 65 20 74 68 65 20 5b 6c 6f 6f 6b 61 73 ause the [lookas
c360: 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ide memory alloc
c370: 61 74 6f 72 5d 20 66 6f 72 20 44 20 74 6f 20 75 ator] for D to u
c380: 73 65 20 62 75 66 66 65 72 20 42 20 0a 2a 2a 20 se buffer B .**
c390: 20 20 20 20 20 20 20 20 20 77 69 74 68 20 4e 20 with N
c3a0: 73 6c 6f 74 73 20 6f 66 20 5a 20 62 79 74 65 73 slots of Z bytes
c3b0: 20 65 61 63 68 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 each..**.** {H1
c3c0: 34 32 31 32 7d 20 41 20 73 75 63 63 65 73 73 66 4212} A successf
c3d0: 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 20 ul call to .**
c3e0: 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
c3f0: 5f 64 62 5f 63 6f 6e 66 69 67 5d 28 44 2c 5b 53 _db_config](D,[S
c400: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c QLITE_DBCONFIG_L
c410: 4f 4f 4b 41 53 49 44 45 5d 2c 42 2c 5a 2c 4e 29 OOKASIDE],B,Z,N)
c420: 20 77 68 65 72 65 0a 2a 2a 20 20 20 20 20 20 20 where.**
c430: 20 20 20 44 20 69 73 20 61 6e 20 6f 70 65 6e 20 D is an open
c440: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
c450: 74 69 6f 6e 5d 20 61 6e 64 20 5a 20 61 6e 64 20 tion] and Z and
c460: 4e 20 61 72 65 20 70 6f 73 69 74 69 76 65 0a 2a N are positive.*
c470: 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 67 * integ
c480: 65 72 73 20 61 6e 64 20 42 20 69 73 20 4e 55 4c ers and B is NUL
c490: 4c 20 70 6f 69 6e 74 65 72 20 73 68 61 6c 6c 20 L pointer shall
c4a0: 63 61 75 73 65 20 74 68 65 0a 2a 2a 20 20 20 20 cause the.**
c4b0: 20 20 20 20 20 20 5b 6c 6f 6f 6b 61 73 69 64 65 [lookaside
c4c0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
c4d0: 72 5d 20 66 6f 72 20 44 20 74 6f 20 61 20 6f 62 r] for D to a ob
c4e0: 74 61 69 6e 20 5a 2a 4e 20 62 79 74 65 20 62 75 tain Z*N byte bu
c4f0: 66 66 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 ffer.**
c500: 20 66 72 6f 6d 20 74 68 65 20 70 72 69 6d 61 72 from the primar
c510: 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 y memory allocat
c520: 6f 72 20 61 6e 64 20 75 73 65 20 74 68 61 74 20 or and use that
c530: 62 75 66 66 65 72 0a 2a 2a 20 20 20 20 20 20 20 buffer.**
c540: 20 20 20 77 69 74 68 20 4e 20 6c 6f 6f 6b 61 73 with N lookas
c550: 69 64 65 20 73 6c 6f 74 73 20 6f 66 20 5a 20 62 ide slots of Z b
c560: 79 74 65 73 20 65 61 63 68 2e 0a 2a 2a 0a 2a 2a ytes each..**.**
c570: 20 7b 48 31 34 32 31 35 7d 20 41 20 73 75 63 63 {H14215} A succ
c580: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 0a essful call to .
c590: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
c5a0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 5d 28 ite3_db_config](
c5b0: 44 2c 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 D,[SQLITE_DBCONF
c5c0: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 42 2c IG_LOOKASIDE],B,
c5d0: 5a 2c 4e 29 20 77 68 65 72 65 0a 2a 2a 20 20 20 Z,N) where.**
c5e0: 20 20 20 20 20 20 20 44 20 69 73 20 61 6e 20 6f D is an o
c5f0: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f pen [database co
c600: 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5a 20 nnection] and Z
c610: 61 6e 64 20 4e 20 61 72 65 20 7a 65 72 6f 20 73 and N are zero s
c620: 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 hall.**
c630: 20 64 69 73 61 62 6c 65 20 74 68 65 20 5b 6c 6f disable the [lo
c640: 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 okaside memory a
c650: 6c 6c 6f 63 61 74 6f 72 5d 20 66 6f 72 20 44 2e llocator] for D.
c660: 0a 2a 2a 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 .**.**.*/.SQLITE
c670: 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e _EXPERIMENTAL in
c680: 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e t sqlite3_db_con
c690: 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e fig(sqlite3*, in
c6a0: 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a t op, ...);../*.
c6b0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d ** CAPI3REF: Mem
c6c0: 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 ory Allocation R
c6d0: 6f 75 74 69 6e 65 73 20 7b 48 31 30 31 35 35 7d outines {H10155}
c6e0: 20 3c 53 32 30 31 32 30 3e 0a 2a 2a 20 45 58 50 <S20120>.** EXP
c6f0: 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 ERIMENTAL.**.**
c700: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 An instance of t
c710: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e his object defin
c720: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 es the interface
c730: 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a between SQLite.
c740: 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c ** and low-level
c750: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
c760: 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a on routines..**.
c770: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 ** This object i
c780: 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f s used in only o
c790: 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 ne place in the
c7a0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
c7b0: 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 ..** A pointer t
c7c0: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 o an instance of
c7d0: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 this object is
c7e0: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a the argument to.
c7f0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ** [sqlite3_conf
c800: 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 ig()] when the c
c810: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
c820: 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 ion is.** [SQLIT
c830: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d E_CONFIG_MALLOC]
c840: 2e 20 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 . By creating a
c850: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
c860: 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 is object.** and
c870: 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b passing it to [
c880: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
c890: 5d 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 ] during configu
c8a0: 72 61 74 69 6f 6e 2c 20 61 6e 0a 2a 2a 20 61 70 ration, an.** ap
c8b0: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 plication can sp
c8c0: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 ecify an alterna
c8d0: 74 69 76 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f tive memory allo
c8e0: 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d cation subsystem
c8f0: 0a 2a 2a 20 66 6f 72 20 53 51 4c 69 74 65 20 74 .** for SQLite t
c900: 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 o use for all of
c910: 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d its dynamic mem
c920: 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a ory needs..**.**
c930: 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 Note that SQLit
c940: 65 20 63 6f 6d 65 73 20 77 69 74 68 20 61 20 62 e comes with a b
c950: 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 uilt-in memory a
c960: 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 69 73 llocator that is
c970: 0a 2a 2a 20 70 65 72 66 65 63 74 6c 79 20 61 64 .** perfectly ad
c980: 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f equate for the o
c990: 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f verwhelming majo
c9a0: 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 rity of applicat
c9b0: 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 ions.** and that
c9c0: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 this object is
c9d0: 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 only useful to a
c9e0: 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f tiny minority o
c9f0: 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a f applications.*
ca00: 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a * with specializ
ca10: 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ed memory alloca
ca20: 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 tion requirement
ca30: 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 s. This object
ca40: 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 is.** also used
ca50: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f during testing o
ca60: 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 f SQLite in orde
ca70: 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 r to specify an
ca80: 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d alternative.** m
ca90: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 emory allocator
caa0: 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d that simulates m
cab0: 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d emory out-of-mem
cac0: 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 ory conditions i
cad0: 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 n.** order to ve
cae0: 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 rify that SQLite
caf0: 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 recovers gracef
cb00: 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a ully from such.*
cb10: 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a * conditions..**
cb20: 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c .** The xMalloc,
cb30: 20 78 46 72 65 65 2c 20 61 6e 64 20 78 52 65 61 xFree, and xRea
cb40: 6c 6c 6f 63 20 6d 65 74 68 6f 64 73 20 6d 75 73 lloc methods mus
cb50: 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a t work like the.
cb60: 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 66 72 65 ** malloc(), fre
cb70: 65 28 29 2c 20 61 6e 64 20 72 65 61 6c 6c 6f 63 e(), and realloc
cb80: 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f () functions fro
cb90: 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 6c m the standard l
cba0: 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 78 53 ibrary..**.** xS
cbb0: 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 ize should retur
cbc0: 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 n the allocated
cbd0: 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 size of a memory
cbe0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 allocation.** p
cbf0: 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e reviously obtain
cc00: 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 ed from xMalloc
cc10: 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 or xRealloc. Th
cc20: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 e allocated size
cc30: 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 .** is always at
cc40: 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73 least as big as
cc50: 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73 the requested s
cc60: 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c ize but may be l
cc70: 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 arger..**.** The
cc80: 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 xRoundup method
cc90: 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f returns what wo
cca0: 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 uld be the alloc
ccb0: 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 ated size of.**
ccc0: 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 a memory allocat
ccd0: 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 ion given a part
cce0: 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 icular requested
ccf0: 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d size. Most mem
cd00: 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 ory.** allocator
cd10: 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 s round up memor
cd20: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 y allocations at
cd30: 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 least to the ne
cd40: 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f xt multiple.** o
cd50: 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 f 8. Some alloc
cd60: 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 ators round up t
cd70: 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 o a larger multi
cd80: 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 ple or to a powe
cd90: 72 20 6f 66 20 32 2e 0a 2a 2a 0a 2a 2a 20 54 68 r of 2..**.** Th
cda0: 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 e xInit method i
cdb0: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d nitializes the m
cdc0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e emory allocator.
cdd0: 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a (For example,.
cde0: 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f ** it might allo
cdf0: 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 cate any require
ce00: 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 mutexes or init
ce10: 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 ialize internal
ce20: 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 data.** structur
ce30: 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f es. The xShutdo
ce40: 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 wn method is inv
ce50: 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 oked (indirectly
ce60: 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ) by.** [sqlite3
ce70: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 _shutdown()] and
ce80: 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 should dealloca
ce90: 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 te any resources
cea0: 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 acquired.** by
ceb0: 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 xInit. The pApp
cec0: 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 Data pointer is
ced0: 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 used as the only
cee0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
cef0: 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 xInit and xShut
cf00: 64 6f 77 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 down..*/.typedef
cf10: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
cf20: 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 mem_methods sqli
cf30: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b te3_mem_methods;
cf40: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
cf50: 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 mem_methods {.
cf60: 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 void *(*xMalloc)
cf70: 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f (int); /
cf80: 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 * Memory allocat
cf90: 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a ion function */.
cfa0: 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 void (*xFree)(
cfb0: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 void*);
cfc0: 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 /* Free a prior
cfd0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 allocation */.
cfe0: 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f void *(*xReallo
cff0: 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 c)(void*,int);
d000: 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c /* Resize an all
d010: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 ocation */. int
d020: 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 (*xSize)(void*)
d030: 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 ; /* R
d040: 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f eturn the size o
d050: 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 f an allocation
d060: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e */. int (*xRoun
d070: 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 dup)(int);
d080: 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 /* Round up
d090: 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 request size to
d0a0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 allocation size
d0b0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 */. int (*xInit
d0c0: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 )(void*);
d0d0: 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a /* Initializ
d0e0: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c e the memory all
d0f0: 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 ocator */. void
d100: 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f (*xShutdown)(vo
d110: 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 id*); /* De
d120: 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d initialize the m
d130: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 emory allocator
d140: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 */. void *pAppD
d150: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 ata;
d160: 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 /* Argument
d170: 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 to xInit() and x
d180: 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b Shutdown() */.};
d190: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
d1a0: 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 : Configuration
d1b0: 4f 70 74 69 6f 6e 73 20 7b 48 31 30 31 36 30 7d Options {H10160}
d1c0: 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 <S20000>.** EXP
d1d0: 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 ERIMENTAL.**.**
d1e0: 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 These constants
d1f0: 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c are the availabl
d200: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 e integer config
d210: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 uration options
d220: 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 that.** can be p
d230: 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 assed as the fir
d240: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 st argument to t
d250: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 he [sqlite3_conf
d260: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e ig()] interface.
d270: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 .**.** New confi
d280: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 guration options
d290: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e may be added in
d2a0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
d2b0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 of SQLite..** E
d2c0: 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 xisting configur
d2d0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 ation options mi
d2e0: 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e ght be discontin
d2f0: 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f ued. Applicatio
d300: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 ns.** should che
d310: 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f ck the return co
d320: 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 de from [sqlite3
d330: 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 _config()] to ma
d340: 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 ke sure that.**
d350: 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e the call worked.
d360: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 The [sqlite3_c
d370: 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 onfig()] interfa
d380: 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 ce will return a
d390: 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 .** non-zero [er
d3a0: 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 ror code] if a d
d3b0: 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 iscontinued or u
d3c0: 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 nsupported confi
d3d0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a guration option.
d3e0: 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a ** is invoked..*
d3f0: 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 *.** <dl>.** <dt
d400: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 >SQLITE_CONFIG_S
d410: 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e INGLETHREAD</dt>
d420: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 .** <dd>There ar
d430: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 e no arguments t
d440: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 o this option.
d450: 54 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 This option disa
d460: 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 bles.** all mute
d470: 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 xing and puts SQ
d480: 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 Lite into a mode
d490: 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e where it can on
d4a0: 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 ly be used.** by
d4b0: 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 a single thread
d4c0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
d4d0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d >SQLITE_CONFIG_M
d4e0: 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a ULTITHREAD</dt>.
d4f0: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 ** <dd>There are
d500: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f no arguments to
d510: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 this option. T
d520: 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 his option disab
d530: 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 les.** mutexing
d540: 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e on [database con
d550: 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 nection] and [pr
d560: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
d570: 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 ] objects..** Th
d580: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 e application is
d590: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 responsible for
d5a0: 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 serializing acc
d5b0: 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 ess to.** [datab
d5c0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d ase connections]
d5d0: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 and [prepared s
d5e0: 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 tatements]. But
d5f0: 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a other mutexes.*
d600: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f * are enabled so
d610: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c that SQLite wil
d620: 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 l be safe to use
d630: 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 in a multi-thre
d640: 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d aded.** environm
d650: 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e ent as long as n
d660: 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 o two threads at
d670: 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 tempt to use the
d680: 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 same.** [databa
d690: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 se connection] a
d6a0: 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e t the same time.
d6b0: 20 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 See the [threa
d6c0: 64 69 6e 67 20 6d 6f 64 65 5d 0a 2a 2a 20 64 6f ding mode].** do
d6d0: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 cumentation for
d6e0: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 additional infor
d6f0: 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a mation.</dd>.**.
d700: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ** <dt>SQLITE_CO
d710: 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c NFIG_SERIALIZED<
d720: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 /dt>.** <dd>Ther
d730: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e e are no argumen
d740: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f ts to this optio
d750: 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 n. This option
d760: 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d enables.** all m
d770: 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 utexes including
d780: 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a the recursive.*
d790: 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 * mutexes on [da
d7a0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
d7b0: 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 n] and [prepared
d7c0: 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 statement] obje
d7d0: 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 cts..** In this
d7e0: 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74 mode (which is t
d7f0: 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 he default when
d800: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
d810: 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 ed with.** [SQLI
d820: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d TE_THREADSAFE=1]
d830: 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 ) the SQLite lib
d840: 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 rary will itself
d850: 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 serialize acces
d860: 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 s.** to [databas
d870: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 e connections] a
d880: 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 nd [prepared sta
d890: 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 tements] so that
d8a0: 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 the.** applicat
d8b0: 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 ion is free to u
d8c0: 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 se the same [dat
d8d0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
d8e0: 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 ] or the.** same
d8f0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
d900: 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 ment] in differe
d910: 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68 nt threads at th
d920: 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 e same time..**
d930: 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 See the [threadi
d940: 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e ng mode] documen
d950: 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 tation for addit
d960: 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f ional informatio
d970: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 n.</dd>.**.** <d
d980: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
d990: 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c MALLOC</dt>.** <
d9a0: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 dd>This option t
d9b0: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
d9c0: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 gument which is
d9d0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a a pointer to an.
d9e0: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 ** instance of t
d9f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f he [sqlite3_mem_
da00: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 methods] structu
da10: 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e re. The argumen
da20: 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 t specifies.** a
da30: 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c lternative low-l
da40: 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f evel memory allo
da50: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 cation routines
da60: 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c to be used in pl
da70: 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 ace of.** the me
da80: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
da90: 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 routines built i
daa0: 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e nto SQLite.</dd>
dab0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
dac0: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c E_CONFIG_GETMALL
dad0: 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 OC</dt>.** <dd>T
dae0: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
daf0: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
db00: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f nt which is a po
db10: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 inter to an.** i
db20: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b nstance of the [
db30: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
db40: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 ods] structure.
db50: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 The [sqlite3_me
db60: 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 m_methods].** st
db70: 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 ructure is fille
db80: 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 d with the curre
db90: 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d ntly defined mem
dba0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
dbb0: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 outines..** This
dbc0: 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 option can be u
dbd0: 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 sed to overload
dbe0: 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f the default memo
dbf0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a ry allocation.**
dc00: 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 routines with a
dc10: 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 wrapper that si
dc20: 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 mulations memory
dc30: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c allocation fail
dc40: 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 ure or.** tracks
dc50: 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 memory usage, f
dc60: 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e or example.</dd>
dc70: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
dc80: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 E_CONFIG_MEMSTAT
dc90: 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 US</dt>.** <dd>T
dca0: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
dcb0: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
dcc0: 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e of type int, in
dcd0: 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a terpreted as a .
dce0: 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 ** boolean, whic
dcf0: 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 h enables or dis
dd00: 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 ables the collec
dd10: 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 tion of memory a
dd20: 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 llocation .** st
dd30: 61 74 69 73 74 69 63 73 2e 20 57 68 65 6e 20 64 atistics. When d
dd40: 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c isabled, the fol
dd50: 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e lowing SQLite in
dd60: 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 terfaces become
dd70: 0a 2a 2a 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f .** non-operatio
dd80: 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a nal:.** <ul>.*
dd90: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 * <li> [sqlite
dda0: 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 3_memory_used()]
ddb0: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 .** <li> [sqli
ddc0: 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 te3_memory_highw
ddd0: 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 ater()].** <li
dde0: 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f > [sqlite3_soft_
ddf0: 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a heap_limit()].**
de00: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 <li> [sqlite3
de10: 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 _status()].**
de20: 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a </ul>.** </dd>.*
de30: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
de40: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f CONFIG_SCRATCH</
de50: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
de60: 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 option specifies
de70: 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 a static memory
de80: 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c buffer that SQL
de90: 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a ite can use for.
dea0: 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 ** scratch memor
deb0: 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68 y. There are th
dec0: 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 ree arguments:
ded0: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 A pointer to the
dee0: 20 6d 65 6d 6f 72 79 2c 20 74 68 65 0a 2a 2a 20 memory, the.**
def0: 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 size of each scr
df00: 61 74 63 68 20 62 75 66 66 65 72 20 28 73 7a 29 atch buffer (sz)
df10: 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 , and the number
df20: 20 6f 66 20 62 75 66 66 65 72 73 20 28 4e 29 2e of buffers (N).
df30: 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 The sz.** argu
df40: 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d ment must be a m
df50: 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 20 54 ultiple of 16. T
df60: 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 he sz parameter
df70: 73 68 6f 75 6c 64 20 62 65 20 61 20 66 65 77 20 should be a few
df80: 62 79 74 65 73 0a 2a 2a 20 6c 61 72 67 65 72 20 bytes.** larger
df90: 74 68 61 6e 20 74 68 65 20 61 63 74 75 61 6c 20 than the actual
dfa0: 73 63 72 61 74 63 68 20 73 70 61 63 65 20 72 65 scratch space re
dfb0: 71 75 69 72 65 64 20 64 75 65 20 69 6e 74 65 72 quired due inter
dfc0: 6e 61 6c 20 6f 76 65 72 68 65 61 64 2e 0a 2a 2a nal overhead..**
dfd0: 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 The first.** ar
dfe0: 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f gument should po
dff0: 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 int to an alloca
e000: 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 tion of at least
e010: 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d sz*N bytes of m
e020: 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 emory..** SQLite
e030: 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 will use no mor
e040: 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 e than one scrat
e050: 63 68 20 62 75 66 66 65 72 20 61 74 20 6f 6e 63 ch buffer at onc
e060: 65 20 70 65 72 20 74 68 72 65 61 64 2c 20 73 6f e per thread, so
e070: 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 .** N should be
e080: 73 65 74 20 74 6f 20 74 68 65 20 65 78 70 65 63 set to the expec
e090: 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 ted maximum numb
e0a0: 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 20 20 er of threads.
e0b0: 54 68 65 20 73 7a 0a 2a 2a 20 70 61 72 61 6d 65 The sz.** parame
e0c0: 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 36 20 ter should be 6
e0d0: 74 69 6d 65 73 20 74 68 65 20 73 69 7a 65 20 6f times the size o
e0e0: 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 f the largest da
e0f0: 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 tabase page size
e100: 2e 0a 2a 2a 20 53 63 72 61 74 63 68 20 62 75 66 ..** Scratch buf
e110: 66 65 72 73 20 61 72 65 20 75 73 65 64 20 61 73 fers are used as
e120: 20 70 61 72 74 20 6f 66 20 74 68 65 20 62 74 72 part of the btr
e130: 65 65 20 62 61 6c 61 6e 63 65 20 6f 70 65 72 61 ee balance opera
e140: 74 69 6f 6e 2e 20 20 49 66 0a 2a 2a 20 54 68 65 tion. If.** The
e150: 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65 72 20 btree balancer
e160: 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c needs additional
e170: 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 memory beyond w
e180: 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 hat is provided
e190: 62 79 0a 2a 2a 20 73 63 72 61 74 63 68 20 62 75 by.** scratch bu
e1a0: 66 66 65 72 73 20 6f 72 20 69 66 20 6e 6f 20 73 ffers or if no s
e1b0: 63 72 61 74 63 68 20 62 75 66 66 65 72 20 73 70 cratch buffer sp
e1c0: 61 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64 ace is specified
e1d0: 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a , then SQLite.**
e1e0: 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 goes to [sqlite
e1f0: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 74 6f 20 6f 3_malloc()] to o
e200: 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 btain the memory
e210: 20 69 74 20 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a it needs.</dd>.
e220: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
e230: 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 _CONFIG_PAGECACH
e240: 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 E</dt>.** <dd>Th
e250: 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 is option specif
e260: 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d ies a static mem
e270: 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 ory buffer that
e280: 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 SQLite can use f
e290: 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 or.** the databa
e2a0: 73 65 20 70 61 67 65 20 63 61 63 68 65 2e 20 20 se page cache.
e2b0: 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 There are three
e2c0: 61 72 67 75 6d 65 6e 74 73 3a 20 41 20 70 6f 69 arguments: A poi
e2d0: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 6d nter to the.** m
e2e0: 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 emory, the size
e2f0: 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66 of each page buf
e300: 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 fer (sz), and th
e310: 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 e number of page
e320: 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a s (N)..** The sz
e330: 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 argument must b
e340: 65 20 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f e a power of two
e350: 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 between 512 and
e360: 20 33 32 37 36 38 2e 20 20 54 68 65 20 66 69 72 32768. The fir
e370: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 st.** argument s
e380: 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 hould point to a
e390: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 n allocation of
e3a0: 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 at least sz*N by
e3b0: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a tes of memory..*
e3c0: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 * SQLite will us
e3d0: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f e the memory pro
e3e0: 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72 vided by the fir
e3f0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 st argument to s
e400: 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 atisfy its.** me
e410: 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 mory needs for t
e420: 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 he first N pages
e430: 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f that it adds to
e440: 20 63 61 63 68 65 2e 20 20 49 66 20 61 64 64 69 cache. If addi
e450: 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 tional.** page c
e460: 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e ache memory is n
e470: 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 eeded beyond wha
e480: 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 t is provided by
e490: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 this option, th
e4a0: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 en.** SQLite goe
e4b0: 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 s to [sqlite3_ma
e4c0: 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 lloc()] for the
e4d0: 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 additional stora
e4e0: 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 ge space..** The
e4f0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
e500: 6d 69 67 68 74 20 75 73 65 20 6f 6e 65 20 6f 72 might use one or
e510: 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 4e 20 62 more of the N b
e520: 75 66 66 65 72 73 20 74 6f 20 68 6f 6c 64 20 0a uffers to hold .
e530: 2a 2a 20 6d 65 6d 6f 72 79 20 61 63 63 6f 75 6e ** memory accoun
e540: 74 69 6e 67 20 69 6e 66 6f 72 6d 61 74 69 6f 6e ting information
e550: 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 . </dd>.**.** <d
e560: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
e570: 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 HEAP</dt>.** <dd
e580: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 >This option spe
e590: 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 cifies a static
e5a0: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 memory buffer th
e5b0: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 at SQLite will u
e5c0: 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 se.** for all of
e5d0: 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d its dynamic mem
e5e0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e ory allocation n
e5f0: 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 eeds beyond thos
e600: 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f e provided.** fo
e610: 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e r by [SQLITE_CON
e620: 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 FIG_SCRATCH] and
e630: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
e640: 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 PAGECACHE]..** T
e650: 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 here are three a
e660: 72 67 75 6d 65 6e 74 73 3a 20 41 20 70 6f 69 6e rguments: A poin
e670: 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 ter to the memor
e680: 79 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 y, the number of
e690: 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 .** bytes in the
e6a0: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 memory buffer,
e6b0: 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 and the minimum
e6c0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e allocation size.
e6d0: 20 20 49 66 0a 2a 2a 20 74 68 65 20 66 69 72 73 If.** the firs
e6e0: 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d t pointer (the m
e6f0: 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 emory pointer) i
e700: 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c s NULL, then SQL
e710: 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 ite reverts.** t
e720: 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 o using its defa
e730: 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ult memory alloc
e740: 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d ator (the system
e750: 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d malloc() implem
e760: 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e entation),.** un
e770: 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 doing any prior
e780: 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 invocation of [S
e790: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c QLITE_CONFIG_MAL
e7a0: 4c 4f 43 5d 2e 20 20 49 66 20 74 68 65 0a 2a 2a LOC]. If the.**
e7b0: 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 memory pointer
e7c0: 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 is not NULL and
e7d0: 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 either [SQLITE_E
e7e0: 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f NABLE_MEMSYS3] o
e7f0: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 r.** [SQLITE_ENA
e800: 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 BLE_MEMSYS5] are
e810: 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 defined, then t
e820: 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d he alternative m
e830: 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 emory.** allocat
e840: 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f or is engaged to
e850: 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 handle all of S
e860: 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c QLites memory al
e870: 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 3c location needs.<
e880: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
e890: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 QLITE_CONFIG_MUT
e8a0: 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 EX</dt>.** <dd>T
e8b0: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
e8c0: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
e8d0: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f nt which is a po
e8e0: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 inter to an.** i
e8f0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b nstance of the [
e900: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 sqlite3_mutex_me
e910: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 thods] structure
e920: 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 . The argument
e930: 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 specifies.** alt
e940: 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 ernative low-lev
e950: 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 el mutex routine
e960: 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 s to be used in
e970: 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 place.** the mut
e980: 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c ex routines buil
e990: 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f t into SQLite.</
e9a0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
e9b0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
e9c0: 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 UTEX</dt>.** <dd
e9d0: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b >This option tak
e9e0: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
e9f0: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 ment which is a
ea00: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a pointer to an.**
ea10: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 instance of the
ea20: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
ea30: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 methods] structu
ea40: 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c re. The.** [sql
ea50: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
ea60: 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 ds].** structure
ea70: 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 is filled with
ea80: 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 the currently de
ea90: 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 fined mutex rout
eaa0: 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 ines..** This op
eab0: 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 tion can be used
eac0: 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 to overload the
ead0: 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 default mutex a
eae0: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 llocation.** rou
eaf0: 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 tines with a wra
eb00: 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 pper used to tra
eb10: 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 ck mutex usage f
eb20: 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a or performance.*
eb30: 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 * profiling or t
eb40: 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d esting, for exam
eb50: 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ple.</dd>.**.**
eb60: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
eb70: 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e G_LOOKASIDE</dt>
eb80: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 .** <dd>This opt
eb90: 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 ion takes two ar
eba0: 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 guments that det
ebb0: 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 ermine the defau
ebc0: 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c lt.** memory all
ebd0: 63 61 74 69 6f 6e 20 6c 6f 6f 6b 61 73 69 64 65 cation lookaside
ebe0: 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e 20 20 optimization.
ebf0: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
ec00: 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a nt is the.** siz
ec10: 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 e of each lookas
ec20: 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 ide buffer slot
ec30: 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 and the second i
ec40: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a s the number of.
ec50: 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 ** slots allocat
ec60: 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 ed to each datab
ec70: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 3c ase connection.<
ec80: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e /dd>.**.** </dl>
ec90: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
eca0: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 TE_CONFIG_SINGLE
ecb0: 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 THREAD 1 /* ni
ecc0: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c l */.#define SQL
ecd0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 ITE_CONFIG_MULTI
ece0: 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e THREAD 2 /* n
ecf0: 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 il */.#define SQ
ed00: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 LITE_CONFIG_SERI
ed10: 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 ALIZED 3 /*
ed20: 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nil */.#define S
ed30: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c QLITE_CONFIG_MAL
ed40: 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a LOC 4 /*
ed50: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 sqlite3_mem_met
ed60: 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 hods* */.#define
ed70: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 SQLITE_CONFIG_G
ed80: 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 ETMALLOC 5
ed90: 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d /* sqlite3_mem_m
eda0: 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 ethods* */.#defi
edb0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
edc0: 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 _SCRATCH 6
edd0: 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 /* void*, int
ede0: 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 sz, int N */.#de
edf0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
ee00: 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 IG_PAGECACHE
ee10: 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 7 /* void*, in
ee20: 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 t sz, int N */.#
ee30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
ee40: 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 NFIG_HEAP
ee50: 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 8 /* void*,
ee60: 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d int nByte, int m
ee70: 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 in */.#define SQ
ee80: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 LITE_CONFIG_MEMS
ee90: 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 TATUS 9 /*
eea0: 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 boolean */.#defi
eeb0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
eec0: 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 _MUTEX 10
eed0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 /* sqlite3_mut
eee0: 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 ex_methods* */.#
eef0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
ef00: 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 NFIG_GETMUTEX
ef10: 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 11 /* sqlite3
ef20: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 _mutex_methods*
ef30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
ef40: 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c E_CONFIG_CHUNKAL
ef50: 4c 4f 43 20 20 20 31 32 20 20 2f 2a 20 69 6e 74 LOC 12 /* int
ef60: 20 74 68 72 65 73 68 6f 6c 64 20 2a 2f 0a 23 64 threshold */.#d
ef70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
ef80: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 FIG_LOOKASIDE
ef90: 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 13 /* int int
efa0: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
efb0: 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f EF: Configuratio
efc0: 6e 20 4f 70 74 69 6f 6e 73 20 7b 48 31 30 31 37 n Options {H1017
efd0: 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 0} <S20000>.** E
efe0: 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a XPERIMENTAL.**.*
eff0: 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 * These constant
f000: 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 s are the availa
f010: 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 ble integer conf
f020: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
f030: 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 s that.** can be
f040: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 passed as the s
f050: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 econd argument t
f060: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 o the [sqlite3_d
f070: 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 b_config()] inte
f080: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 rface..**.** New
f090: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
f0a0: 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 ptions may be ad
f0b0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
f0c0: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
f0d0: 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f ..** Existing co
f0e0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
f0f0: 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 ons might be dis
f100: 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c continued. Appl
f110: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 ications.** shou
f120: 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 ld check the ret
f130: 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 urn code from [s
f140: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
f150: 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 ()] to make sure
f160: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c that.** the cal
f170: 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b l worked. The [
f180: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
f190: 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 g()] interface w
f1a0: 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 ill return a.**
f1b0: 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 non-zero [error
f1c0: 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f code] if a disco
f1d0: 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 ntinued or unsup
f1e0: 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 ported configura
f1f0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 tion option.** i
f200: 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a s invoked..**.**
f210: 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c <dl>.** <dt>SQL
f220: 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
f230: 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c KASIDE</dt>.** <
f240: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 dd>This option t
f250: 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74 akes three addit
f260: 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 ional arguments
f270: 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 that determine t
f280: 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 he .** [lookasid
f290: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
f2a0: 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f or] configuratio
f2b0: 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 n for the [datab
f2c0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e ase connection].
f2d0: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 .** The first ar
f2e0: 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 gument (the thir
f2f0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b d parameter to [
f300: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
f310: 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 g()] is a.** poi
f320: 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 nter to a memory
f330: 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 buffer to use f
f340: 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d or lookaside mem
f350: 6f 72 79 2e 20 20 54 68 65 20 66 69 72 73 74 0a ory. The first.
f360: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 ** argument may
f370: 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 be NULL in which
f380: 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c case SQLite wil
f390: 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 6c l allocate the l
f3a0: 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 62 75 66 66 ookaside.** buff
f3b0: 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 er itself using
f3c0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
f3d0: 29 5d 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 )]. The second
f3e0: 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a argument is the.
f3f0: 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 ** size of each
f400: 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 lookaside buffer
f410: 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 74 68 slot and the th
f420: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ird argument is
f430: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a the number of.**
f440: 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a slots. The siz
f450: 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 e of the buffer
f460: 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 in the first arg
f470: 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 ument must be gr
f480: 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 eater than.** or
f490: 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 equal to the pr
f4a0: 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 oduct of the sec
f4b0: 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 ond and third ar
f4c0: 67 75 6d 65 6e 74 73 2e 3c 2f 64 64 3e 0a 2a 2a guments.</dd>.**
f4d0: 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 .** </dl>.*/.#de
f4e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f fine SQLITE_DBCO
f4f0: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 NFIG_LOOKASIDE
f500: 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 1001 /* void*
f510: 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a int int */.../*
f520: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e .** CAPI3REF: En
f530: 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 able Or Disable
f540: 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 Extended Result
f550: 43 6f 64 65 73 20 7b 48 31 32 32 30 30 7d 20 3c Codes {H12200} <
f560: 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S10700>.**.** Th
f570: 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 e sqlite3_extend
f580: 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 ed_result_codes(
f590: 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 ) routine enable
f5a0: 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 s or disables th
f5b0: 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 e.** [extended r
f5c0: 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 esult codes] fea
f5d0: 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 ture of SQLite.
f5e0: 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 The extended res
f5f0: 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 ult.** codes are
f600: 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 disabled by def
f610: 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 ault for histori
f620: 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 cal compatibilit
f630: 79 20 63 6f 6e 73 69 64 65 72 61 74 69 6f 6e 73 y considerations
f640: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
f650: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 30 TS:.**.** {H1220
f660: 31 7d 20 45 61 63 68 20 6e 65 77 20 5b 64 61 74 1} Each new [dat
f670: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
f680: 5d 20 73 68 61 6c 6c 20 68 61 76 65 20 74 68 65 ] shall have the
f690: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 65 78 .** [ex
f6a0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
f6b0: 64 65 73 5d 20 66 65 61 74 75 72 65 20 64 69 73 des] feature dis
f6c0: 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 abled by default
f6d0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 30 32 7d ..**.** {H12202}
f6e0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 The [sqlite3_ex
f6f0: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f tended_result_co
f700: 64 65 73 28 44 2c 46 29 5d 20 69 6e 74 65 72 66 des(D,F)] interf
f710: 61 63 65 20 73 68 61 6c 6c 20 65 6e 61 62 6c 65 ace shall enable
f720: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 65 78 .** [ex
f730: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
f740: 64 65 73 5d 20 66 6f 72 20 74 68 65 20 20 5b 64 des] for the [d
f750: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
f760: 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 on] D.**
f770: 20 20 69 66 20 74 68 65 20 46 20 70 61 72 61 6d if the F param
f780: 65 74 65 72 20 69 73 20 74 72 75 65 2c 20 6f 72 eter is true, or
f790: 20 64 69 73 61 62 6c 65 20 74 68 65 6d 20 69 66 disable them if
f7a0: 20 46 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2f 0a F is false..*/.
f7b0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 int sqlite3_exte
f7c0: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 nded_result_code
f7d0: 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 s(sqlite3*, int
f7e0: 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 onoff);../*.** C
f7f0: 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e API3REF: Last In
f800: 73 65 72 74 20 52 6f 77 69 64 20 7b 48 31 32 32 sert Rowid {H122
f810: 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 20} <S10700>.**.
f820: 2a 2a 20 45 61 63 68 20 65 6e 74 72 79 20 69 6e ** Each entry in
f830: 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 an SQLite table
f840: 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 has a unique 64
f850: 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 -bit signed.** i
f860: 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 nteger key calle
f870: 64 20 74 68 65 20 22 72 6f 77 69 64 22 2e 20 54 d the "rowid". T
f880: 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 he rowid is alwa
f890: 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 ys available.**
f8a0: 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 as an undeclared
f8b0: 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f column named RO
f8c0: 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f WID, OID, or _RO
f8d0: 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 WID_ as long as
f8e0: 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 those.** names a
f8f0: 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 re not also used
f900: 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 by explicitly d
f910: 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e eclared columns.
f920: 20 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 If.** the table
f930: 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 has a column of
f940: 20 74 79 70 65 20 49 4e 54 45 47 45 52 20 50 52 type INTEGER PR
f950: 49 4d 41 52 59 20 4b 45 59 20 74 68 65 6e 20 74 IMARY KEY then t
f960: 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 hat column.** is
f970: 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 another alias f
f980: 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a or the rowid..**
f990: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
f9a0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 72 6f 77 returns the row
f9b0: 69 64 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 id of the most r
f9c0: 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 ecent.** success
f9d0: 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 ful [INSERT] int
f9e0: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 o the database f
f9f0: 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73 rom the [databas
fa00: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a e connection].**
fa10: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
fa20: 67 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f 20 73 gument. If no s
fa30: 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 uccessful [INSER
fa40: 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 T]s.** have ever
fa50: 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 occurred on tha
fa60: 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 t database conne
fa70: 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 ction, zero is r
fa80: 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 eturned..**.** I
fa90: 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 f an [INSERT] oc
faa0: 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 curs within a tr
fab0: 69 67 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20 igger, then the
fac0: 72 6f 77 69 64 20 6f 66 20 74 68 65 20 69 6e 73 rowid of the ins
fad0: 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 69 73 20 erted.** row is
fae0: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 returned by this
faf0: 20 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 routine as long
fb00: 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 as the trigger
fb10: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 is running..** B
fb20: 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 ut once the trig
fb30: 67 65 72 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 ger terminates,
fb40: 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
fb50: 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 ed by this routi
fb60: 6e 65 0a 2a 2a 20 72 65 76 65 72 74 73 20 74 6f ne.** reverts to
fb70: 20 74 68 65 20 6c 61 73 74 20 76 61 6c 75 65 20 the last value
fb80: 69 6e 73 65 72 74 65 64 20 62 65 66 6f 72 65 20 inserted before
fb90: 74 68 65 20 74 72 69 67 67 65 72 20 66 69 72 65 the trigger fire
fba0: 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 49 4e 53 d..**.** An [INS
fbb0: 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 ERT] that fails
fbc0: 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 due to a constra
fbd0: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 int violation is
fbe0: 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 not a.** succes
fbf0: 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e sful [INSERT] an
fc00: 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 d does not chang
fc10: 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 e the value retu
fc20: 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 rned by this.**
fc30: 72 6f 75 74 69 6e 65 2e 20 20 54 68 75 73 20 49 routine. Thus I
fc40: 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 NSERT OR FAIL, I
fc50: 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c NSERT OR IGNORE,
fc60: 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 INSERT OR ROLLB
fc70: 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 ACK,.** and INSE
fc80: 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 RT OR ABORT make
fc90: 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 no changes to t
fca0: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
fcb0: 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 of this.** routi
fcc0: 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e ne when their in
fcd0: 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 sertion fails.
fce0: 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 When INSERT OR R
fcf0: 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e EPLACE.** encoun
fd00: 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e ters a constrain
fd10: 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 t violation, it
fd20: 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 does not fail.
fd30: 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f The.** INSERT co
fd40: 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c ntinues to compl
fd50: 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 etion after dele
fd60: 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 ting rows that c
fd70: 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e aused.** the con
fd80: 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 straint problem
fd90: 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 so INSERT OR REP
fda0: 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 LACE will always
fdb0: 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 change.** the r
fdc0: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 eturn value of t
fdd0: 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a his interface..*
fde0: 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 *.** For the pur
fdf0: 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f poses of this ro
fe00: 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 utine, an [INSER
fe10: 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 T] is considered
fe20: 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 to.** be succes
fe30: 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 sful even if it
fe40: 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 is subsequently
fe50: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a rolled back..**.
fe60: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
fe70: 2a 0a 2a 2a 20 7b 48 31 32 32 32 31 7d 20 54 68 *.** {H12221} Th
fe80: 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f e [sqlite3_last_
fe90: 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 insert_rowid()]
fea0: 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 function shall r
feb0: 65 74 75 72 6e 20 74 68 65 20 72 6f 77 69 64 0a eturn the rowid.
fec0: 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 ** of t
fed0: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 he most recent s
fee0: 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 uccessful [INSER
fef0: 54 5d 20 70 65 72 66 6f 72 6d 65 64 20 6f 6e 20 T] performed on
ff00: 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 the same.**
ff10: 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 [database c
ff20: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 77 onnection] and w
ff30: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 6f ithin the same o
ff40: 72 20 68 69 67 68 65 72 20 6c 65 76 65 6c 0a 2a r higher level.*
ff50: 2a 20 20 20 20 20 20 20 20 20 20 74 72 69 67 67 * trigg
ff60: 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20 7a er context, or z
ff70: 65 72 6f 20 69 66 20 74 68 65 72 65 20 68 61 76 ero if there hav
ff80: 65 20 62 65 65 6e 20 6e 6f 20 71 75 61 6c 69 66 e been no qualif
ff90: 79 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 ying.**
ffa0: 20 5b 49 4e 53 45 52 54 5d 20 73 74 61 74 65 6d [INSERT] statem
ffb0: 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 ents..**.** {H12
ffc0: 32 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 223} The [sqlite
ffd0: 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 3_last_insert_ro
ffe0: 77 69 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 wid()] function
fff0: 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 shall return the
10000 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 61 6d .** sam
10010 65 20 76 61 6c 75 65 20 77 68 65 6e 20 63 61 6c e value when cal
10020 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d led from the sam
10030 65 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 e trigger contex
10040 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6d t.** im
10050 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65 mediately before
10060 20 61 6e 64 20 61 66 74 65 72 20 61 20 5b 52 4f and after a [RO
10070 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 41 LLBACK]..**.** A
10080 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a SSUMPTIONS:.**.*
10090 2a 20 7b 41 31 32 32 33 32 7d 20 49 66 20 61 20 * {A12232} If a
100a0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 separate thread
100b0 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b performs a new [
100c0 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 INSERT] on the s
100d0 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ame.**
100e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
100f0 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 ion while the [s
10100 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 qlite3_last_inse
10110 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 20 rt_rowid()].**
10120 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e function
10130 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 is running and
10140 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 thus changes the
10150 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77 last insert row
10160 69 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 id,.**
10170 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 then the value r
10180 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 eturned by [sqli
10190 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f te3_last_insert_
101a0 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 20 rowid()] is.**
101b0 20 20 20 20 20 20 20 20 75 6e 70 72 65 64 69 63 unpredic
101c0 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 table and might
101d0 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 not equal either
101e0 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 the old or the
101f0 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 new.**
10200 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69 last insert rowi
10210 64 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e d..*/.sqlite3_in
10220 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 t64 sqlite3_last
10230 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 _insert_rowid(sq
10240 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 lite3*);../*.**
10250 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 CAPI3REF: Count
10260 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f The Number Of Ro
10270 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 48 31 32 ws Modified {H12
10280 32 34 30 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 240} <S10600>.**
10290 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f .** This functio
102a0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 n returns the nu
102b0 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 mber of database
102c0 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 rows that were
102d0 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e changed.** or in
102e0 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 serted or delete
102f0 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 d by the most re
10300 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 cently completed
10310 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a SQL statement.*
10320 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 * on the [databa
10330 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 se connection] s
10340 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 pecified by the
10350 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e first parameter.
10360 0a 2a 2a 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 .** Only changes
10370 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63 74 that are direct
10380 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79 20 ly specified by
10390 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 the [INSERT], [U
103a0 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 PDATE],.** or [D
103b0 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 ELETE] statement
103c0 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 are counted. A
103d0 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 uxiliary changes
103e0 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 caused by.** tr
103f0 69 67 67 65 72 73 20 61 72 65 20 6e 6f 74 20 63 iggers are not c
10400 6f 75 6e 74 65 64 2e 20 55 73 65 20 74 68 65 20 ounted. Use the
10410 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 [sqlite3_total_c
10420 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 hanges()] functi
10430 6f 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 on.** to find th
10440 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f e total number o
10450 66 20 63 68 61 6e 67 65 73 20 69 6e 63 6c 75 64 f changes includ
10460 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 ing changes caus
10470 65 64 20 62 79 20 74 72 69 67 67 65 72 73 2e 0a ed by triggers..
10480 2a 2a 0a 2a 2a 20 41 20 22 72 6f 77 20 63 68 61 **.** A "row cha
10490 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 nge" is a change
104a0 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 to a single row
104b0 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 of a single tab
104c0 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 le.** caused by
104d0 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 an INSERT, DELET
104e0 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 E, or UPDATE sta
104f0 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 tement. Rows th
10500 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 at.** are change
10510 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74 d as side effect
10520 73 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e s of REPLACE con
10530 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 straint resoluti
10540 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c on,.** rollback,
10550 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e ABORT processin
10560 67 2c 20 44 52 4f 50 20 54 41 42 4c 45 2c 20 6f g, DROP TABLE, o
10570 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a r by any other.*
10580 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 * mechanisms do
10590 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 not count as dir
105a0 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e ect row changes.
105b0 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 .**.** A "trigge
105c0 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 r context" is a
105d0 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 scope of executi
105e0 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 on that begins a
105f0 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 nd.** ends with
10600 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 the script of a
10610 74 72 69 67 67 65 72 2e 20 20 4d 6f 73 74 20 53 trigger. Most S
10620 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 QL statements ar
10630 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f e.** evaluated o
10640 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 utside of any tr
10650 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 igger. This is
10660 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a the "top level".
10670 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 ** trigger conte
10680 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 xt. If a trigge
10690 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 r fires from the
106a0 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a top level, a.**
106b0 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e new trigger con
106c0 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 text is entered
106d0 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e for the duration
106e0 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 of that one.**
106f0 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 trigger. Subtri
10700 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62 ggers create sub
10710 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 contexts for the
10720 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a ir duration..**.
10730 2a 2a 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 ** Calling [sqli
10740 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b te3_exec()] or [
10750 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
10760 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 recursively does
10770 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 .** not create a
10780 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e new trigger con
10790 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 text..**.** This
107a0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e function return
107b0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
107c0 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 direct row chang
107d0 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 es in the.** mos
107e0 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c t recent INSERT,
107f0 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 UPDATE, or DELE
10800 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 TE statement wit
10810 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 hin the same.**
10820 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e trigger context.
10830 0a 2a 2a 0a 2a 2a 20 54 68 75 73 2c 20 77 68 65 .**.** Thus, whe
10840 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 n called from th
10850 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 e top level, thi
10860 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 s function retur
10870 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 ns the.** number
10880 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 of changes in t
10890 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 he most recent I
108a0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f NSERT, UPDATE, o
108b0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 r DELETE.** that
108c0 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 also occurred a
108d0 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e t the top level.
108e0 20 20 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 Within the bod
108f0 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a y of a trigger,.
10900 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 ** the sqlite3_c
10910 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 hanges() interfa
10920 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 ce can be called
10930 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d to find the num
10940 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 ber of.** change
10950 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 s in the most re
10960 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 cently completed
10970 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c INSERT, UPDATE,
10980 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 or DELETE.** st
10990 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 atement within t
109a0 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 he body of the s
109b0 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 ame trigger..**
109c0 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d However, the num
109d0 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 ber returned doe
109e0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 s not include ch
109f0 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 anges.** caused
10a00 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73 by subtriggers s
10a10 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 ince those have
10a20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 their own contex
10a30 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 t..**.** SQLite
10a40 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 implements the c
10a50 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46 ommand "DELETE F
10a60 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f ROM table" witho
10a70 75 74 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 ut a WHERE claus
10a80 65 0a 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 e.** by dropping
10a90 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20 and recreating
10aa0 74 68 65 20 74 61 62 6c 65 2e 20 20 44 6f 69 6e the table. Doin
10ab0 67 20 73 6f 20 69 73 20 6d 75 63 68 20 66 61 73 g so is much fas
10ac0 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a ter than going.*
10ad0 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65 * through and de
10ae0 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61 leting individua
10af0 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20 l elements from
10b00 74 68 65 20 74 61 62 6c 65 2e 20 20 42 65 63 61 the table. Beca
10b10 75 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 6f use of this.** o
10b20 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 ptimization, the
10b30 20 64 65 6c 65 74 69 6f 6e 73 20 69 6e 20 22 44 deletions in "D
10b40 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 ELETE FROM table
10b50 22 20 61 72 65 20 6e 6f 74 20 72 6f 77 20 63 68 " are not row ch
10b60 61 6e 67 65 73 20 61 6e 64 0a 2a 2a 20 77 69 6c anges and.** wil
10b70 6c 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65 64 l not be counted
10b80 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f by the sqlite3_
10b90 63 68 61 6e 67 65 73 28 29 20 6f 72 20 5b 73 71 changes() or [sq
10ba0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e lite3_total_chan
10bb0 67 65 73 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 ges()].** functi
10bc0 6f 6e 73 2c 20 72 65 67 61 72 64 6c 65 73 73 20 ons, regardless
10bd0 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 of the number of
10be0 20 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 20 77 elements that w
10bf0 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a ere originally.*
10c00 2a 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 20 * in the table.
10c10 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72 To get an accur
10c20 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 ate count of the
10c30 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 number of rows
10c40 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 deleted, use.**
10c50 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 "DELETE FROM tab
10c60 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e 73 74 le WHERE 1" inst
10c70 65 61 64 2e 20 20 4f 72 20 72 65 63 6f 6d 70 69 ead. Or recompi
10c80 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 le using the.**
10c90 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 55 [SQLITE_OMIT_TRU
10ca0 4e 43 41 54 45 5f 4f 50 54 49 4d 49 5a 41 54 49 NCATE_OPTIMIZATI
10cb0 4f 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 ON] compile-time
10cc0 20 6f 70 74 69 6f 6e 20 74 6f 20 64 69 73 61 62 option to disab
10cd0 6c 65 20 74 68 65 0a 2a 2a 20 6f 70 74 69 6d 69 le the.** optimi
10ce0 7a 61 74 69 6f 6e 20 6f 6e 20 61 6c 6c 20 71 75 zation on all qu
10cf0 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 eries..**.** INV
10d00 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
10d10 48 31 32 32 34 31 7d 20 54 68 65 20 5b 73 71 6c H12241} The [sql
10d20 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 ite3_changes()]
10d30 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 function shall r
10d40 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 eturn the number
10d50 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 of.**
10d60 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 row changes caus
10d70 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 ed by the most r
10d80 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 ecent INSERT, UP
10d90 44 41 54 45 2c 0a 2a 2a 20 20 20 20 20 20 20 20 DATE,.**
10da0 20 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 or DELETE stat
10db0 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 73 61 6d ement on the sam
10dc0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
10dd0 63 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 ction and.**
10de0 20 20 20 20 20 20 77 69 74 68 69 6e 20 74 68 65 within the
10df0 20 73 61 6d 65 20 6f 72 20 68 69 67 68 65 72 20 same or higher
10e00 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c trigger context,
10e10 20 6f 72 20 7a 65 72 6f 20 69 66 20 74 68 65 72 or zero if ther
10e20 65 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 e have.**
10e30 20 20 20 6e 6f 74 20 62 65 65 6e 20 61 6e 79 20 not been any
10e40 71 75 61 6c 69 66 79 69 6e 67 20 72 6f 77 20 63 qualifying row c
10e50 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 hanges..**.** {H
10e60 31 32 32 34 33 7d 20 53 74 61 74 65 6d 65 6e 74 12243} Statement
10e70 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 44 s of the form "D
10e80 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 ELETE FROM table
10e90 6e 61 6d 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a name" with no.**
10ea0 20 20 20 20 20 20 20 20 20 20 57 48 45 52 45 20 WHERE
10eb0 63 6c 61 75 73 65 20 73 68 61 6c 6c 20 63 61 75 clause shall cau
10ec0 73 65 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 se subsequent ca
10ed0 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 lls to.**
10ee0 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e [sqlite3_chan
10ef0 67 65 73 28 29 5d 20 74 6f 20 72 65 74 75 72 6e ges()] to return
10f00 20 7a 65 72 6f 2c 20 72 65 67 61 72 64 6c 65 73 zero, regardles
10f10 73 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 s of the.**
10f20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 72 number of r
10f30 6f 77 73 20 6f 72 69 67 69 6e 61 6c 6c 79 20 69 ows originally i
10f40 6e 20 74 68 65 20 74 61 62 6c 65 2e 0a 2a 2a 0a n the table..**.
10f50 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a ** ASSUMPTIONS:.
10f60 2a 2a 0a 2a 2a 20 7b 41 31 32 32 35 32 7d 20 49 **.** {A12252} I
10f70 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 f a separate thr
10f80 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 ead makes change
10f90 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 s on the same da
10fa0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
10fb0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 n.** wh
10fc0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 ile [sqlite3_cha
10fd0 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 nges()] is runni
10fe0 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 ng then the valu
10ff0 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 e returned.**
11000 20 20 20 20 20 20 20 69 73 20 75 6e 70 72 65 64 is unpred
11010 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 ictable and not
11020 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 meaningful..*/.i
11030 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 nt sqlite3_chang
11040 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f es(sqlite3*);../
11050 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
11060 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 otal Number Of R
11070 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 48 31 ows Modified {H1
11080 32 32 36 30 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2260} <S10600>.*
11090 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 *.** This functi
110a0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e on returns the n
110b0 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 umber of row cha
110c0 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 49 nges caused by I
110d0 4e 53 45 52 54 2c 0a 2a 2a 20 55 50 44 41 54 45 NSERT,.** UPDATE
110e0 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 or DELETE state
110f0 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 ments since the
11100 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
11110 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 tion] was opened
11120 2e 0a 2a 2a 20 54 68 65 20 63 6f 75 6e 74 20 69 ..** The count i
11130 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e ncludes all chan
11140 67 65 73 20 66 72 6f 6d 20 61 6c 6c 20 74 72 69 ges from all tri
11150 67 67 65 72 20 63 6f 6e 74 65 78 74 73 2e 20 20 gger contexts.
11160 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 However,.** the
11170 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 count does not i
11180 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 nclude changes u
11190 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 sed to implement
111a0 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 REPLACE constra
111b0 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c ints,.** do roll
111c0 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 backs or ABORT p
111d0 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 44 52 rocessing, or DR
111e0 4f 50 20 74 61 62 6c 65 20 70 72 6f 63 65 73 73 OP table process
111f0 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 63 68 61 6e ing..** The chan
11200 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 20 ges are counted
11210 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 73 as soon as the s
11220 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 tatement that ma
11230 6b 65 73 20 74 68 65 6d 20 69 73 0a 2a 2a 20 63 kes them is.** c
11240 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 ompleted (when t
11250 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e he statement han
11260 64 6c 65 20 69 73 20 70 61 73 73 65 64 20 74 6f dle is passed to
11270 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
11280 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 )] or.** [sqlite
11290 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 3_finalize()])..
112a0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 **.** SQLite imp
112b0 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d lements the comm
112c0 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d and "DELETE FROM
112d0 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20 table" without
112e0 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a a WHERE clause.*
112f0 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e * by dropping an
11300 64 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 d recreating the
11310 20 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69 table. (This i
11320 73 20 6d 75 63 68 20 66 61 73 74 65 72 20 74 68 s much faster th
11330 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f an going.** thro
11340 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 ugh and deleting
11350 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d individual elem
11360 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74 61 ents from the ta
11370 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f ble.) Because o
11380 66 20 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 f this.** optimi
11390 7a 61 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65 zation, the dele
113a0 74 69 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54 45 tions in "DELETE
113b0 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72 65 FROM table" are
113c0 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65 73 not row changes
113d0 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 and.** will not
113e0 20 62 65 20 63 6f 75 6e 74 65 64 20 62 79 20 74 be counted by t
113f0 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 he sqlite3_chang
11400 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 es() or [sqlite3
11410 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 _total_changes()
11420 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c 20 ].** functions,
11430 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 regardless of th
11440 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d e number of elem
11450 65 6e 74 73 20 74 68 61 74 20 77 65 72 65 20 6f ents that were o
11460 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 riginally.** in
11470 74 68 65 20 74 61 62 6c 65 2e 20 20 54 6f 20 67 the table. To g
11480 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 et an accurate c
11490 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 ount of the numb
114a0 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 er of rows delet
114b0 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 ed, use.** "DELE
114c0 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 TE FROM table WH
114d0 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e 20 ERE 1" instead.
114e0 20 20 4f 72 20 72 65 63 6f 6d 70 69 6c 65 20 75 Or recompile u
114f0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c sing the.** [SQL
11500 49 54 45 5f 4f 4d 49 54 5f 54 52 55 4e 43 41 54 ITE_OMIT_TRUNCAT
11510 45 5f 4f 50 54 49 4d 49 5a 41 54 49 4f 4e 5d 20 E_OPTIMIZATION]
11520 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
11530 69 6f 6e 20 74 6f 20 64 69 73 61 62 6c 65 20 74 ion to disable t
11540 68 65 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 he.** optimizati
11550 6f 6e 20 6f 6e 20 61 6c 6c 20 71 75 65 72 69 65 on on all querie
11560 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 s..**.** See als
11570 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 o the [sqlite3_c
11580 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 hanges()] interf
11590 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 ace..**.** INVAR
115a0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 IANTS:.**.** {H1
115b0 32 32 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 2261} The [sqlit
115c0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
115d0 28 29 5d 20 72 65 74 75 72 6e 73 20 74 68 65 20 ()] returns the
115e0 74 6f 74 61 6c 20 6e 75 6d 62 65 72 0a 2a 2a 20 total number.**
115f0 20 20 20 20 20 20 20 20 20 6f 66 20 72 6f 77 20 of row
11600 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 changes caused b
11610 79 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 y INSERT, UPDATE
11620 2c 20 61 6e 64 2f 6f 72 20 44 45 4c 45 54 45 0a , and/or DELETE.
11630 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 61 74 ** stat
11640 65 6d 65 6e 74 73 20 6f 6e 20 74 68 65 20 73 61 ements on the sa
11650 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e me [database con
11660 6e 65 63 74 69 6f 6e 5d 2c 20 69 6e 20 61 6e 79 nection], in any
11670 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 72 69 .** tri
11680 67 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 73 69 gger context, si
11690 6e 63 65 20 74 68 65 20 64 61 74 61 62 61 73 65 nce the database
116a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 connection was
116b0 63 72 65 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b created..**.** {
116c0 48 31 32 32 36 33 7d 20 53 74 61 74 65 6d 65 6e H12263} Statemen
116d0 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 ts of the form "
116e0 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c DELETE FROM tabl
116f0 65 6e 61 6d 65 22 20 77 69 74 68 20 6e 6f 0a 2a ename" with no.*
11700 2a 20 20 20 20 20 20 20 20 20 20 57 48 45 52 45 * WHERE
11710 20 63 6c 61 75 73 65 20 73 68 61 6c 6c 20 6e 6f clause shall no
11720 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c t change the val
11730 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 ue returned.**
11740 20 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 by [sqli
11750 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
11760 73 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 s()]..**.** ASSU
11770 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b MPTIONS:.**.** {
11780 41 31 32 32 36 34 7d 20 49 66 20 61 20 73 65 70 A12264} If a sep
11790 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b arate thread mak
117a0 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 es changes on th
117b0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 e same database
117c0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 connection.**
117d0 20 20 20 20 20 20 20 77 68 69 6c 65 20 5b 73 71 while [sq
117e0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e lite3_total_chan
117f0 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e ges()] is runnin
11800 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 g then the value
11810 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 .** ret
11820 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 urned is unpredi
11830 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d ctable and not m
11840 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e eaningful..*/.in
11850 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f t sqlite3_total_
11860 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a changes(sqlite3*
11870 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
11880 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 EF: Interrupt A
11890 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 Long-Running Que
118a0 72 79 20 7b 48 31 32 32 37 30 7d 20 3c 53 33 30 ry {H12270} <S30
118b0 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 500>.**.** This
118c0 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 function causes
118d0 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 any pending data
118e0 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 base operation t
118f0 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 o abort and.** r
11900 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 eturn at its ear
11910 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 liest opportunit
11920 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 y. This routine
11930 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 is typically.**
11940 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e called in respon
11950 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 se to a user act
11960 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 ion such as pres
11970 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a sing "Cancel".**
11980 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 or Ctrl-C where
11990 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 the user wants
119a0 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 a long query ope
119b0 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a ration to halt.*
119c0 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a * immediately..*
119d0 2a 0a 2a 2a 20 49 74 20 69 73 20 73 61 66 65 20 *.** It is safe
119e0 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 to call this rou
119f0 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 tine from a thre
11a00 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f ad different fro
11a10 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 m the.** thread
11a20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c that is currentl
11a30 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 y running the da
11a40 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e tabase operation
11a50 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 . But it.** is
11a60 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c not safe to call
11a70 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 this routine wi
11a80 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 th a [database c
11a90 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a onnection] that.
11aa0 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 ** is closed or
11ab0 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f might close befo
11ac0 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 re sqlite3_inter
11ad0 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a rupt() returns..
11ae0 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 53 51 4c 20 **.** If an SQL
11af0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 operation is ver
11b00 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 y nearly finishe
11b10 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 d at the time wh
11b20 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e en.** sqlite3_in
11b30 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c terrupt() is cal
11b40 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 led, then it mig
11b50 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f ht not have an o
11b60 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f pportunity.** to
11b70 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 be interrupted
11b80 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e and might contin
11b90 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e ue to completion
11ba0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f ..**.** An SQL o
11bb0 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 peration that is
11bc0 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c interrupted wil
11bd0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 l return [SQLITE
11be0 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 _INTERRUPT]..**
11bf0 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 If the interrupt
11c00 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e ed SQL operation
11c10 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 is an INSERT, U
11c20 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 PDATE, or DELETE
11c30 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 .** that is insi
11c40 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 de an explicit t
11c50 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e ransaction, then
11c60 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e the entire tran
11c70 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 saction.** will
11c80 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 be rolled back a
11c90 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a utomatically..**
11ca0 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 .** A call to sq
11cb0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
11cc0 29 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 ) has no effect
11cd0 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 on SQL statement
11ce0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 s.** that are st
11cf0 61 72 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 arted after sqli
11d00 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 te3_interrupt()
11d10 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 returns..**.** I
11d20 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
11d30 20 7b 48 31 32 32 37 31 7d 20 54 68 65 20 5b 73 {H12271} The [s
11d40 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
11d50 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 ()] interface wi
11d60 6c 6c 20 66 6f 72 63 65 20 61 6c 6c 20 72 75 6e ll force all run
11d70 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 ning.**
11d80 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
11d90 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
11da0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
11db0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
11dc0 20 20 20 20 20 20 20 20 20 74 6f 20 68 61 6c 74 to halt
11dd0 20 61 66 74 65 72 20 70 72 6f 63 65 73 73 69 6e after processin
11de0 67 20 61 74 20 6d 6f 73 74 20 6f 6e 65 20 61 64 g at most one ad
11df0 64 69 74 69 6f 6e 61 6c 20 72 6f 77 20 6f 66 20 ditional row of
11e00 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 data..**.** {H12
11e10 32 37 32 7d 20 41 6e 79 20 53 51 4c 20 73 74 61 272} Any SQL sta
11e20 74 65 6d 65 6e 74 20 74 68 61 74 20 69 73 20 69 tement that is i
11e30 6e 74 65 72 72 75 70 74 65 64 20 62 79 20 5b 73 nterrupted by [s
11e40 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
11e50 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ()].**
11e60 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c will return [SQL
11e70 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a ITE_INTERRUPT]..
11e80 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e **.** ASSUMPTION
11e90 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 37 39 S:.**.** {A12279
11ea0 7d 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 } If the databas
11eb0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f e connection clo
11ec0 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 ses while [sqlit
11ed0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a e3_interrupt()].
11ee0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 72 ** is r
11ef0 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 unning then bad
11f00 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 things will like
11f10 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f ly happen..*/.vo
11f20 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 id sqlite3_inter
11f30 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a rupt(sqlite3*);.
11f40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
11f50 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e Determine If An
11f60 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 SQL Statement I
11f70 73 20 43 6f 6d 70 6c 65 74 65 20 7b 48 31 30 35 s Complete {H105
11f80 31 30 7d 20 3c 53 37 30 32 30 30 3e 0a 2a 2a 0a 10} <S70200>.**.
11f90 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
11fa0 73 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 s are useful for
11fb0 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e command-line in
11fc0 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 put to determine
11fd0 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 if the.** curre
11fe0 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 ntly entered tex
11ff0 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 t seems to form
12000 63 6f 6d 70 6c 65 74 65 20 61 20 53 51 4c 20 73 complete a SQL s
12010 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 tatement or.** i
12020 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 f additional inp
12030 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 ut is needed bef
12040 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 ore sending the
12050 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c text into.** SQL
12060 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e ite for parsing.
12070 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 These routines
12080 20 72 65 74 75 72 6e 20 74 72 75 65 20 69 66 20 return true if
12090 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 the input string
120a0 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 .** appears to b
120b0 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c e a complete SQL
120c0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 41 20 73 statement. A s
120d0 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 tatement is judg
120e0 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 ed to be.** comp
120f0 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 lete if it ends
12100 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e with a semicolon
12110 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f token and is no
12120 74 20 61 20 66 72 61 67 6d 65 6e 74 20 6f 66 20 t a fragment of
12130 61 0a 2a 2a 20 43 52 45 41 54 45 20 54 52 49 47 a.** CREATE TRIG
12140 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 GER statement.
12150 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 Semicolons that
12160 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 are embedded wit
12170 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 hin.** string li
12180 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 terals or quoted
12190 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 identifier name
121a0 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 s or comments ar
121b0 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e e not.** indepen
121c0 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 dent tokens (the
121d0 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 y are part of th
121e0 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 e token in which
121f0 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 they are.** emb
12200 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 edded) and thus
12210 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 do not count as
12220 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d a statement term
12230 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 inator..**.** Th
12240 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 ese routines do
12250 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 not parse the SQ
12260 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 L statements thu
12270 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 s.** will not de
12280 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c tect syntactical
12290 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c ly incorrect SQL
122a0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
122b0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 31 TS:.**.** {H1051
122c0 31 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 1} A successful
122d0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 5b 73 evaluation of [s
122e0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 qlite3_complete(
122f0 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 )] or.**
12300 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c [sqlite3_compl
12310 65 74 65 31 36 28 29 5d 20 66 75 6e 63 74 69 6f ete16()] functio
12320 6e 73 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 ns shall.**
12330 20 20 20 20 20 72 65 74 75 72 6e 20 61 20 6e 75 return a nu
12340 6d 65 72 69 63 20 31 20 69 66 20 61 6e 64 20 6f meric 1 if and o
12350 6e 6c 79 20 69 66 20 74 68 65 20 6c 61 73 74 20 nly if the last
12360 6e 6f 6e 2d 77 68 69 74 65 73 70 61 63 65 0a 2a non-whitespace.*
12370 2a 20 20 20 20 20 20 20 20 20 20 74 6f 6b 65 6e * token
12380 20 69 6e 20 74 68 65 69 72 20 69 6e 70 75 74 20 in their input
12390 69 73 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 is a semicolon t
123a0 68 61 74 20 69 73 20 6e 6f 74 20 69 6e 20 62 65 hat is not in be
123b0 74 77 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 tween.**
123c0 20 20 74 68 65 20 42 45 47 49 4e 20 61 6e 64 20 the BEGIN and
123d0 45 4e 44 20 6f 66 20 61 20 43 52 45 41 54 45 20 END of a CREATE
123e0 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e TRIGGER statemen
123f0 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 31 32 t..**.** {H10512
12400 7d 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c } If a memory al
12410 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f location error o
12420 63 63 75 72 73 20 64 75 72 69 6e 67 20 61 6e 20 ccurs during an
12430 69 6e 76 6f 63 61 74 69 6f 6e 0a 2a 2a 20 20 20 invocation.**
12440 20 20 20 20 20 20 20 6f 66 20 5b 73 71 6c 69 74 of [sqlit
12450 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6f e3_complete()] o
12460 72 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c r [sqlite3_compl
12470 65 74 65 31 36 28 29 5d 20 74 68 65 6e 20 74 68 ete16()] then th
12480 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f e.** ro
12490 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 utine shall retu
124a0 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d rn [SQLITE_NOMEM
124b0 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 ]..**.** ASSUMPT
124c0 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 30 IONS:.**.** {A10
124d0 35 31 32 7d 20 54 68 65 20 69 6e 70 75 74 20 74 512} The input t
124e0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c o [sqlite3_compl
124f0 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 ete()] must be a
12500 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
12510 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54 46 .** UTF
12520 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a -8 string..**.**
12530 20 7b 41 31 30 35 31 33 7d 20 54 68 65 20 69 6e {A10513} The in
12540 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f put to [sqlite3_
12550 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 complete16()] mu
12560 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 st be a zero-ter
12570 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 minated.**
12580 20 20 20 20 55 54 46 2d 31 36 20 73 74 72 69 6e UTF-16 strin
12590 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 g in native byte
125a0 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 order..*/.int s
125b0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 qlite3_complete(
125c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 const char *sql)
125d0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f ;.int sqlite3_co
125e0 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 mplete16(const v
125f0 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a oid *sql);../*.*
12600 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 * CAPI3REF: Regi
12610 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 ster A Callback
12620 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 To Handle SQLITE
12630 5f 42 55 53 59 20 45 72 72 6f 72 73 20 7b 48 31 _BUSY Errors {H1
12640 32 33 31 30 7d 20 3c 53 34 30 34 30 30 3e 0a 2a 2310} <S40400>.*
12650 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
12660 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 e sets a callbac
12670 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 k function that
12680 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 might be invoked
12690 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 whenever.** an
126a0 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 attempt is made
126b0 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 to open a databa
126c0 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e se table that an
126d0 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 other thread.**
126e0 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c or process has l
126f0 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 ocked..**.** If
12700 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 the busy callbac
12710 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 k is NULL, then
12720 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 [SQLITE_BUSY] or
12730 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 [SQLITE_IOERR_B
12740 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 LOCKED].** is re
12750 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 turned immediate
12760 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 ly upon encounte
12770 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 49 ring the lock. I
12780 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 f the busy callb
12790 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 ack.** is not NU
127a0 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c LL, then the cal
127b0 6c 62 61 63 6b 20 77 69 6c 6c 20 62 65 20 69 6e lback will be in
127c0 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 voked with two a
127d0 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 rguments..**.**
127e0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
127f0 6e 74 20 74 6f 20 74 68 65 20 68 61 6e 64 6c 65 nt to the handle
12800 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 r is a copy of t
12810 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 he void* pointer
12820 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 which.** is the
12830 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 third argument
12840 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f to sqlite3_busy_
12850 68 61 6e 64 6c 65 72 28 29 2e 20 20 54 68 65 20 handler(). The
12860 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
12870 74 6f 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 to.** the handle
12880 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 r callback is th
12890 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 e number of time
128a0 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 s that the busy
128b0 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 handler has.** b
128c0 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 een invoked for
128d0 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 this locking eve
128e0 6e 74 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 62 nt. If the.** b
128f0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 usy callback ret
12900 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 urns 0, then no
12910 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d additional attem
12920 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a pts are made to.
12930 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 ** access the da
12940 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 tabase and [SQLI
12950 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c TE_BUSY] or [SQL
12960 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 ITE_IOERR_BLOCKE
12970 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a D] is returned..
12980 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 ** If the callba
12990 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a ck returns non-z
129a0 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 ero, then anothe
129b0 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 r attempt.** is
129c0 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 made to open the
129d0 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 database for re
129e0 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 ading and the cy
129f0 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a cle repeats..**.
12a00 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 ** The presence
12a10 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 of a busy handle
12a20 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 r does not guara
12a30 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c ntee that it wil
12a40 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 l be invoked.**
12a50 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f when there is lo
12a60 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 49 ck contention. I
12a70 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 f SQLite determi
12a80 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e nes that invokin
12a90 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 g the busy.** ha
12aa0 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 ndler could resu
12ab0 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b lt in a deadlock
12ac0 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 , it will go ahe
12ad0 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 ad and return [S
12ae0 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f QLITE_BUSY].** o
12af0 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f r [SQLITE_IOERR_
12b00 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 BLOCKED] instead
12b10 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 of invoking the
12b20 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a busy handler..*
12b30 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 * Consider a sce
12b40 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 nario where one
12b50 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 process is holdi
12b60 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 ng a read lock t
12b70 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 hat.** it is try
12b80 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 ing to promote t
12b90 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 o a reserved loc
12ba0 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e k and.** a secon
12bb0 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c d process is hol
12bc0 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 ding a reserved
12bd0 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 lock that it is
12be0 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f trying.** to pro
12bf0 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 mote to an exclu
12c00 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 sive lock. The
12c10 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 first process ca
12c20 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 nnot proceed.**
12c30 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c because it is bl
12c40 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 ocked by the sec
12c50 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f ond and the seco
12c60 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f nd process canno
12c70 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 t.** proceed bec
12c80 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b ause it is block
12c90 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e ed by the first.
12ca0 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 If both proces
12cb0 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 ses.** invoke th
12cc0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c e busy handlers,
12cd0 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 neither will ma
12ce0 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e ke any progress.
12cf0 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 Therefore,.**
12d00 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b SQLite returns [
12d10 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 SQLITE_BUSY] for
12d20 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 the first proce
12d30 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 ss, hoping that
12d40 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 this.** will ind
12d50 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 uce the first pr
12d60 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 ocess to release
12d70 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 its read lock a
12d80 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 nd allow.** the
12d90 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 second process t
12da0 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a o proceed..**.**
12db0 20 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 The default bus
12dc0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 y callback is NU
12dd0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 LL..**.** The [S
12de0 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f QLITE_BUSY] erro
12df0 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 r is converted t
12e00 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f o [SQLITE_IOERR_
12e10 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e BLOCKED].** when
12e20 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 SQLite is in th
12e30 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 e middle of a la
12e40 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 rge transaction
12e50 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a where all the.**
12e60 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f changes will no
12e70 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 t fit into the i
12e80 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 n-memory cache.
12e90 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 SQLite will.**
12ea0 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 already hold a R
12eb0 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 ESERVED lock on
12ec0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
12ed0 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a e, but it needs.
12ee0 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 ** to promote th
12ef0 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 is lock to EXCLU
12f00 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 SIVE so that it
12f10 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a can spill cache.
12f20 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 ** pages into th
12f30 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
12f40 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 without harm to
12f50 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 concurrent.** re
12f60 61 64 65 72 73 2e 20 20 49 66 20 69 74 20 69 73 aders. If it is
12f70 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f unable to promo
12f80 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 te the lock, the
12f90 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a n the in-memory.
12fa0 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 ** cache will be
12fb0 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f left in an inco
12fc0 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 nsistent state a
12fd0 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a nd so the error.
12fe0 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f ** code is promo
12ff0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c ted from the rel
13000 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b atively benign [
13010 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a SQLITE_BUSY] to.
13020 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 ** the more seve
13030 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 re [SQLITE_IOERR
13040 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 54 68 69 73 _BLOCKED]. This
13050 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d error code prom
13060 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 otion.** forces
13070 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c an automatic rol
13080 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 lback of the cha
13090 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a nges. See the.*
130a0 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 * <a href="/cvst
130b0 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 rac/wiki?p=Corru
130c0 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 ptionFollowingBu
130d0 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 syError">.** Cor
130e0 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 ruptionFollowing
130f0 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 BusyError</a> wi
13100 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 ki page for a di
13110 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a scussion of why.
13120 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 ** this is impor
13130 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 tant..**.** Ther
13140 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 e can only be a
13150 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 single busy hand
13160 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 ler defined for
13170 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 each.** [databas
13180 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 e connection].
13190 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 Setting a new bu
131a0 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 sy handler clear
131b0 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 s any.** previou
131c0 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e sly set handler.
131d0 20 20 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c Note that call
131e0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 ing [sqlite3_bus
131f0 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 y_timeout()].**
13200 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 will also set or
13210 20 63 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 clear the busy
13220 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 handler..**.** T
13230 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b he busy callback
13240 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 should not take
13250 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 any actions whi
13260 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a ch modify the.**
13270 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
13280 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 tion that invoke
13290 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c d the busy handl
132a0 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 er. Any such ac
132b0 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 tions.** result
132c0 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 in undefined beh
132d0 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 49 4e avior..** .** IN
132e0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
132f0 7b 48 31 32 33 31 31 7d 20 54 68 65 20 5b 73 71 {H12311} The [sq
13300 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c lite3_busy_handl
13310 65 72 28 44 2c 43 2c 41 29 5d 20 66 75 6e 63 74 er(D,C,A)] funct
13320 69 6f 6e 20 73 68 61 6c 6c 20 72 65 70 6c 61 63 ion shall replac
13330 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 75 e.** bu
13340 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 6e 20 74 sy callback in t
13350 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
13360 6e 65 63 74 69 6f 6e 5d 20 44 20 77 69 74 68 20 nection] D with
13370 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 a new.**
13380 20 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e a new busy han
13390 64 6c 65 72 20 43 20 61 6e 64 20 61 70 70 6c 69 dler C and appli
133a0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e cation data poin
133b0 74 65 72 20 41 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ter A..**.** {H1
133c0 32 33 31 32 7d 20 4e 65 77 6c 79 20 63 72 65 61 2312} Newly crea
133d0 74 65 64 20 5b 64 61 74 61 62 61 73 65 20 63 6f ted [database co
133e0 6e 6e 65 63 74 69 6f 6e 73 5d 20 73 68 61 6c 6c nnections] shall
133f0 20 68 61 76 65 20 61 20 62 75 73 79 0a 2a 2a 20 have a busy.**
13400 20 20 20 20 20 20 20 20 20 68 61 6e 64 6c 65 72 handler
13410 20 6f 66 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 of NULL..**.**
13420 7b 48 31 32 33 31 34 7d 20 57 68 65 6e 20 74 77 {H12314} When tw
13430 6f 20 6f 72 20 6d 6f 72 65 20 5b 64 61 74 61 62 o or more [datab
13440 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d ase connections]
13450 20 73 68 61 72 65 20 61 0a 2a 2a 20 20 20 20 20 share a.**
13460 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 6e [sqlite3_en
13470 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 able_shared_cach
13480 65 20 7c 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 e | common cache
13490 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 ],.** t
134a0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 he busy handler
134b0 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 for the database
134c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 75 72 72 connection curr
134d0 65 6e 74 6c 79 20 75 73 69 6e 67 0a 2a 2a 20 20 ently using.**
134e0 20 20 20 20 20 20 20 20 74 68 65 20 63 61 63 68 the cach
134f0 65 20 73 68 61 6c 6c 20 62 65 20 69 6e 76 6f 6b e shall be invok
13500 65 64 20 77 68 65 6e 20 74 68 65 20 63 61 63 68 ed when the cach
13510 65 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 6c e encounters a l
13520 6f 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 ock..**.** {H123
13530 31 36 7d 20 49 66 20 61 20 62 75 73 79 20 68 61 16} If a busy ha
13540 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 ndler callback r
13550 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 eturns zero, the
13560 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 n the SQLite int
13570 65 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 erface.**
13580 20 20 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 that provoked
13590 20 74 68 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 the locking eve
135a0 6e 74 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 nt shall return
135b0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a [SQLITE_BUSY]..*
135c0 2a 0a 2a 2a 20 7b 48 31 32 33 31 38 7d 20 53 51 *.** {H12318} SQ
135d0 4c 69 74 65 20 73 68 61 6c 6c 20 69 6e 76 6f 6b Lite shall invok
135e0 65 73 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 es the busy hand
135f0 6c 65 72 20 77 69 74 68 20 74 77 6f 20 61 72 67 ler with two arg
13600 75 6d 65 6e 74 73 20 77 68 69 63 68 0a 2a 2a 20 uments which.**
13610 20 20 20 20 20 20 20 20 20 61 72 65 20 61 20 63 are a c
13620 6f 70 79 20 6f 66 20 74 68 65 20 70 6f 69 6e 74 opy of the point
13630 65 72 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 er supplied by t
13640 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 he 3rd parameter
13650 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 to.**
13660 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 [sqlite3_busy_ha
13670 6e 64 6c 65 72 28 29 5d 20 61 6e 64 20 61 20 63 ndler()] and a c
13680 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 ount of the numb
13690 65 72 20 6f 66 20 70 72 69 6f 72 0a 2a 2a 20 20 er of prior.**
136a0 20 20 20 20 20 20 20 20 69 6e 76 6f 63 61 74 69 invocati
136b0 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 73 79 20 ons of the busy
136c0 68 61 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 20 handler for the
136d0 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 same locking eve
136e0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 nt..**.** ASSUMP
136f0 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 TIONS:.**.** {A1
13700 32 33 31 39 7d 20 41 20 62 75 73 79 20 68 61 6e 2319} A busy han
13710 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c dler must not cl
13720 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 ose the database
13730 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 connection.**
13740 20 20 20 20 20 20 20 20 6f 72 20 5b 70 72 65 70 or [prep
13750 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
13760 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 that invoked the
13770 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a busy handler..*
13780 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 /.int sqlite3_bu
13790 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 sy_handler(sqlit
137a0 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 e3*, int(*)(void
137b0 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a *,int), void*);.
137c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
137d0 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 Set A Busy Time
137e0 6f 75 74 20 7b 48 31 32 33 34 30 7d 20 3c 53 34 out {H12340} <S4
137f0 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 0410>.**.** This
13800 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 routine sets a
13810 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 [sqlite3_busy_ha
13820 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e ndler | busy han
13830 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 dler] that sleep
13840 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 s.** for a speci
13850 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 fied amount of t
13860 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 ime when a table
13870 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65 is locked. The
13880 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c handler.** will
13890 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 sleep multiple
138a0 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c times until at l
138b0 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 east "ms" millis
138c0 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 econds of sleepi
138d0 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d ng.** have accum
138e0 75 6c 61 74 65 64 2e 20 7b 48 31 32 33 34 33 7d ulated. {H12343}
138f0 20 41 66 74 65 72 20 22 6d 73 22 20 6d 69 6c 6c After "ms" mill
13900 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 iseconds of slee
13910 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e ping,.** the han
13920 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 dler returns 0 w
13930 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c hich causes [sql
13940 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 ite3_step()] to
13950 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 return.** [SQLIT
13960 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 E_BUSY] or [SQLI
13970 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 TE_IOERR_BLOCKED
13980 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 ]..**.** Calling
13990 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 this routine wi
139a0 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c th an argument l
139b0 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 ess than or equa
139c0 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 l to zero.** tur
139d0 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 ns off all busy
139e0 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 handlers..**.**
139f0 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 There can only b
13a00 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 e a single busy
13a10 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 handler for a pa
13a20 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 rticular.** [dat
13a30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
13a40 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 ] any any given
13a50 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 moment. If anot
13a60 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 her busy handler
13a70 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 .** was defined
13a80 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 (using [sqlite3
13a90 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d _busy_handler()]
13aa0 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 ) prior to calli
13ab0 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 ng.** this routi
13ac0 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 ne, that other b
13ad0 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 usy handler is c
13ae0 6c 65 61 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e leared..**.** IN
13af0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
13b00 7b 48 31 32 33 34 31 7d 20 54 68 65 20 5b 73 71 {H12341} The [sq
13b10 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f lite3_busy_timeo
13b20 75 74 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 ut()] function s
13b30 68 61 6c 6c 20 6f 76 65 72 72 69 64 65 20 61 6e hall override an
13b40 79 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 y prior.**
13b50 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 [sqlite3_bus
13b60 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 6f 72 20 y_timeout()] or
13b70 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 [sqlite3_busy_ha
13b80 6e 64 6c 65 72 28 29 5d 20 73 65 74 74 69 6e 67 ndler()] setting
13b90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20 .** on
13ba0 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 the same [databa
13bb0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a se connection]..
13bc0 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34 33 7d 20 49 **.** {H12343} I
13bd0 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 f the 2nd parame
13be0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
13bf0 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 busy_timeout()]
13c00 69 73 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 is less than.**
13c10 20 20 20 20 20 20 20 20 20 6f 72 20 65 71 75 61 or equa
13c20 6c 20 74 6f 20 7a 65 72 6f 2c 20 74 68 65 6e 20 l to zero, then
13c30 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
13c40 20 73 68 61 6c 6c 20 62 65 20 63 6c 65 61 72 65 shall be cleare
13c50 64 20 73 6f 20 74 68 61 74 0a 2a 2a 20 20 20 20 d so that.**
13c60 20 20 20 20 20 20 61 6c 6c 20 73 75 62 73 65 71 all subseq
13c70 75 65 6e 74 20 6c 6f 63 6b 69 6e 67 20 65 76 65 uent locking eve
13c80 6e 74 73 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 nts immediately
13c90 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 return [SQLITE_B
13ca0 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 USY]..**.** {H12
13cb0 33 34 34 7d 20 49 66 20 74 68 65 20 32 6e 64 20 344} If the 2nd
13cc0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 parameter to [sq
13cd0 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f lite3_busy_timeo
13ce0 75 74 28 29 5d 20 69 73 20 61 20 70 6f 73 69 74 ut()] is a posit
13cf0 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ive.**
13d00 6e 75 6d 62 65 72 20 4e 2c 20 74 68 65 6e 20 61 number N, then a
13d10 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 73 68 busy handler sh
13d20 61 6c 6c 20 62 65 20 73 65 74 20 74 68 61 74 20 all be set that
13d30 72 65 70 65 61 74 65 64 6c 79 20 63 61 6c 6c 73 repeatedly calls
13d40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
13d50 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 xSleep() method
13d60 20 69 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 in the [sqlite3
13d70 5f 76 66 73 20 7c 20 56 46 53 20 69 6e 74 65 72 _vfs | VFS inter
13d80 66 61 63 65 5d 20 75 6e 74 69 6c 0a 2a 2a 20 20 face] until.**
13d90 20 20 20 20 20 20 20 20 65 69 74 68 65 72 20 74 either t
13da0 68 65 20 6c 6f 63 6b 20 63 6c 65 61 72 73 20 6f he lock clears o
13db0 72 20 75 6e 74 69 6c 20 74 68 65 20 63 75 6d 75 r until the cumu
13dc0 6c 61 74 69 76 65 20 73 6c 65 65 70 20 74 69 6d lative sleep tim
13dd0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 e.** re
13de0 70 6f 72 74 65 64 20 62 61 63 6b 20 62 79 20 78 ported back by x
13df0 53 6c 65 65 70 28 29 20 65 78 63 65 65 64 73 20 Sleep() exceeds
13e00 4e 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a N milliseconds..
13e10 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 */.int sqlite3_b
13e20 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 usy_timeout(sqli
13e30 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a te3*, int ms);..
13e40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
13e50 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 Convenience Rout
13e60 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 ines For Running
13e70 20 51 75 65 72 69 65 73 20 7b 48 31 32 33 37 30 Queries {H12370
13e80 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a } <S10000>.**.**
13e90 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c Definition: A <
13ea0 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f b>result table</
13eb0 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 b> is memory dat
13ec0 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61 a structure crea
13ed0 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 ted by the.** [s
13ee0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
13ef0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 ()] interface.
13f00 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 A result table r
13f10 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f ecords the.** co
13f20 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 mplete query res
13f30 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 ults from one or
13f40 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a more queries..*
13f50 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 *.** The table c
13f60 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 onceptually has
13f70 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 a number of rows
13f80 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 and columns. B
13f90 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 ut.** these numb
13fa0 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 ers are not part
13fb0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 of the result t
13fc0 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 able itself. Th
13fd0 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 ese.** numbers a
13fe0 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 re obtained sepa
13ff0 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 rately. Let N b
14000 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 e the number of
14010 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 rows.** and M be
14020 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 the number of c
14030 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 olumns..**.** A
14040 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 result table is
14050 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e an array of poin
14060 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 ters to zero-ter
14070 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 minated UTF-8 st
14080 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 rings..** There
14090 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d are (N+1)*M elem
140a0 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 ents in the arra
140b0 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 y. The first M
140c0 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a pointers point.*
140d0 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e * to zero-termin
140e0 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 ated strings tha
140f0 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e t contain the n
14100 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 ames of the colu
14110 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 mns..** The rema
14120 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c ining entries al
14130 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 l point to query
14140 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 results. NULL
14150 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a values result.**
14160 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 in NULL pointer
14170 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 s. All other va
14180 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 lues are in thei
14190 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 r UTF-8 zero-ter
141a0 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e minated.** strin
141b0 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e g representation
141c0 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 as returned by
141d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
141e0 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 text()]..**.** A
141f0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 result table mi
14200 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f ght consist of o
14210 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 ne or more memor
14220 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a y allocations..*
14230 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 * It is not safe
14240 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c to pass a resul
14250 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 t table directly
14260 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 to [sqlite3_fre
14270 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c e()]..** A resul
14280 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 t table should b
14290 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 e deallocated us
142a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 ing [sqlite3_fre
142b0 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a e_table()]..**.*
142c0 2a 20 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 * As an example
142d0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 of the result ta
142e0 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 ble format, supp
142f0 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 ose a query resu
14300 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c lt.** is as foll
14310 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 ows:.**.** <bloc
14320 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 kquote><pre>.**
14330 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 Name
14340 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 | Age.**
14350 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d -------------
14360 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 ----------.**
14370 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 Alice
14380 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 | 43.**
14390 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 Bob | 28
143a0 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 .** Cindy
143b0 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c | 21.** <
143c0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
143d0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 e>.**.** There a
143e0 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d re two column (M
143f0 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 ==2) and three r
14400 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 ows (N==3). Thu
14410 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 s the.** result
14420 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 table has 8 entr
14430 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 ies. Suppose th
14440 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 e result table i
14450 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 s stored.** in a
14460 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a n array names az
14470 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a Result. Then az
14480 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 Result holds thi
14490 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a s content:.**.**
144a0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
144b0 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 e>.** azR
144c0 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 esult[0] = "
144d0 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 Name";.**
144e0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d azResult[1]
144f0 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 = "Age";.**
14500 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
14510 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a ;2] = "Alice";.*
14520 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
14530 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b t[3] = "43";
14540 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
14550 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f ult[4] = "Bo
14560 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a b";.** az
14570 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 Result[5] =
14580 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 "28";.**
14590 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 azResult[6]
145a0 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 = "Cindy";.**
145b0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
145c0 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 1;7] = "21";.**
145d0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
145e0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 te>.**.** The sq
145f0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
14600 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 ) function evalu
14610 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 ates one or more
14620 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 .** semicolon-se
14630 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 parated SQL stat
14640 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 ements in the ze
14650 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 ro-terminated UT
14660 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 F-8.** string of
14670 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 its 2nd paramet
14680 65 72 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 er. It returns
14690 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 a result table t
146a0 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 o the.** pointer
146b0 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 given in its 3r
146c0 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a d parameter..**.
146d0 2a 2a 20 41 66 74 65 72 20 74 68 65 20 63 61 6c ** After the cal
146e0 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68 61 ling function ha
146f0 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 s finished using
14700 20 74 68 65 20 72 65 73 75 6c 74 2c 20 69 74 20 the result, it
14710 73 68 6f 75 6c 64 0a 2a 2a 20 70 61 73 73 20 74 should.** pass t
14720 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 he pointer to th
14730 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 e result table t
14740 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 o sqlite3_free_t
14750 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 able() in order
14760 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 to.** release th
14770 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 e memory that wa
14780 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 s malloced. Bec
14790 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 ause of the way
147a0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
147b0 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e malloc()] happen
147c0 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 s within sqlite3
147d0 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 _get_table(), th
147e0 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e e calling.** fun
147f0 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 ction must not t
14800 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 ry to call [sqli
14810 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 te3_free()] dire
14820 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b ctly. Only.** [
14830 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 sqlite3_free_tab
14840 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f le()] is able to
14850 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d release the mem
14860 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 ory properly and
14870 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 safely..**.** T
14880 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 he sqlite3_get_t
14890 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 able() interface
148a0 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 is implemented
148b0 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f as a wrapper aro
148c0 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f und.** [sqlite3_
148d0 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 exec()]. The sq
148e0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
148f0 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e ) routine does n
14900 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a ot have access.*
14910 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 * to any interna
14920 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 l data structure
14930 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 s of SQLite. It
14940 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 uses only the p
14950 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 ublic.** interfa
14960 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e ce defined here.
14970 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e As a consequen
14980 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 ce, errors that
14990 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 occur in the.**
149a0 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 wrapper layer ou
149b0 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 tside of the int
149c0 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 ernal [sqlite3_e
149d0 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 xec()] call are
149e0 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 not.** reflected
149f0 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 in subsequent c
14a00 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
14a10 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 20 5b _errcode()] or [
14a20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 sqlite3_errmsg()
14a30 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 ]..**.** INVARIA
14a40 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 NTS:.**.** {H123
14a50 37 31 7d 20 49 66 20 61 20 5b 73 71 6c 69 74 65 71} If a [sqlite
14a60 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 3_get_table()] f
14a70 61 69 6c 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c ails a memory al
14a80 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a location, then.*
14a90 2a 20 20 20 20 20 20 20 20 20 20 69 74 20 73 68 * it sh
14aa0 61 6c 6c 20 66 72 65 65 20 74 68 65 20 72 65 73 all free the res
14ab0 75 6c 74 20 74 61 62 6c 65 20 75 6e 64 65 72 20 ult table under
14ac0 63 6f 6e 73 74 72 75 63 74 69 6f 6e 2c 20 61 62 construction, ab
14ad0 6f 72 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 ort the.**
14ae0 20 20 20 20 71 75 65 72 79 20 69 6e 20 70 72 6f query in pro
14af0 63 65 73 73 2c 20 73 6b 69 70 20 61 6e 79 20 73 cess, skip any s
14b00 75 62 73 65 71 75 65 6e 74 20 71 75 65 72 69 65 ubsequent querie
14b10 73 2c 20 73 65 74 20 74 68 65 0a 2a 2a 20 20 20 s, set the.**
14b20 20 20 20 20 20 20 20 2a 70 61 7a 52 65 73 75 6c *pazResul
14b30 74 20 6f 75 74 70 75 74 20 70 6f 69 6e 74 65 72 t output pointer
14b40 20 74 6f 20 4e 55 4c 4c 20 61 6e 64 20 72 65 74 to NULL and ret
14b50 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 urn [SQLITE_NOME
14b60 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 M]..**.** {H1237
14b70 33 7d 20 49 66 20 74 68 65 20 70 6e 43 6f 6c 75 3} If the pnColu
14b80 6d 6e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 mn parameter to
14b90 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 [sqlite3_get_tab
14ba0 6c 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c le()] is not NUL
14bb0 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 L.** th
14bc0 65 6e 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 en a successful
14bd0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 invocation of [s
14be0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
14bf0 28 29 5d 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 ()] shall.**
14c00 20 20 20 20 20 20 77 72 69 74 65 20 74 68 65 20 write the
14c10 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e number of column
14c20 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 s in the.**
14c30 20 20 20 20 20 72 65 73 75 6c 74 20 73 65 74 20 result set
14c40 6f 66 20 74 68 65 20 71 75 65 72 79 20 69 6e 74 of the query int
14c50 6f 20 2a 70 6e 43 6f 6c 75 6d 6e 2e 0a 2a 2a 0a o *pnColumn..**.
14c60 2a 2a 20 7b 48 31 32 33 37 34 7d 20 49 66 20 74 ** {H12374} If t
14c70 68 65 20 70 6e 52 6f 77 20 70 61 72 61 6d 65 74 he pnRow paramet
14c80 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67 er to [sqlite3_g
14c90 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 6e et_table()] is n
14ca0 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 ot NULL.**
14cb0 20 20 20 20 74 68 65 6e 20 61 20 73 75 63 63 65 then a succe
14cc0 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e ssful invocation
14cd0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 of [sqlite3_get
14ce0 5f 74 61 62 6c 65 28 29 5d 20 73 68 61 6c 6c 0a _table()] shall.
14cf0 2a 2a 20 20 20 20 20 20 20 20 20 20 77 72 69 74 ** writ
14d00 65 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 es the number of
14d10 20 72 6f 77 73 20 69 6e 20 74 68 65 0a 2a 2a 20 rows in the.**
14d20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 result
14d30 73 65 74 20 6f 66 20 74 68 65 20 71 75 65 72 79 set of the query
14d40 20 69 6e 74 6f 20 2a 70 6e 52 6f 77 2e 0a 2a 2a into *pnRow..**
14d50 0a 2a 2a 20 7b 48 31 32 33 37 36 7d 20 41 20 73 .** {H12376} A s
14d60 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 uccessful invoca
14d70 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 tion of [sqlite3
14d80 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 74 68 _get_table()] th
14d90 61 74 20 63 6f 6d 70 75 74 65 73 0a 2a 2a 20 20 at computes.**
14da0 20 20 20 20 20 20 20 20 4e 20 72 6f 77 73 20 6f N rows o
14db0 66 20 72 65 73 75 6c 74 20 77 69 74 68 20 43 20 f result with C
14dc0 63 6f 6c 75 6d 6e 73 20 70 65 72 20 72 6f 77 20 columns per row
14dd0 73 68 61 6c 6c 20 6d 61 6b 65 20 2a 70 61 7a 52 shall make *pazR
14de0 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 20 20 20 esult.**
14df0 20 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 72 point to an ar
14e00 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 ray of pointers
14e10 74 6f 20 28 4e 2b 31 29 2a 43 20 73 74 72 69 6e to (N+1)*C strin
14e20 67 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72 gs where the fir
14e30 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 st.** C
14e40 20 73 74 72 69 6e 67 73 20 61 72 65 20 63 6f 6c strings are col
14e50 75 6d 6e 20 6e 61 6d 65 73 20 61 73 20 6f 62 74 umn names as obt
14e60 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 20 20 ained from.**
14e70 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
14e80 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 column_name()] a
14e90 6e 64 20 74 68 65 20 72 65 73 74 20 61 72 65 20 nd the rest are
14ea0 63 6f 6c 75 6d 6e 20 72 65 73 75 6c 74 20 76 61 column result va
14eb0 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 lues.**
14ec0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
14ed0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
14ee0 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ext()]..**.** {H
14ef0 31 32 33 37 39 7d 20 54 68 65 20 76 61 6c 75 65 12379} The value
14f00 73 20 69 6e 20 74 68 65 20 70 61 7a 52 65 73 75 s in the pazResu
14f10 6c 74 20 61 72 72 61 79 20 72 65 74 75 72 6e 65 lt array returne
14f20 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 67 65 d by [sqlite3_ge
14f30 74 5f 74 61 62 6c 65 28 29 5d 0a 2a 2a 20 20 20 t_table()].**
14f40 20 20 20 20 20 20 20 73 68 61 6c 6c 20 72 65 6d shall rem
14f50 61 69 6e 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 ain valid until
14f60 63 6c 65 61 72 65 64 20 62 79 20 5b 73 71 6c 69 cleared by [sqli
14f70 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 te3_free_table()
14f80 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 38 32 ]..**.** {H12382
14f90 7d 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 } When an error
14fa0 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 65 76 occurs during ev
14fb0 61 6c 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c aluation of [sql
14fc0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
14fd0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 ].** th
14fe0 65 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c e function shall
14ff0 20 73 65 74 20 2a 70 61 7a 52 65 73 75 6c 74 20 set *pazResult
15000 74 6f 20 4e 55 4c 4c 2c 20 77 72 69 74 65 20 61 to NULL, write a
15010 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a n error message.
15020 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 6f ** into
15030 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 memory obtained
15040 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
15050 61 6c 6c 6f 63 28 29 5d 2c 20 6d 61 6b 65 0a 2a alloc()], make.*
15060 2a 20 20 20 20 20 20 20 20 20 20 2a 2a 70 7a 45 * **pzE
15070 72 72 6d 73 67 20 70 6f 69 6e 74 20 74 6f 20 74 rrmsg point to t
15080 68 61 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67 hat error messag
15090 65 2c 20 61 6e 64 20 72 65 74 75 72 6e 20 61 0a e, and return a.
150a0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 70 70 72 ** appr
150b0 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 opriate [error c
150c0 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c ode]..*/.int sql
150d0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a ite3_get_table(.
150e0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
150f0 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 /* An op
15100 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 en database */.
15110 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 const char *zSq
15120 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f l, /* SQL to
15130 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f be evaluated */
15140 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 . char ***pazRe
15150 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 sult, /* Resu
15160 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 lts of the query
15170 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 */. int *pnRow
15180 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e , /* N
15190 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 umber of result
151a0 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 rows written her
151b0 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f e */. int *pnCo
151c0 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 lumn, /*
151d0 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 Number of result
151e0 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e columns written
151f0 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 here */. char
15200 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 **pzErrmsg
15210 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 /* Error msg wr
15220 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b itten here */.);
15230 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 .void sqlite3_fr
15240 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a ee_table(char **
15250 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 result);../*.**
15260 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 CAPI3REF: Format
15270 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 ted String Print
15280 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 ing Functions {H
15290 31 37 34 30 30 7d 20 3c 53 37 30 30 30 30 3e 3c 17400} <S70000><
152a0 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S20000>.**.** Th
152b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
152c0 20 77 6f 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 workalikes of t
152d0 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 he "printf()" fa
152e0 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e mily of function
152f0 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 s.** from the st
15300 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 andard C library
15310 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
15320 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e te3_mprintf() an
15330 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e d sqlite3_vmprin
15340 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 tf() routines wr
15350 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 ite their.** res
15360 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 ults into memory
15370 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
15380 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
15390 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 ]..** The string
153a0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 s returned by th
153b0 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 ese two routines
153c0 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 should be.** re
153d0 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 leased by [sqlit
153e0 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 42 6f 74 e3_free()]. Bot
153f0 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 h routines retur
15400 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e n a.** NULL poin
15410 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f ter if [sqlite3_
15420 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 malloc()] is una
15430 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 ble to allocate
15440 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 enough.** memory
15450 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 to hold the res
15460 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a ulting string..*
15470 2a 0a 2a 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f *.** In sqlite3_
15480 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 snprintf() routi
15490 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f ne is similar to
154a0 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 "snprintf()" fr
154b0 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 om.** the standa
154c0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 rd C library. T
154d0 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 he result is wri
154e0 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a tten into the.**
154f0 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 buffer supplied
15500 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 as the second p
15510 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 arameter whose s
15520 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a ize is given by.
15530 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 ** the first par
15540 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 ameter. Note tha
15550 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 t the order of t
15560 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 he.** first two
15570 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 parameters is re
15580 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 versed from snpr
15590 69 6e 74 66 28 29 2e 20 20 54 68 69 73 20 69 73 intf(). This is
155a0 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 an.** historica
155b0 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 l accident that
155c0 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 cannot be fixed
155d0 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 without breaking
155e0 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f .** backwards co
155f0 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f mpatibility. No
15600 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c te also that sql
15610 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a ite3_snprintf().
15620 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ** returns a poi
15630 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 nter to its buff
15640 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 er instead of th
15650 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 e number of.** c
15660 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c haracters actual
15670 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 ly written into
15680 74 68 65 20 62 75 66 66 65 72 2e 20 20 57 65 20 the buffer. We
15690 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 admit that.** th
156a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 e number of char
156b0 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 acters written w
156c0 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 ould be a more u
156d0 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 seful return.**
156e0 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e value but we can
156f0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 not change the i
15700 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
15710 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 sqlite3_snprint
15720 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f f().** now witho
15730 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 ut breaking comp
15740 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a atibility..**.**
15750 20 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 As long as the
15760 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 buffer size is g
15770 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f reater than zero
15780 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e , sqlite3_snprin
15790 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 tf().** guarante
157a0 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 es that the buff
157b0 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 er is always zer
157c0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 o-terminated. T
157d0 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 he first.** para
157e0 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 meter "n" is the
157f0 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 total size of t
15800 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 he buffer, inclu
15810 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a ding space for.*
15820 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 * the zero termi
15830 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c nator. So the l
15840 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 ongest string th
15850 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 at can be comple
15860 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 tely.** written
15870 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 will be n-1 char
15880 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 acters..**.** Th
15890 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c ese routines all
158a0 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 implement some
158b0 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 additional forma
158c0 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 tting.** options
158d0 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c that are useful
158e0 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e for constructin
158f0 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 g SQL statements
15900 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 ..** All of the
15910 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 usual printf() f
15920 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e ormatting option
15930 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 s apply. In add
15940 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 ition, there.**
15950 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 is are "%q", "%Q
15960 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 ", and "%z" opti
15970 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 ons..**.** The %
15980 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c q option works l
15990 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 ike %s in that i
159a0 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 t substitutes a
159b0 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a null-terminated.
159c0 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 ** string from t
159d0 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 he argument list
159e0 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 . But %q also d
159f0 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 oubles every '\'
15a00 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 ' character..**
15a10 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 %q is designed f
15a20 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 or use inside a
15a30 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 20 string literal.
15a40 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 By doubling eac
15a50 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 h '\''.** charac
15a60 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 ter it escapes t
15a70 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e hat character an
15a80 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 d allows it to b
15a90 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a e inserted into.
15aa0 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a ** the string..*
15ab0 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 *.** For example
15ac0 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 , assume the str
15ad0 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 ing variable zTe
15ae0 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 xt contains text
15af0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a as follows:.**.
15b00 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
15b10 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a pre>.** char *z
15b20 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 Text = "It's a h
15b30 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c appy day!";.** <
15b40 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
15b50 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e e>.**.** One can
15b60 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 use this text i
15b70 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 n an SQL stateme
15b80 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a nt as follows:.*
15b90 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
15ba0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 ><pre>.** char
15bb0 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f *zSQL = sqlite3_
15bc0 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 mprintf("INSERT
15bd0 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 INTO table VALUE
15be0 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 S('%q')", zText)
15bf0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 ;.** sqlite3_ex
15c00 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 ec(db, zSQL, 0,
15c10 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 0, 0);.** sqlit
15c20 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a e3_free(zSQL);.*
15c30 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
15c40 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 uote>.**.** Beca
15c50 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 use the %q forma
15c60 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 t string is used
15c70 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 , the '\'' chara
15c80 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a cter in zText.**
15c90 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 is escaped and
15ca0 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 the SQL generate
15cb0 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a d is as follows:
15cc0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
15cd0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 te><pre>.** INS
15ce0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 ERT INTO table1
15cf0 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 VALUES('It''s a
15d00 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 happy day!').**
15d10 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
15d20 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 te>.**.** This i
15d30 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 s correct. Had
15d40 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 we used %s inste
15d50 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 ad of %q, the ge
15d60 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 nerated SQL.** w
15d70 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 ould have looked
15d80 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a like this:.**.*
15d90 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
15da0 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 re>.** INSERT I
15db0 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 NTO table1 VALUE
15dc0 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 S('It's a happy
15dd0 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 day!');.** </pre
15de0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
15df0 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 *.** This second
15e00 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 example is an S
15e10 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e QL syntax error.
15e20 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 As a general r
15e30 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a ule you should.*
15e40 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 * always use %q
15e50 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 instead of %s wh
15e60 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 en inserting tex
15e70 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 t into a string
15e80 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 literal..**.** T
15e90 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 he %Q option wor
15ea0 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 ks like %q excep
15eb0 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 t it also adds s
15ec0 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f ingle quotes aro
15ed0 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 und.** the outsi
15ee0 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 de of the total
15ef0 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f string. Additio
15f00 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 nally, if the pa
15f10 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a rameter in the.*
15f20 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 * argument list
15f30 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
15f40 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65 r, %Q substitute
15f50 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c s the text "NULL
15f60 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 " (without.** si
15f70 6e 67 6c 65 20 71 75 6f 74 65 73 29 20 69 6e 20 ngle quotes) in
15f80 70 6c 61 63 65 20 6f 66 20 74 68 65 20 25 51 20 place of the %Q
15f90 6f 70 74 69 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 option. So, for
15fa0 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f example, one co
15fb0 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c uld say:.**.** <
15fc0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
15fd0 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 .** char *zSQL
15fe0 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 = sqlite3_mprint
15ff0 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 f("INSERT INTO t
16000 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 able VALUES(%Q)"
16010 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 , zText);.** sq
16020 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a lite3_exec(db, z
16030 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a SQL, 0, 0, 0);.*
16040 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 * sqlite3_free(
16050 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e zSQL);.** </pre>
16060 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
16070 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f .** The code abo
16080 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 ve will render a
16090 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 correct SQL sta
160a0 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 tement in the zS
160b0 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 QL.** variable e
160c0 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 ven if the zText
160d0 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e variable is a N
160e0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a ULL pointer..**.
160f0 2a 2a 20 54 68 65 20 22 25 7a 22 20 66 6f 72 6d ** The "%z" form
16100 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f atting option wo
16110 72 6b 73 20 65 78 61 63 74 6c 79 20 6c 69 6b 65 rks exactly like
16120 20 22 25 73 22 20 77 69 74 68 20 74 68 65 0a 2a "%s" with the.*
16130 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 * addition that
16140 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 after the string
16150 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 has been read a
16160 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a nd copied into.*
16170 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 * the result, [s
16180 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 qlite3_free()] i
16190 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 s called on the
161a0 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 20 7b 45 input string. {E
161b0 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 ND}.**.** INVARI
161c0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 ANTS:.**.** {H17
161d0 34 30 33 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 403} The [sqlit
161e0 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 61 6e e3_mprintf()] an
161f0 64 20 5b 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 d [sqlite3_vmpri
16200 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ntf()] interface
16210 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 s.** r
16220 65 74 75 72 6e 20 65 69 74 68 65 72 20 70 6f 69 eturn either poi
16230 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 nters to zero-te
16240 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 rminated UTF-8 s
16250 74 72 69 6e 67 73 20 68 65 6c 64 20 69 6e 0a 2a trings held in.*
16260 2a 20 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f * memo
16270 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ry obtained from
16280 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
16290 28 29 5d 20 6f 72 20 4e 55 4c 4c 20 70 6f 69 6e ()] or NULL poin
162a0 74 65 72 73 20 69 66 0a 2a 2a 20 20 20 20 20 20 ters if.**
162b0 20 20 20 20 20 61 20 63 61 6c 6c 20 74 6f 20 5b a call to [
162c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
162d0 5d 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b ] fails..**.** {
162e0 48 31 37 34 30 36 7d 20 20 54 68 65 20 5b 73 71 H17406} The [sq
162f0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
16300 5d 20 69 6e 74 65 72 66 61 63 65 20 77 72 69 74 ] interface writ
16310 65 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e es a zero-termin
16320 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 ated.**
16330 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 69 UTF-8 string i
16340 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 20 70 nto the buffer p
16350 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 ointed to by the
16360 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
16370 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 70 r.** p
16380 72 6f 76 69 64 65 64 20 74 68 61 74 20 74 68 65 rovided that the
16390 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
163a0 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e is greater than
163b0 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 zero..**.** {H1
163c0 37 34 30 37 7d 20 20 54 68 65 20 5b 73 71 6c 69 7407} The [sqli
163d0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 te3_snprintf()]
163e0 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e interface does n
163f0 6f 74 20 77 72 69 74 65 20 73 6c 6f 74 73 20 6f ot write slots o
16400 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 f.** i
16410 74 73 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 ts output buffer
16420 20 28 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 (the second par
16430 61 6d 65 74 65 72 29 20 6f 75 74 73 69 64 65 20 ameter) outside
16440 74 68 65 20 72 61 6e 67 65 0a 2a 2a 20 20 20 20 the range.**
16450 20 20 20 20 20 20 20 6f 66 20 30 20 74 68 72 6f of 0 thro
16460 75 67 68 20 4e 2d 31 20 28 77 68 65 72 65 20 4e ugh N-1 (where N
16470 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 is the first pa
16480 72 61 6d 65 74 65 72 29 0a 2a 2a 20 20 20 20 20 rameter).**
16490 20 20 20 20 20 20 72 65 67 61 72 64 6c 65 73 73 regardless
164a0 20 6f 66 20 74 68 65 20 6c 65 6e 67 74 68 20 6f of the length o
164b0 66 20 74 68 65 20 73 74 72 69 6e 67 0a 2a 2a 20 f the string.**
164c0 20 20 20 20 20 20 20 20 20 20 72 65 71 75 65 73 reques
164d0 74 65 64 20 62 79 20 74 68 65 20 66 6f 72 6d 61 ted by the forma
164e0 74 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e t specification.
164f0 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 .*/.char *sqlite
16500 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 3_mprintf(const
16510 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 char*,...);.char
16520 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e *sqlite3_vmprin
16530 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 tf(const char*,
16540 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a va_list);.char *
16550 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
16560 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 (int,char*,const
16570 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f char*, ...);../
16580 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
16590 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e emory Allocation
165a0 20 53 75 62 73 79 73 74 65 6d 20 7b 48 31 37 33 Subsystem {H173
165b0 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 00} <S20000>.**.
165c0 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f ** The SQLite co
165d0 72 65 20 20 75 73 65 73 20 74 68 65 73 65 20 74 re uses these t
165e0 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f hree routines fo
165f0 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e r all of its own
16600 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d .** internal mem
16610 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e ory allocation n
16620 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 eeds. "Core" in
16630 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e the previous sen
16640 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f tence.** does no
16650 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 t include operat
16660 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 ing-system speci
16670 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e fic VFS implemen
16680 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 tation. The.**
16690 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 Windows VFS uses
166a0 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 native malloc()
166b0 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 and free() for
166c0 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e some operations.
166d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
166e0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 e3_malloc() rout
166f0 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f ine returns a po
16700 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b inter to a block
16710 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 .** of memory at
16720 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 least N bytes i
16730 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 n length, where
16740 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 N is the paramet
16750 65 72 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 er..** If sqlite
16760 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 3_malloc() is un
16770 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 able to obtain s
16780 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a ufficient free.*
16790 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 * memory, it ret
167a0 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e urns a NULL poin
167b0 74 65 72 2e 20 20 49 66 20 74 68 65 20 70 61 72 ter. If the par
167c0 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 ameter N to.** s
167d0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
167e0 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 is zero or negat
167f0 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ive then sqlite3
16800 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e _malloc() return
16810 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e s.** a NULL poin
16820 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 ter..**.** Calli
16830 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 ng sqlite3_free(
16840 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 ) with a pointer
16850 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 previously retu
16860 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 rned.** by sqlit
16870 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 e3_malloc() or s
16880 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
16890 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d releases that m
168a0 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 emory so.** that
168b0 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 it might be reu
168c0 73 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 sed. The sqlite
168d0 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 3_free() routine
168e0 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 is.** a no-op i
168f0 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 f is called with
16900 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
16910 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c Passing a NULL
16920 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 pointer.** to s
16930 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 qlite3_free() is
16940 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 harmless. Afte
16950 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d r being freed, m
16960 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 emory.** should
16970 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 neither be read
16980 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 nor written. Ev
16990 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 en reading previ
169a0 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d ously freed.** m
169b0 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 emory might resu
169c0 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 lt in a segmenta
169d0 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 tion fault or ot
169e0 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 her severe error
169f0 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 ..** Memory corr
16a00 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e uption, a segmen
16a10 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 tation fault, or
16a20 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 other severe er
16a30 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 ror.** might res
16a40 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 ult if sqlite3_f
16a50 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 ree() is called
16a60 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 with a non-NULL
16a70 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 pointer that.**
16a80 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 was not obtained
16a90 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 from sqlite3_ma
16aa0 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 lloc() or sqlite
16ab0 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 3_realloc()..**.
16ac0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 ** The sqlite3_r
16ad0 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 ealloc() interfa
16ae0 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 ce attempts to r
16af0 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 esize a.** prior
16b00 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
16b10 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 on to be at leas
16b20 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 t N bytes, where
16b30 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 N is the.** sec
16b40 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 ond parameter.
16b50 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 The memory alloc
16b60 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 ation to be resi
16b70 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74 zed is the first
16b80 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 20 .** parameter.
16b90 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 If the first par
16ba0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
16bb0 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 3_realloc().** i
16bc0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
16bd0 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 then its behavi
16be0 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 or is identical
16bf0 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 to calling.** sq
16c00 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 lite3_malloc(N)
16c10 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 where N is the s
16c20 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
16c30 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c to sqlite3_reall
16c40 6f 63 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65 20 oc()..** If the
16c50 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
16c60 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c to sqlite3_real
16c70 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 loc() is zero or
16c80 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 .** negative the
16c90 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 n the behavior i
16ca0 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 s exactly the sa
16cb0 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a me as calling.**
16cc0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 sqlite3_free(P)
16cd0 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20 where P is the
16ce0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
16cf0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c to sqlite3_reall
16d00 6f 63 28 29 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 oc()..** sqlite3
16d10 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 _realloc() retur
16d20 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
16d30 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 a memory allocat
16d40 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 ion.** of at lea
16d50 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 st N bytes in si
16d60 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 ze or NULL if su
16d70 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 fficient memory
16d80 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a is unavailable..
16d90 2a 2a 20 49 66 20 4d 20 69 73 20 74 68 65 20 73 ** If M is the s
16da0 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 ize of the prior
16db0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 allocation, the
16dc0 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 n min(N,M) bytes
16dd0 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 .** of the prior
16de0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 allocation are
16df0 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 copied into the
16e00 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 beginning of buf
16e10 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 fer returned.**
16e20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c by sqlite3_reall
16e30 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 oc() and the pri
16e40 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 or allocation is
16e50 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73 71 freed..** If sq
16e60 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 lite3_realloc()
16e70 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 returns NULL, th
16e80 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c en the prior all
16e90 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f ocation.** is no
16ea0 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 t freed..**.** T
16eb0 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e he memory return
16ec0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 ed by sqlite3_ma
16ed0 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 lloc() and sqlit
16ee0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 e3_realloc().**
16ef0 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 is always aligne
16f00 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e d to at least an
16f10 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 8 byte boundary
16f20 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 . {END}.**.** Th
16f30 65 20 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d e default implem
16f40 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 entation of the
16f50 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
16f60 6e 20 73 75 62 73 79 73 74 65 6d 20 75 73 65 73 n subsystem uses
16f70 0a 2a 2a 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29 .** the malloc()
16f80 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 , realloc() and
16f90 66 72 65 65 28 29 20 70 72 6f 76 69 64 65 64 20 free() provided
16fa0 62 79 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 by the standard
16fb0 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 7b 48 C library..** {H
16fc0 31 37 33 38 32 7d 20 48 6f 77 65 76 65 72 2c 20 17382} However,
16fd0 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d if SQLite is com
16fe0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a piled with the.*
16ff0 2a 20 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f * SQLITE_MEMORY_
17000 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 SIZE=<i>NNN</i>
17010 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d C preprocessor m
17020 61 63 72 6f 20 28 77 68 65 72 65 20 3c 69 3e 4e acro (where <i>N
17030 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69 73 20 61 6e 20 NN</i>.** is an
17040 69 6e 74 65 67 65 72 29 2c 20 74 68 65 6e 20 53 integer), then S
17050 51 4c 69 74 65 20 63 72 65 61 74 65 20 61 20 73 QLite create a s
17060 74 61 74 69 63 20 61 72 72 61 79 20 6f 66 20 61 tatic array of a
17070 74 20 6c 65 61 73 74 0a 2a 2a 20 3c 69 3e 4e 4e t least.** <i>NN
17080 4e 3c 2f 69 3e 20 62 79 74 65 73 20 69 6e 20 73 N</i> bytes in s
17090 69 7a 65 20 61 6e 64 20 75 73 65 73 20 74 68 61 ize and uses tha
170a0 74 20 61 72 72 61 79 20 66 6f 72 20 61 6c 6c 20 t array for all
170b0 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 0a 2a of its dynamic.*
170c0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 * memory allocat
170d0 69 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44 7d ion needs. {END}
170e0 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d Additional mem
170f0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 70 ory allocator op
17100 74 69 6f 6e 73 0a 2a 2a 20 6d 61 79 20 62 65 20 tions.** may be
17110 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 added in future
17120 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 releases..**.**
17130 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f In SQLite versio
17140 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e n 3.5.0 and 3.5.
17150 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 1, it was possib
17160 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 le to define.**
17170 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f the SQLITE_OMIT_
17180 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f MEMORY_ALLOCATIO
17190 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 N which would ca
171a0 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e use the built-in
171b0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
171c0 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 on of these rout
171d0 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 ines to be omitt
171e0 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 ed. That capabi
171f0 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f lity.** is no lo
17200 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 nger provided.
17210 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 Only built-in me
17220 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 mory allocators
17230 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a can be used..**.
17240 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f ** The Windows O
17250 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 S interface laye
17260 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 r calls.** the s
17270 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 ystem malloc() a
17280 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74 nd free() direct
17290 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 ly when converti
172a0 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 ng.** filenames
172b0 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d between the UTF-
172c0 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 8 encoding used
172d0 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 by SQLite.** and
172e0 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 whatever filena
172f0 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 me encoding is u
17300 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69 sed by the parti
17310 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a cular Windows.**
17320 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 installation.
17330 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f Memory allocatio
17340 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 74 n errors are det
17350 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 ected, but.** th
17360 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 ey are reported
17370 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f back as [SQLITE_
17380 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 CANTOPEN] or.**
17390 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 [SQLITE_IOERR] r
173a0 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 ather than [SQLI
173b0 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a TE_NOMEM]..**.**
173c0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
173d0 2a 2a 20 7b 48 31 37 33 30 33 7d 20 20 54 68 65 ** {H17303} The
173e0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
173f0 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 (N)] interface r
17400 65 74 75 72 6e 73 20 65 69 74 68 65 72 20 61 20 eturns either a
17410 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20 pointer to.**
17420 20 20 20 20 20 20 20 20 61 20 6e 65 77 6c 79 20 a newly
17430 63 68 65 63 6b 65 64 2d 6f 75 74 20 62 6c 6f 63 checked-out bloc
17440 6b 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 k of at least N
17450 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 0a bytes of memory.
17460 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 61 ** tha
17470 74 20 69 73 20 38 2d 62 79 74 65 20 61 6c 69 67 t is 8-byte alig
17480 6e 65 64 2c 20 6f 72 20 69 74 20 72 65 74 75 72 ned, or it retur
17490 6e 73 20 4e 55 4c 4c 20 69 66 20 69 74 20 69 73 ns NULL if it is
174a0 20 75 6e 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 unable.**
174b0 20 20 20 20 20 74 6f 20 66 75 6c 66 69 6c 6c 20 to fulfill
174c0 74 68 65 20 72 65 71 75 65 73 74 2e 0a 2a 2a 0a the request..**.
174d0 2a 2a 20 7b 48 31 37 33 30 34 7d 20 20 54 68 65 ** {H17304} The
174e0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
174f0 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 (N)] interface r
17500 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f eturns a NULL po
17510 69 6e 74 65 72 20 69 66 0a 2a 2a 20 20 20 20 20 inter if.**
17520 20 20 20 20 20 20 4e 20 69 73 20 6c 65 73 73 20 N is less
17530 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f than or equal to
17540 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 zero..**.** {H1
17550 37 33 30 35 7d 20 20 54 68 65 20 5b 73 71 6c 69 7305} The [sqli
17560 74 65 33 5f 66 72 65 65 28 50 29 5d 20 69 6e 74 te3_free(P)] int
17570 65 72 66 61 63 65 20 72 65 6c 65 61 73 65 73 20 erface releases
17580 6d 65 6d 6f 72 79 20 70 72 65 76 69 6f 75 73 6c memory previousl
17590 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 y.** r
175a0 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 eturned from [sq
175b0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
175c0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c or [sqlite3_real
175d0 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 loc()],.**
175e0 20 20 20 20 20 6d 61 6b 69 6e 67 20 69 74 20 61 making it a
175f0 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 72 65 75 vailable for reu
17600 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 se..**.** {H1730
17610 36 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 6} A call to [s
17620 71 6c 69 74 65 33 5f 66 72 65 65 28 4e 55 4c 4c qlite3_free(NULL
17630 29 5d 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 )] is a harmless
17640 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 no-op..**.** {H
17650 31 37 33 31 30 7d 20 20 41 20 63 61 6c 6c 20 74 17310} A call t
17660 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c o [sqlite3_reall
17670 6f 63 28 30 2c 4e 29 5d 20 69 73 20 65 71 75 69 oc(0,N)] is equi
17680 76 61 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c valent to a call
17690 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f .** to
176a0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
176b0 28 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 (N)]..**.** {H17
176c0 33 31 32 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 312} A call to
176d0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
176e0 28 50 2c 30 29 5d 20 69 73 20 65 71 75 69 76 61 (P,0)] is equiva
176f0 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a lent to a call.*
17700 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b * to [
17710 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 5d sqlite3_free(P)]
17720 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 35 7d ..**.** {H17315}
17730 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 The SQLite cor
17740 65 20 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f e uses [sqlite3_
17750 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 malloc()], [sqli
17760 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a te3_realloc()],.
17770 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 6e 64 ** and
17780 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
17790 5d 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 ] for all of its
177a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
177b0 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 on and.**
177c0 20 20 20 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e deallocation
177d0 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 needs..**.** {H
177e0 31 37 33 31 38 7d 20 20 54 68 65 20 5b 73 71 6c 17318} The [sql
177f0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e ite3_realloc(P,N
17800 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
17810 75 72 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f urns either a po
17820 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 inter.**
17830 20 20 20 74 6f 20 61 20 62 6c 6f 63 6b 20 6f 66 to a block of
17840 20 63 68 65 63 6b 65 64 2d 6f 75 74 20 6d 65 6d checked-out mem
17850 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20 ory of at least
17860 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 0a N bytes in size.
17870 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 61 ** tha
17880 74 20 69 73 20 38 2d 62 79 74 65 20 61 6c 69 67 t is 8-byte alig
17890 6e 65 64 2c 20 6f 72 20 61 20 4e 55 4c 4c 20 70 ned, or a NULL p
178a0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ointer..**.** {H
178b0 31 37 33 32 31 7d 20 20 57 68 65 6e 20 5b 73 71 17321} When [sq
178c0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c lite3_realloc(P,
178d0 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 20 6e 6f N)] returns a no
178e0 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 n-NULL pointer,
178f0 69 74 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 it first.**
17900 20 20 20 20 20 20 63 6f 70 69 65 73 20 74 68 65 copies the
17910 20 66 69 72 73 74 20 4b 20 62 79 74 65 73 20 6f first K bytes o
17920 66 20 63 6f 6e 74 65 6e 74 20 66 72 6f 6d 20 50 f content from P
17930 20 69 6e 74 6f 20 74 68 65 20 6e 65 77 6c 79 0a into the newly.
17940 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 6c 6c ** all
17950 6f 63 61 74 65 64 20 62 6c 6f 63 6b 2c 20 77 68 ocated block, wh
17960 65 72 65 20 4b 20 69 73 20 74 68 65 20 6c 65 73 ere K is the les
17970 73 65 72 20 6f 66 20 4e 20 61 6e 64 20 74 68 65 ser of N and the
17980 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 20 20 20 20 size of.**
17990 20 20 20 20 20 20 74 68 65 20 62 75 66 66 65 72 the buffer
179a0 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32 P..**.** {H1732
179b0 32 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 2} When [sqlite
179c0 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 3_realloc(P,N)]
179d0 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 returns a non-NU
179e0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74 20 66 LL pointer, it f
179f0 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 irst.**
17a00 20 20 72 65 6c 65 61 73 65 73 20 74 68 65 20 62 releases the b
17a10 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b uffer P..**.** {
17a20 48 31 37 33 32 33 7d 20 20 57 68 65 6e 20 5b 73 H17323} When [s
17a30 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 qlite3_realloc(P
17a40 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 4e 55 4c ,N)] returns NUL
17a50 4c 2c 20 74 68 65 20 62 75 66 66 65 72 20 50 20 L, the buffer P
17a60 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 is.**
17a70 6e 6f 74 20 6d 6f 64 69 66 69 65 64 20 6f 72 20 not modified or
17a80 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 released..**.**
17a90 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a ASSUMPTIONS:.**.
17aa0 2a 2a 20 7b 41 31 37 33 35 30 7d 20 20 54 68 65 ** {A17350} The
17ab0 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e pointer argumen
17ac0 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 ts to [sqlite3_f
17ad0 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 ree()] and [sqli
17ae0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a te3_realloc()].*
17af0 2a 20 20 20 20 20 20 20 20 20 20 20 6d 75 73 74 * must
17b00 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 be either NULL
17b10 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 or else pointers
17b20 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 obtained from a
17b30 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 prior.**
17b40 20 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f invocation o
17b50 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f f [sqlite3_mallo
17b60 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 c()] or [sqlite3
17b70 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 _realloc()] that
17b80 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 have.**
17b90 20 20 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 not yet been
17ba0 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 released..**.**
17bb0 7b 41 31 37 33 35 31 7d 20 20 54 68 65 20 61 70 {A17351} The ap
17bc0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e plication must n
17bd0 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 ot read or write
17be0 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 any part of.**
17bf0 20 20 20 20 20 20 20 20 20 20 61 20 62 6c 6f 63 a bloc
17c00 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 k of memory afte
17c10 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 r it has been re
17c20 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 leased using.**
17c30 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
17c40 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 e3_free()] or [s
17c50 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
17c60 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 ]..*/.void *sqli
17c70 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b te3_malloc(int);
17c80 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 .void *sqlite3_r
17c90 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e ealloc(void*, in
17ca0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 t);.void sqlite3
17cb0 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f _free(void*);../
17cc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
17cd0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 emory Allocator
17ce0 53 74 61 74 69 73 74 69 63 73 20 7b 48 31 37 33 Statistics {H173
17cf0 37 30 7d 20 3c 53 33 30 32 31 30 3e 0a 2a 2a 0a 70} <S30210>.**.
17d00 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 ** SQLite provid
17d10 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 es these two int
17d20 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f erfaces for repo
17d30 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 rting on the sta
17d40 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 tus.** of the [s
17d50 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
17d60 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 , [sqlite3_free(
17d70 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 )], and [sqlite3
17d80 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 _realloc()].** r
17d90 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 outines, which f
17da0 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e orm the built-in
17db0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
17dc0 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a on subsystem..**
17dd0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
17de0 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 31 7d 20 54 **.** {H17371} T
17df0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f he [sqlite3_memo
17e00 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 ry_used()] routi
17e10 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e ne returns the n
17e20 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a umber of bytes.*
17e30 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 6d 65 * of me
17e40 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f mory currently o
17e50 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c utstanding (mall
17e60 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 oced but not fre
17e70 65 64 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 ed)..**.** {H173
17e80 37 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 73} The [sqlite3
17e90 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 _memory_highwate
17ea0 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 r()] routine ret
17eb0 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d urns the maximum
17ec0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c .** val
17ed0 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d ue of [sqlite3_m
17ee0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 emory_used()] si
17ef0 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 nce the high-wat
17f00 65 72 20 6d 61 72 6b 0a 2a 2a 20 20 20 20 20 20 er mark.**
17f10 20 20 20 20 77 61 73 20 6c 61 73 74 20 72 65 73 was last res
17f20 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 et..**.** {H1737
17f30 34 7d 20 54 68 65 20 76 61 6c 75 65 73 20 72 65 4} The values re
17f40 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
17f50 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 e3_memory_used()
17f60 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 ] and.**
17f70 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 [sqlite3_memor
17f80 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 y_highwater()] i
17f90 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 nclude any overh
17fa0 65 61 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ead.**
17fb0 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 added by SQLite
17fc0 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 in its implement
17fd0 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 ation of [sqlite
17fe0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 3_malloc()],.**
17ff0 20 20 20 20 20 20 20 20 20 62 75 74 20 6e 6f 74 but not
18000 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 overhead added
18010 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 by the any under
18020 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 lying system lib
18030 72 61 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 rary.**
18040 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b routines that [
18050 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
18060 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a ] may call..**.*
18070 2a 20 7b 48 31 37 33 37 35 7d 20 54 68 65 20 6d * {H17375} The m
18080 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 emory high-water
18090 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 mark is reset t
180a0 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 o the current va
180b0 6c 75 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 lue of.**
180c0 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f [sqlite3_memo
180d0 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e ry_used()] if an
180e0 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 d only if the pa
180f0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 rameter to.**
18100 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
18110 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
18120 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 54 68 ()] is true. Th
18130 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
18140 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20 .** by
18150 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
18160 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 highwater(1)] is
18170 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 the high-water
18180 6d 61 72 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 mark.**
18190 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 prior to the re
181a0 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f set..*/.sqlite3_
181b0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 int64 sqlite3_me
181c0 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b mory_used(void);
181d0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 .sqlite3_int64 s
181e0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
181f0 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 ghwater(int rese
18200 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 tFlag);../*.** C
18210 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d API3REF: Pseudo-
18220 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 Random Number Ge
18230 6e 65 72 61 74 6f 72 20 7b 48 31 37 33 39 30 7d nerator {H17390}
18240 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S20000>.**.**
18250 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 SQLite contains
18260 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 a high-quality p
18270 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d seudo-random num
18280 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 ber generator (P
18290 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 RNG) used to.**
182a0 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 52 4f select random RO
182b0 57 49 44 73 20 77 68 65 6e 20 69 6e 73 65 72 74 WIDs when insert
182c0 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 ing new records
182d0 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 into a table tha
182e0 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 t.** already use
182f0 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f s the largest po
18300 73 73 69 62 6c 65 20 52 4f 57 49 44 2e 20 20 54 ssible ROWID. T
18310 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 he PRNG is also
18320 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 used for.** the
18330 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 build-in random(
18340 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 ) and randomblob
18350 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 () SQL functions
18360 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 . This interfac
18370 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c e allows.** appl
18380 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 ications to acce
18390 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 ss the same PRNG
183a0 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f for other purpo
183b0 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c ses..**.** A cal
183c0 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e l to this routin
183d0 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 e stores N bytes
183e0 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 of randomness i
183f0 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a nto buffer P..**
18400 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 74 69 .** The first ti
18410 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 me this routine
18420 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 is invoked (eith
18430 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 er internally or
18440 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 by.** the appli
18450 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 cation) the PRNG
18460 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 is seeded using
18470 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 randomness obta
18480 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 ined.** from the
18490 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 xRandomness met
184a0 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 hod of the defau
184b0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d lt [sqlite3_vfs]
184c0 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 4f 6e 20 61 object..** On a
184d0 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e ll subsequent in
184e0 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 vocations, the p
184f0 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 seudo-randomness
18500 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a is generated.**
18510 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 internally and
18520 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 without recourse
18530 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
18540 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 _vfs] xRandomnes
18550 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a s.** method..**.
18560 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
18570 2a 0a 2a 2a 20 7b 48 31 37 33 39 32 7d 20 54 68 *.** {H17392} Th
18580 65 20 5b 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f e [sqlite3_rando
18590 6d 6e 65 73 73 28 4e 2c 50 29 5d 20 69 6e 74 65 mness(N,P)] inte
185a0 72 66 61 63 65 20 77 72 69 74 65 73 20 4e 20 62 rface writes N b
185b0 79 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 ytes of.**
185c0 20 20 20 20 68 69 67 68 2d 71 75 61 6c 69 74 79 high-quality
185d0 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 pseudo-randomne
185e0 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 ss into buffer P
185f0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 ..*/.void sqlite
18600 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 3_randomness(int
18610 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f N, void *P);../
18620 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
18630 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 ompile-Time Auth
18640 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 orization Callba
18650 63 6b 73 20 7b 48 31 32 35 30 30 7d 20 3c 53 37 cks {H12500} <S7
18660 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 0100>.**.** This
18670 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 routine registe
18680 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20 rs a authorizer
18690 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 callback with a
186a0 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 particular.** [d
186b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
186c0 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e on], supplied in
186d0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
186e0 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 ent..** The auth
186f0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
18700 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 is invoked as SQ
18710 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 L statements are
18720 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a being compiled.
18730 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 ** by [sqlite3_p
18740 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 repare()] or its
18750 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 variants [sqlit
18760 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
18770 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 ,.** [sqlite3_pr
18780 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b epare16()] and [
18790 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
187a0 36 5f 76 32 28 29 5d 2e 20 20 41 74 20 76 61 72 6_v2()]. At var
187b0 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 ious.** points d
187c0 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c uring the compil
187d0 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 ation process, a
187e0 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 s logic is being
187f0 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 created.** to p
18800 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 erform various a
18810 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 ctions, the auth
18820 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
18830 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a is invoked to.**
18840 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 see if those ac
18850 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 tions are allowe
18860 64 2e 20 20 54 68 65 20 61 75 74 68 6f 72 69 7a d. The authoriz
18870 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 er callback shou
18880 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 ld.** return [SQ
18890 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f LITE_OK] to allo
188a0 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 w the action, [S
188b0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f QLITE_IGNORE] to
188c0 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a disallow the.**
188d0 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e specific action
188e0 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 but allow the S
188f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 QL statement to
18900 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a continue to be.*
18910 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b * compiled, or [
18920 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 SQLITE_DENY] to
18930 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 cause the entire
18940 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
18950 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 o be.** rejected
18960 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 with an error.
18970 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a If the authoriz
18980 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 er callback retu
18990 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 rns.** any value
189a0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c other than [SQL
189b0 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 ITE_IGNORE], [SQ
189c0 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 LITE_OK], or [SQ
189d0 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 LITE_DENY].** th
189e0 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f en the [sqlite3_
189f0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
18a00 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c equivalent call
18a10 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a that triggered.
18a20 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 ** the authorize
18a30 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 r will fail with
18a40 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 an error messag
18a50 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 e..**.** When th
18a60 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 e callback retur
18a70 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 ns [SQLITE_OK],
18a80 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f that means the o
18a90 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 peration.** requ
18aa0 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 57 68 ested is ok. Wh
18ab0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 en the callback
18ac0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
18ad0 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 DENY], the.** [s
18ae0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
18af0 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 2()] or equivale
18b00 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 nt call that tri
18b10 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 ggered the.** au
18b20 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 thorizer will fa
18b30 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 il with an error
18b40 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e message explain
18b50 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 ing that.** acce
18b60 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 20 49 ss is denied. I
18b70 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 f the authorizer
18b80 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 code is [SQLITE
18b90 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 _READ].** and th
18ba0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 e callback retur
18bb0 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 ns [SQLITE_IGNOR
18bc0 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b E] then the.** [
18bd0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
18be0 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 nt] statement is
18bf0 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 constructed to
18c00 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 substitute.** a
18c10 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c NULL value in pl
18c20 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 ace of the table
18c30 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 column that wou
18c40 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 ld have.** been
18c50 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f read if [SQLITE_
18c60 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 OK] had been ret
18c70 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c urned. The [SQL
18c80 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 ITE_IGNORE].** r
18c90 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 eturn can be use
18ca0 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 d to deny an unt
18cb0 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 rusted user acce
18cc0 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c ss to individual
18cd0 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 .** columns of a
18ce0 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 table..**.** Th
18cf0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
18d00 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 r to the authori
18d10 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 zer callback is
18d20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 a copy of the th
18d30 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ird.** parameter
18d40 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
18d50 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 set_authorizer()
18d60 20 69 6e 74 65 72 66 61 63 65 2e 20 54 68 65 20 interface. The
18d70 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
18d80 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 .** to the callb
18d90 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 ack is an intege
18da0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c r [SQLITE_COPY |
18db0 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 action code] th
18dc0 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 at specifies.**
18dd0 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 the particular a
18de0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 ction to be auth
18df0 6f 72 69 7a 65 64 2e 20 54 68 65 20 74 68 69 72 orized. The thir
18e00 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 d through sixth
18e10 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f parameters.** to
18e20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 the callback ar
18e30 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 e zero-terminate
18e40 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 d strings that c
18e50 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 ontain additiona
18e60 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f l.** details abo
18e70 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f ut the action to
18e80 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a be authorized..
18e90 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 **.** An authori
18ea0 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e zer is used when
18eb0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
18ec0 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a e | preparing].*
18ed0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 * SQL statements
18ee0 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 from an untrust
18ef0 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e ed source, to en
18f00 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 sure that the SQ
18f10 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 L statements.**
18f20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 do not try to ac
18f30 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61 cess data they a
18f40 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 re not allowed t
18f50 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 o see, or that t
18f60 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 hey do not.** tr
18f70 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c y to execute mal
18f80 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 icious statement
18f90 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 s that damage th
18fa0 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 e database. For
18fb0 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 .** example, an
18fc0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 application may
18fd0 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 allow a user to
18fe0 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a enter arbitrary.
18ff0 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 ** SQL queries f
19000 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 or evaluation by
19010 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 a database. Bu
19020 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f t the applicatio
19030 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 n does.** not wa
19040 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 nt the user to b
19050 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 e able to make a
19060 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 rbitrary changes
19070 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 to the.** datab
19080 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 ase. An authori
19090 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 zer could then b
190a0 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 e put in place w
190b0 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 hile the.** user
190c0 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 -entered SQL is
190d0 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 being [sqlite3_p
190e0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 repare | prepare
190f0 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c d] that.** disal
19100 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 lows everything
19110 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 except [SELECT]
19120 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a statements..**.*
19130 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 * Applications t
19140 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 hat need to proc
19150 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 ess SQL from unt
19160 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a rusted sources.*
19170 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e * might also con
19180 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 sider lowering r
19190 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 esource limits u
191a0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 sing [sqlite3_li
191b0 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 mit()].** and li
191c0 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 miting database
191d0 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b size using the [
191e0 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 max_page_count]
191f0 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 [PRAGMA].** in a
19200 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 ddition to using
19210 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a an authorizer..
19220 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e **.** Only a sin
19230 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 gle authorizer c
19240 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f an be in place o
19250 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e n a database con
19260 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 nection.** at a
19270 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c time. Each call
19280 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f to sqlite3_set_
19290 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 authorizer overr
192a0 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 ides the.** prev
192b0 69 6f 75 73 20 63 61 6c 6c 2e 20 20 44 69 73 61 ious call. Disa
192c0 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a ble the authoriz
192d0 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 er by installing
192e0 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b a NULL callback
192f0 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 ..** The authori
19300 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 zer is disabled
19310 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a by default..**.*
19320 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 * The authorizer
19330 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e callback must n
19340 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 ot do anything t
19350 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a hat will modify.
19360 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ** the database
19370 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 connection that
19380 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 invoked the auth
19390 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e orizer callback.
193a0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 .** Note that [s
193b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
193c0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 2()] and [sqlite
193d0 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 3_step()] both m
193e0 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 odify their.** d
193f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
19400 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e ons for the mean
19410 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 ing of "modify"
19420 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 in this paragrap
19430 68 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 5b 73 h..**.** When [s
19440 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
19450 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 2()] is used to
19460 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d prepare a statem
19470 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 ent, the.** stat
19480 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 ement might be r
19490 65 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 eprepared during
194a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
194b0 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 ] due to a .** s
194c0 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 chema change. H
194d0 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 ence, the applic
194e0 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 ation should ens
194f0 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 ure that the.**
19500 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a correct authoriz
19510 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 er callback rema
19520 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 ins in place dur
19530 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 ing the [sqlite3
19540 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 _step()]..**.**
19550 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 Note that the au
19560 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
19570 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c k is invoked onl
19580 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c y during.** [sql
19590 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
195a0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e or its variants.
195b0 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 Authorization
195c0 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 is not.** perfor
195d0 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 med during state
195e0 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 ment evaluation
195f0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 in [sqlite3_step
19600 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 ()]..**.** INVAR
19610 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 IANTS:.**.** {H1
19620 32 35 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 2501} The [sqlit
19630 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
19640 72 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 r(D,...)] interf
19650 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 0a ace registers a.
19660 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 68 ** auth
19670 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
19680 77 69 74 68 20 64 61 74 61 62 61 73 65 20 63 6f with database co
19690 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a nnection D..**.*
196a0 2a 20 7b 48 31 32 35 30 32 7d 20 54 68 65 20 61 * {H12502} The a
196b0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
196c0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 ck is invoked as
196d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
196e0 61 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 are.**
196f0 62 65 69 6e 67 20 70 61 72 73 65 65 64 20 61 6e being parseed an
19700 64 20 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a d compiled..**.*
19710 2a 20 7b 48 31 32 35 30 33 7d 20 49 66 20 74 68 * {H12503} If th
19720 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
19730 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 6e lback returns an
19740 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 y value other th
19750 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b an.** [
19760 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 SQLITE_IGNORE],
19770 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 [SQLITE_OK], or
19780 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 [SQLITE_DENY], t
19790 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 hen.**
197a0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
197b0 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 74 interface call t
197c0 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 20 20 hat caused.**
197d0 20 20 20 20 20 20 20 74 68 65 20 61 75 74 68 6f the autho
197e0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 74 rizer callback t
197f0 6f 20 72 75 6e 20 73 68 61 6c 6c 20 66 61 69 6c o run shall fail
19800 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 with an.**
19810 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 [SQLITE_ERR
19820 4f 52 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61 OR] error code a
19830 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 nd an appropriat
19840 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e e error message.
19850 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 34 7d 20 .**.** {H12504}
19860 57 68 65 6e 20 74 68 65 20 61 75 74 68 6f 72 69 When the authori
19870 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 zer callback ret
19880 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d urns [SQLITE_OK]
19890 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a , the operation.
198a0 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 73 63 ** desc
198b0 72 69 62 65 64 20 69 73 20 70 72 6f 63 65 73 73 ribed is process
198c0 65 64 20 6e 6f 72 6d 61 6c 6c 79 2e 0a 2a 2a 0a ed normally..**.
198d0 2a 2a 20 7b 48 31 32 35 30 35 7d 20 57 68 65 6e ** {H12505} When
198e0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
198f0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
19900 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 [SQLITE_DENY],
19910 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
19920 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 74 65 application inte
19930 72 66 61 63 65 20 63 61 6c 6c 20 74 68 61 74 20 rface call that
19940 63 61 75 73 65 64 20 74 68 65 0a 2a 2a 20 20 20 caused the.**
19950 20 20 20 20 20 20 20 61 75 74 68 6f 72 69 7a 65 authorize
19960 72 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75 r callback to ru
19970 6e 20 73 68 61 6c 6c 20 66 61 69 6c 0a 2a 2a 20 n shall fail.**
19980 20 20 20 20 20 20 20 20 20 77 69 74 68 20 61 6e with an
19990 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
199a0 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 error code and a
199b0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a n error message.
199c0 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78 70 6c ** expl
199d0 61 69 6e 69 6e 67 20 74 68 61 74 20 61 63 63 65 aining that acce
199e0 73 73 20 69 73 20 64 65 6e 69 65 64 2e 0a 2a 2a ss is denied..**
199f0 0a 2a 2a 20 7b 48 31 32 35 30 36 7d 20 49 66 20 .** {H12506} If
19a00 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
19a10 6f 64 65 20 28 74 68 65 20 32 6e 64 20 70 61 72 ode (the 2nd par
19a20 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 ameter to the au
19a30 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20 thorizer.**
19a40 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69 callback) i
19a50 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20 s [SQLITE_READ]
19a60 61 6e 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a and the authoriz
19a70 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 er callback retu
19a80 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 rns.**
19a90 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c [SQLITE_IGNORE],
19aa0 20 74 68 65 6e 20 74 68 65 20 70 72 65 70 61 72 then the prepar
19ab0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 ed statement is
19ac0 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 0a 2a constructed to.*
19ad0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 73 65 72 * inser
19ae0 74 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 t a NULL value i
19af0 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 n place of the t
19b00 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 able column that
19b10 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 20 would have.**
19b20 20 20 20 20 20 20 20 20 62 65 65 6e 20 72 65 61 been rea
19b30 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d d if [SQLITE_OK]
19b40 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e had been return
19b50 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 ed..**.** {H1250
19b60 37 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 7} If the author
19b70 69 7a 65 72 20 63 6f 64 65 20 28 74 68 65 20 32 izer code (the 2
19b80 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 nd parameter to
19b90 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a the authorizer.*
19ba0 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 * callb
19bb0 61 63 6b 29 20 69 73 20 61 6e 79 74 68 69 6e 67 ack) is anything
19bc0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c other than [SQL
19bd0 49 54 45 5f 52 45 41 44 5d 2c 20 74 68 65 6e 0a ITE_READ], then.
19be0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 72 65 ** a re
19bf0 74 75 72 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f turn of [SQLITE_
19c00 49 47 4e 4f 52 45 5d 20 68 61 73 20 74 68 65 20 IGNORE] has the
19c10 73 61 6d 65 20 65 66 66 65 63 74 20 61 73 20 5b same effect as [
19c20 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2e 0a 2a 2a SQLITE_DENY]..**
19c30 0a 2a 2a 20 7b 48 31 32 35 31 30 7d 20 54 68 65 .** {H12510} The
19c40 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
19c50 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a to the authoriz
19c60 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 er callback is a
19c70 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 copy of.**
19c80 20 20 20 20 20 74 68 65 20 74 68 69 72 64 20 70 the third p
19c90 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
19ca0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 [sqlite3_set_aut
19cb0 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 horizer()] inter
19cc0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 face..**.** {H12
19cd0 35 31 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 511} The second
19ce0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
19cf0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 callback is an
19d00 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 integer.**
19d10 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 [SQLITE_COPY
19d20 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 | action code]
19d30 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74 that specifies t
19d40 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 he particular ac
19d50 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 tion.**
19d60 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 to be authorize
19d70 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31 32 d..**.** {H12512
19d80 7d 20 54 68 65 20 74 68 69 72 64 20 74 68 72 6f } The third thro
19d90 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 ugh sixth parame
19da0 74 65 72 73 20 74 6f 20 74 68 65 20 63 61 6c 6c ters to the call
19db0 62 61 63 6b 20 61 72 65 0a 2a 2a 20 20 20 20 20 back are.**
19dc0 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e zero-termin
19dd0 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 ated strings tha
19de0 74 20 63 6f 6e 74 61 69 6e 0a 2a 2a 20 20 20 20 t contain.**
19df0 20 20 20 20 20 20 61 64 64 69 74 69 6f 6e 61 6c additional
19e00 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 details about t
19e10 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 he action to be
19e20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a authorized..**.*
19e30 2a 20 7b 48 31 32 35 32 30 7d 20 45 61 63 68 20 * {H12520} Each
19e40 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
19e50 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 _set_authorizer(
19e60 29 5d 20 6f 76 65 72 72 69 64 65 73 0a 2a 2a 20 )] overrides.**
19e70 20 20 20 20 20 20 20 20 20 61 6e 79 20 70 72 65 any pre
19e80 76 69 6f 75 73 6c 79 20 69 6e 73 74 61 6c 6c 65 viously installe
19e90 64 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a d authorizer..**
19ea0 0a 2a 2a 20 7b 48 31 32 35 32 31 7d 20 41 20 4e .** {H12521} A N
19eb0 55 4c 4c 20 61 75 74 68 6f 72 69 7a 65 72 20 6d ULL authorizer m
19ec0 65 61 6e 73 20 74 68 61 74 20 6e 6f 20 61 75 74 eans that no aut
19ed0 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 20 20 horization.**
19ee0 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 callback
19ef0 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a is invoked..**.*
19f00 2a 20 7b 48 31 32 35 32 32 7d 20 54 68 65 20 64 * {H12522} The d
19f10 65 66 61 75 6c 74 20 61 75 74 68 6f 72 69 7a 65 efault authorize
19f20 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e r is NULL..*/.in
19f30 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 t sqlite3_set_au
19f40 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 thorizer(. sqli
19f50 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 te3*,. int (*xA
19f60 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 uth)(void*,int,c
19f70 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 onst char*,const
19f80 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 char*,const cha
19f90 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c r*,const char*),
19fa0 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 . void *pUserDa
19fb0 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ta.);../*.** CAP
19fc0 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 I3REF: Authorize
19fd0 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 20 7b r Return Codes {
19fe0 48 31 32 35 39 30 7d 20 3c 48 31 32 35 30 30 3e H12590} <H12500>
19ff0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 .**.** The [sqli
1a000 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
1a010 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 er | authorizer
1a020 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
1a030 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 n] must.** retur
1a040 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 n either [SQLITE
1a050 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 _OK] or one of t
1a060 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e hese two constan
1a070 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 ts in order.** t
1a080 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 o signal SQLite
1a090 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 whether or not t
1a0a0 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 he action is per
1a0b0 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 mitted. See the
1a0c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 .** [sqlite3_set
1a0d0 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 _authorizer | au
1a0e0 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e thorizer documen
1a0f0 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 tation] for addi
1a100 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d tional.** inform
1a110 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e ation..*/.#defin
1a120 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 e SQLITE_DENY
1a130 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 1 /* Abort the
1a140 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 SQL statement w
1a150 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a ith an error */.
1a160 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
1a170 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e GNORE 2 /* Don
1a180 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 't allow access,
1a190 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 but don't gener
1a1a0 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a ate an error */.
1a1b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1a1c0 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 Authorizer Acti
1a1d0 6f 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 35 30 on Codes {H12550
1a1e0 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a } <H12500>.**.**
1a1f0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 The [sqlite3_se
1a200 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 t_authorizer()]
1a210 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 interface regist
1a220 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 ers a callback f
1a230 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 unction.** that
1a240 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 is invoked to au
1a250 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 thorize certain
1a260 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 SQL statement ac
1a270 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 tions. The.** s
1a280 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
1a290 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
1a2a0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f is an integer co
1a2b0 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 de that specifie
1a2c0 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e s.** what action
1a2d0 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 is being author
1a2e0 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 ized. These are
1a2f0 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 the integer act
1a300 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a ion codes that.*
1a310 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 * the authorizer
1a320 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 callback may be
1a330 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 passed..**.** T
1a340 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 hese action code
1a350 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 values signify
1a360 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 what kind of ope
1a370 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a ration is to be.
1a380 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 ** authorized.
1a390 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 The 3rd and 4th
1a3a0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 parameters to th
1a3b0 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a e authorization.
1a3c0 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 ** callback func
1a3d0 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 tion will be par
1a3e0 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 ameters or NULL
1a3f0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 depending on whi
1a400 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 ch of these.** c
1a410 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 odes is used as
1a420 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
1a430 65 74 65 72 2e 20 20 54 68 65 20 35 74 68 20 70 eter. The 5th p
1a440 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a arameter to the.
1a450 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 ** authorizer ca
1a460 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 llback is the na
1a470 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 me of the databa
1a480 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d se ("main", "tem
1a490 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 p",.** etc.) if
1a4a0 61 70 70 6c 69 63 61 62 6c 65 2e 20 20 54 68 65 applicable. The
1a4b0 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6th parameter t
1a4c0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 o the authorizer
1a4d0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 callback.** is
1a4e0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
1a4f0 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 inner-most trigg
1a500 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 er or view that
1a510 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 is responsible f
1a520 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 or.** the access
1a530 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c attempt or NULL
1a540 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 if this access
1a550 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 attempt is direc
1a560 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d tly from.** top-
1a570 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a level SQL code..
1a580 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
1a590 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 31 7d :.**.** {H12551}
1a5a0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 The second para
1a5b0 6d 65 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 20 meter to an.**
1a5c0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
1a5d0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 _set_authorizer
1a5e0 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c | authorizer cal
1a5f0 6c 62 61 63 6b 5d 20 73 68 61 6c 6c 20 62 65 20 lback] shall be
1a600 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20 an integer.**
1a610 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 [SQLITE_C
1a620 4f 50 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 OPY | authorizer
1a630 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 code] that spec
1a640 69 66 69 65 73 20 77 68 61 74 20 61 63 74 69 6f ifies what actio
1a650 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 n.** is
1a660 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 being authorize
1a670 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 32 d..**.** {H12552
1a680 7d 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 } The 3rd and 4t
1a690 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 h parameters to
1a6a0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
1a6b0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 [sqlite3_set_aut
1a6c0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 horizer | author
1a6d0 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b ization callback
1a6e0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 ].** sh
1a6f0 61 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 all be parameter
1a700 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 s or NULL depend
1a710 69 6e 67 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 ing on which.**
1a720 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 [SQLITE
1a730 5f 43 4f 50 59 20 7c 20 61 75 74 68 6f 72 69 7a _COPY | authoriz
1a740 65 72 20 63 6f 64 65 5d 20 69 73 20 75 73 65 64 er code] is used
1a750 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 as the second p
1a760 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 arameter..**.**
1a770 7b 48 31 32 35 35 33 7d 20 54 68 65 20 35 74 68 {H12553} The 5th
1a780 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
1a790 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 e.** [s
1a7a0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
1a7b0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a rizer | authoriz
1a7c0 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 73 68 61 er callback] sha
1a7d0 6c 6c 20 62 65 20 74 68 65 20 6e 61 6d 65 0a 2a ll be the name.*
1a7e0 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 * of th
1a7f0 65 20 64 61 74 61 62 61 73 65 20 28 65 78 61 6d e database (exam
1a800 70 6c 65 3a 20 22 6d 61 69 6e 22 2c 20 22 74 65 ple: "main", "te
1a810 6d 70 22 2c 20 65 74 63 2e 29 20 69 66 20 61 70 mp", etc.) if ap
1a820 70 6c 69 63 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 plicable..**.**
1a830 7b 48 31 32 35 35 34 7d 20 54 68 65 20 36 74 68 {H12554} The 6th
1a840 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
1a850 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 e.** [s
1a860 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
1a870 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a rizer | authoriz
1a880 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 73 68 61 er callback] sha
1a890 6c 6c 20 62 65 20 74 68 65 20 6e 61 6d 65 0a 2a ll be the name.*
1a8a0 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 * of th
1a8b0 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 e inner-most tri
1a8c0 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 gger or view tha
1a8d0 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 t is responsible
1a8e0 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 for.**
1a8f0 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 the access atte
1a900 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 mpt or NULL if t
1a910 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d his access attem
1a920 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 pt is directly f
1a930 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 rom.**
1a940 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f top-level SQL co
1a950 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a de..*/./********
1a960 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1a970 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1a980 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a *** 3rd ********
1a990 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a **** 4th *******
1a9a0 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ****/.#define SQ
1a9b0 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 LITE_CREATE_INDE
1a9c0 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f X 1 /
1a9d0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 * Index Name
1a9e0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
1a9f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1aa00 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 ITE_CREATE_TABLE
1aa10 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 2 /*
1aa20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
1aa30 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
1aa40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1aa50 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 TE_CREATE_TEMP_I
1aa60 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 NDEX 3 /*
1aa70 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 Index Name
1aa80 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
1aa90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1aaa0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 E_CREATE_TEMP_TA
1aab0 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 BLE 4 /* T
1aac0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
1aad0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
1aae0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1aaf0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 _CREATE_TEMP_TRI
1ab00 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 GGER 5 /* Tr
1ab10 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 igger Name Ta
1ab20 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
1ab30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1ab40 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 CREATE_TEMP_VIEW
1ab50 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 6 /* Vie
1ab60 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c w Name NUL
1ab70 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
1ab80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
1ab90 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 REATE_TRIGGER
1aba0 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 7 /* Trig
1abb0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c ger Name Tabl
1abc0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
1abd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
1abe0 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 EATE_VIEW
1abf0 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 8 /* View
1ac00 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
1ac10 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
1ac20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c efine SQLITE_DEL
1ac30 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 ETE
1ac40 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 9 /* Table
1ac50 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
1ac60 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
1ac70 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
1ac80 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 _INDEX
1ac90 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 10 /* Index N
1aca0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e ame Table N
1acb0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
1acc0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
1acd0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 TABLE
1ace0 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 11 /* Table Na
1acf0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
1ad00 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
1ad10 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
1ad20 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 EMP_INDEX 1
1ad30 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 2 /* Index Nam
1ad40 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d e Table Nam
1ad50 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
1ad60 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 e SQLITE_DROP_TE
1ad70 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 MP_TABLE 13
1ad80 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
1ad90 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
1ada0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1adb0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d SQLITE_DROP_TEM
1adc0 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 P_TRIGGER 14
1add0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d /* Trigger Nam
1ade0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 e Table Name
1adf0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1ae00 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 SQLITE_DROP_TEMP
1ae10 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 _VIEW 15
1ae20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 /* View Name
1ae30 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
1ae40 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1ae50 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 QLITE_DROP_TRIGG
1ae60 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 ER 16
1ae70 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 /* Trigger Name
1ae80 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
1ae90 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1aea0 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 LITE_DROP_VIEW
1aeb0 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 17 /
1aec0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 * View Name
1aed0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
1aee0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1aef0 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 ITE_INSERT
1af00 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 18 /*
1af10 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
1af20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
1af30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1af40 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 TE_PRAGMA
1af50 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 19 /*
1af60 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 Pragma Name
1af70 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 1st arg or NULL
1af80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1af90 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 E_READ
1afa0 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 20 /* T
1afb0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 able Name C
1afc0 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a olumn Name *
1afd0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1afe0 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 _SELECT
1aff0 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 21 /* NU
1b000 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 LL NU
1b010 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
1b020 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1b030 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 TRANSACTION
1b040 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4e 55 4c 22 /* NUL
1b050 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c L NUL
1b060 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
1b070 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 #define SQLITE_U
1b080 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 PDATE
1b090 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 23 /* Tabl
1b0a0 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 e Name Colu
1b0b0 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 mn Name */.#
1b0c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 define SQLITE_AT
1b0d0 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 TACH
1b0e0 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 24 /* Filen
1b0f0 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 ame NULL
1b100 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
1b110 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 efine SQLITE_DET
1b120 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 ACH
1b130 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 25 /* Databa
1b140 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 se Name NULL
1b150 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
1b160 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 fine SQLITE_ALTE
1b170 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 R_TABLE
1b180 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 26 /* Databas
1b190 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e e Name Table N
1b1a0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
1b1b0 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 ine SQLITE_REIND
1b1c0 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 EX
1b1d0 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 27 /* Index Na
1b1e0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
1b1f0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
1b200 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a ne SQLITE_ANALYZ
1b210 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 E 2
1b220 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 8 /* Table Nam
1b230 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
1b240 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
1b250 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
1b260 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 VTABLE 29
1b270 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
1b280 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d Module Nam
1b290 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 e */.#define
1b2a0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 SQLITE_DROP_VTA
1b2b0 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 BLE 30
1b2c0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
1b2d0 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 Module Name
1b2e0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1b2f0 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 SQLITE_FUNCTION
1b300 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 31
1b310 20 2f 2a 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d /* Function Nam
1b320 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 e NULL
1b330 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1b340 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 QLITE_COPY
1b350 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 0
1b360 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 /* No longer use
1b370 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d */../*.** CAPI
1b380 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 3REF: Tracing An
1b390 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 d Profiling Func
1b3a0 74 69 6f 6e 73 20 7b 48 31 32 32 38 30 7d 20 3c tions {H12280} <
1b3b0 53 36 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 S60400>.** EXPER
1b3c0 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 IMENTAL.**.** Th
1b3d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 ese routines reg
1b3e0 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 ister callback f
1b3f0 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 unctions that ca
1b400 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a n be used for.**
1b410 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f tracing and pro
1b420 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 filing the execu
1b430 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 tion of SQL stat
1b440 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 ements..**.** Th
1b450 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
1b460 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 ion registered b
1b470 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 y sqlite3_trace(
1b480 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a ) is invoked at.
1b490 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 ** various times
1b4a0 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 when an SQL sta
1b4b0 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 tement is being
1b4c0 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f run by [sqlite3_
1b4d0 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 step()]..** The
1b4e0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
1b4f0 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 a UTF-8 renderi
1b500 6e 67 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 ng of the SQL st
1b510 61 74 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a 20 atement text.**
1b520 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 as the statement
1b530 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 first begins ex
1b540 65 63 75 74 69 6e 67 2e 20 20 41 64 64 69 74 69 ecuting. Additi
1b550 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 6f onal callbacks o
1b560 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 ccur.** as each
1b570 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f triggered subpro
1b580 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e gram is entered.
1b590 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 The callbacks
1b5a0 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 for triggers.**
1b5b0 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 contain a UTF-8
1b5c0 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 SQL comment that
1b5d0 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 identifies the
1b5e0 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 trigger..**.** T
1b5f0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 he callback func
1b600 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 tion registered
1b610 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 by sqlite3_profi
1b620 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a le() is invoked.
1b630 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 ** as each SQL s
1b640 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 tatement finishe
1b650 73 2e 20 20 54 68 65 20 70 72 6f 66 69 6c 65 20 s. The profile
1b660 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e callback contain
1b670 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 s.** the origina
1b680 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 l statement text
1b690 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 and an estimate
1b6a0 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 of wall-clock t
1b6b0 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f ime.** of how lo
1b6c0 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e ng that statemen
1b6d0 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a t took to run..*
1b6e0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
1b6f0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 31 7d 20 .**.** {H12281}
1b700 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e The callback fun
1b710 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 ction registered
1b720 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 by [sqlite3_tra
1b730 63 65 28 29 5d 20 0a 2a 2a 20 20 20 20 20 20 20 ce()] .**
1b740 20 20 20 73 68 61 6c 6c 20 62 65 20 69 6e 76 6f shall be invo
1b750 6b 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ked.**
1b760 77 68 65 6e 65 76 65 72 20 61 6e 20 53 51 4c 20 whenever an SQL
1b770 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 statement first
1b780 62 65 67 69 6e 73 20 74 6f 20 65 78 65 63 75 74 begins to execut
1b790 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 e and.**
1b7a0 20 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 69 whenever a tri
1b7b0 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 20 gger subprogram
1b7c0 66 69 72 73 74 20 62 65 67 69 6e 73 20 74 6f 20 first begins to
1b7d0 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 run..**.** {H122
1b7e0 38 32 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 82} Each call to
1b7f0 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 [sqlite3_trace(
1b800 29 5d 20 73 68 61 6c 6c 20 6f 76 65 72 72 69 64 )] shall overrid
1b810 65 20 74 68 65 20 70 72 65 76 69 6f 75 73 6c 79 e the previously
1b820 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 .** reg
1b830 69 73 74 65 72 65 64 20 74 72 61 63 65 20 63 61 istered trace ca
1b840 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 llback..**.** {H
1b850 31 32 32 38 33 7d 20 41 20 4e 55 4c 4c 20 74 72 12283} A NULL tr
1b860 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 73 68 61 ace callback sha
1b870 6c 6c 20 64 69 73 61 62 6c 65 20 74 72 61 63 69 ll disable traci
1b880 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 ng..**.** {H1228
1b890 34 7d 20 54 68 65 20 66 69 72 73 74 20 61 72 67 4} The first arg
1b8a0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 ument to the tra
1b8b0 63 65 20 63 61 6c 6c 62 61 63 6b 20 73 68 61 6c ce callback shal
1b8c0 6c 20 62 65 20 61 20 63 6f 70 79 20 6f 66 0a 2a l be a copy of.*
1b8d0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 70 * the p
1b8e0 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 ointer which was
1b8f0 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e the 3rd argumen
1b900 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 t to [sqlite3_tr
1b910 61 63 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ace()]..**.** {H
1b920 31 32 32 38 35 7d 20 54 68 65 20 73 65 63 6f 6e 12285} The secon
1b930 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 d argument to th
1b940 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b e trace callback
1b950 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 is a.**
1b960 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 zero-terminate
1b970 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 63 d UTF-8 string c
1b980 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6f 72 ontaining the or
1b990 69 67 69 6e 61 6c 20 74 65 78 74 0a 2a 2a 20 20 iginal text.**
1b9a0 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 53 of the S
1b9b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 QL statement as
1b9c0 69 74 20 77 61 73 20 70 61 73 73 65 64 20 69 6e it was passed in
1b9d0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 to [sqlite3_prep
1b9e0 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20 are_v2()].**
1b9f0 20 20 20 20 20 20 6f 72 20 74 68 65 20 65 71 75 or the equ
1ba00 69 76 61 6c 65 6e 74 2c 20 6f 72 20 61 6e 20 53 ivalent, or an S
1ba10 51 4c 20 63 6f 6d 6d 65 6e 74 20 69 6e 64 69 63 QL comment indic
1ba20 61 74 69 6e 67 20 74 68 65 20 62 65 67 69 6e 6e ating the beginn
1ba30 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ing.**
1ba40 6f 66 20 61 20 74 72 69 67 67 65 72 20 73 75 62 of a trigger sub
1ba50 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b program..**.** {
1ba60 48 31 32 32 38 37 7d 20 54 68 65 20 63 61 6c 6c H12287} The call
1ba70 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 back function re
1ba80 67 69 73 74 65 72 65 64 20 62 79 20 5b 73 71 6c gistered by [sql
1ba90 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 ite3_profile()]
1baa0 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 is invoked.**
1bab0 20 20 20 20 20 20 20 61 73 20 65 61 63 68 20 53 as each S
1bac0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e QL statement fin
1bad0 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ishes..**.** {H1
1bae0 32 32 38 38 7d 20 54 68 65 20 66 69 72 73 74 20 2288} The first
1baf0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
1bb00 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 profile callbac
1bb10 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a k is a copy of.*
1bb20 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 33 * the 3
1bb30 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
1bb40 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 [sqlite3_profile
1bb50 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 ()]..**.** {H122
1bb60 38 39 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 89} The second p
1bb70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
1bb80 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b profile callback
1bb90 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 is a.**
1bba0 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 zero-terminate
1bbb0 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 d UTF-8 string t
1bbc0 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 hat contains the
1bbd0 20 63 6f 6d 70 6c 65 74 65 20 74 65 78 74 20 6f complete text o
1bbe0 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 f.** th
1bbf0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
1bc00 61 73 20 69 74 20 77 61 73 20 70 72 6f 63 65 73 as it was proces
1bc10 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f sed by [sqlite3_
1bc20 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a prepare_v2()].**
1bc30 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 or the
1bc40 20 65 71 75 69 76 61 6c 65 6e 74 2e 0a 2a 2a 0a equivalent..**.
1bc50 2a 2a 20 7b 48 31 32 32 39 30 7d 20 54 68 65 20 ** {H12290} The
1bc60 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
1bc70 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63 to the profile c
1bc80 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 65 73 allback is an es
1bc90 74 69 6d 61 74 65 0a 2a 2a 20 20 20 20 20 20 20 timate.**
1bca0 20 20 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 of the number
1bcb0 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 20 of nanoseconds
1bcc0 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 of wall-clock ti
1bcd0 6d 65 20 72 65 71 75 69 72 65 64 20 74 6f 0a 2a me required to.*
1bce0 2a 20 20 20 20 20 20 20 20 20 20 72 75 6e 20 74 * run t
1bcf0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
1bd00 20 66 72 6f 6d 20 73 74 61 72 74 20 74 6f 20 66 from start to f
1bd10 69 6e 69 73 68 2e 0a 2a 2f 0a 53 51 4c 49 54 45 inish..*/.SQLITE
1bd20 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f _EXPERIMENTAL vo
1bd30 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 id *sqlite3_trac
1bd40 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 e(sqlite3*, void
1bd50 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c (*xTrace)(void*,
1bd60 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f const char*), vo
1bd70 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 id*);.SQLITE_EXP
1bd80 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a ERIMENTAL void *
1bd90 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 sqlite3_profile(
1bda0 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 sqlite3*,. voi
1bdb0 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 d(*xProfile)(voi
1bdc0 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 d*,const char*,s
1bdd0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 qlite3_uint64),
1bde0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 void*);../*.** C
1bdf0 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 API3REF: Query P
1be00 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b rogress Callback
1be10 73 20 7b 48 31 32 39 31 30 7d 20 3c 53 36 30 34 s {H12910} <S604
1be20 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 00>.**.** This r
1be30 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 outine configure
1be40 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e s a callback fun
1be50 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 ction - the.** p
1be60 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b rogress callback
1be70 20 2d 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b - that is invok
1be80 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 ed periodically
1be90 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 during long.** r
1bea0 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 unning calls to
1beb0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
1bec0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 , [sqlite3_step(
1bed0 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 )] and.** [sqlit
1bee0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e e3_get_table()].
1bef0 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 An example use
1bf00 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 for this.** int
1bf10 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 erface is to kee
1bf20 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 p a GUI updated
1bf30 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 during a large q
1bf40 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 uery..**.** If t
1bf50 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c he progress call
1bf60 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e back returns non
1bf70 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 -zero, the opera
1bf80 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 tion is.** inter
1bf90 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 rupted. This fe
1bfa0 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 ature can be use
1bfb0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 d to implement a
1bfc0 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 .** "Cancel" but
1bfd0 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f ton on a GUI pro
1bfe0 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 gress dialog box
1bff0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 ..**.** The prog
1c000 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 75 73 ress handler mus
1c010 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e t not do anythin
1c020 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 g that will modi
1c030 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 fy.** the databa
1c040 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 se connection th
1c050 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 at invoked the p
1c060 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e rogress handler.
1c070 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 .** Note that [s
1c080 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1c090 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 2()] and [sqlite
1c0a0 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 3_step()] both m
1c0b0 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 odify their.** d
1c0c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1c0d0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e ons for the mean
1c0e0 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 ing of "modify"
1c0f0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 in this paragrap
1c100 68 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 h..**.** INVARIA
1c110 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 NTS:.**.** {H129
1c120 31 31 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 11} The callback
1c130 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 function regist
1c140 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f ered by sqlite3_
1c150 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 progress_handler
1c160 28 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 ().** i
1c170 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 s invoked period
1c180 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f ically during lo
1c190 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 ng running calls
1c1a0 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 to.**
1c1b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
1c1c0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 32 7d ..**.** {H12912}
1c1d0 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 The progress ca
1c1e0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
1c1f0 64 20 6f 6e 63 65 20 66 6f 72 20 65 76 65 72 79 d once for every
1c200 20 4e 20 76 69 72 74 75 61 6c 0a 2a 2a 20 20 20 N virtual.**
1c210 20 20 20 20 20 20 20 6d 61 63 68 69 6e 65 20 6f machine o
1c220 70 63 6f 64 65 73 2c 20 77 68 65 72 65 20 4e 20 pcodes, where N
1c230 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 is the second ar
1c240 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 gument to.**
1c250 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 the [sqlit
1c260 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 e3_progress_hand
1c270 6c 65 72 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 ler()] call that
1c280 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 registered.**
1c290 20 20 20 20 20 20 20 20 74 68 65 20 63 61 6c 6c the call
1c2a0 62 61 63 6b 2e 20 20 49 66 20 4e 20 69 73 20 6c back. If N is l
1c2b0 65 73 73 20 74 68 61 6e 20 31 2c 20 73 71 6c 69 ess than 1, sqli
1c2c0 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e te3_progress_han
1c2d0 64 6c 65 72 28 29 0a 2a 2a 20 20 20 20 20 20 20 dler().**
1c2e0 20 20 20 61 63 74 73 20 61 73 20 69 66 20 61 20 acts as if a
1c2f0 4e 55 4c 4c 20 70 72 6f 67 72 65 73 73 20 68 61 NULL progress ha
1c300 6e 64 6c 65 72 20 68 61 64 20 62 65 65 6e 20 73 ndler had been s
1c310 70 65 63 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 pecified..**.**
1c320 7b 48 31 32 39 31 33 7d 20 54 68 65 20 70 72 6f {H12913} The pro
1c330 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 gress callback i
1c340 74 73 65 6c 66 20 69 73 20 69 64 65 6e 74 69 66 tself is identif
1c350 69 65 64 20 62 79 20 74 68 65 20 74 68 69 72 64 ied by the third
1c360 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 67 .** arg
1c370 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 ument to sqlite3
1c380 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 _progress_handle
1c390 72 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 r()..**.** {H129
1c3a0 31 34 7d 20 54 68 65 20 66 6f 75 72 74 68 20 61 14} The fourth a
1c3b0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
1c3c0 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 e3_progress_hand
1c3d0 6c 65 72 28 29 20 69 73 20 61 0a 2a 2a 20 20 20 ler() is a.**
1c3e0 20 20 20 20 20 20 20 76 6f 69 64 20 70 6f 69 6e void poin
1c3f0 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 ter passed to th
1c400 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 e progress callb
1c410 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ack.**
1c420 66 75 6e 63 74 69 6f 6e 20 65 61 63 68 20 74 69 function each ti
1c430 6d 65 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 me it is invoked
1c440 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 35 7d ..**.** {H12915}
1c450 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 If a call to [s
1c460 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 qlite3_step()] r
1c470 65 73 75 6c 74 73 20 69 6e 20 66 65 77 65 72 20 esults in fewer
1c480 74 68 61 6e 20 4e 20 6f 70 63 6f 64 65 73 0a 2a than N opcodes.*
1c490 2a 20 20 20 20 20 20 20 20 20 20 62 65 69 6e 67 * being
1c4a0 20 65 78 65 63 75 74 65 64 2c 20 74 68 65 6e 20 executed, then
1c4b0 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c the progress cal
1c4c0 6c 62 61 63 6b 20 69 73 20 6e 65 76 65 72 20 69 lback is never i
1c4d0 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 nvoked..**.** {H
1c4e0 31 32 39 31 36 7d 20 45 76 65 72 79 20 63 61 6c 12916} Every cal
1c4f0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 l to [sqlite3_pr
1c500 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 ogress_handler()
1c510 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76 ].** ov
1c520 65 72 77 72 69 74 65 73 20 61 6e 79 20 70 72 65 erwrites any pre
1c530 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 viously register
1c540 65 64 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 ed progress hand
1c550 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 ler..**.** {H129
1c560 31 37 7d 20 49 66 20 74 68 65 20 70 72 6f 67 72 17} If the progr
1c570 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c ess handler call
1c580 62 61 63 6b 20 69 73 20 4e 55 4c 4c 20 74 68 65 back is NULL the
1c590 6e 20 6e 6f 20 70 72 6f 67 72 65 73 73 0a 2a 2a n no progress.**
1c5a0 20 20 20 20 20 20 20 20 20 20 68 61 6e 64 6c 65 handle
1c5b0 72 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a r is invoked..**
1c5c0 0a 2a 2a 20 7b 48 31 32 39 31 38 7d 20 49 66 20 .** {H12918} If
1c5d0 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c the progress cal
1c5e0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 lback returns a
1c5f0 72 65 73 75 6c 74 20 6f 74 68 65 72 20 74 68 61 result other tha
1c600 6e 20 30 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 n 0, then.**
1c610 20 20 20 20 20 20 74 68 65 20 62 65 68 61 76 69 the behavi
1c620 6f 72 20 69 73 20 61 20 69 66 20 5b 73 71 6c 69 or is a if [sqli
1c630 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d te3_interrupt()]
1c640 20 68 61 64 20 62 65 65 6e 20 63 61 6c 6c 65 64 had been called
1c650 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 53 ..** <S
1c660 33 30 35 30 30 3e 0a 2a 2f 0a 76 6f 69 64 20 73 30500>.*/.void s
1c670 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f qlite3_progress_
1c680 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a handler(sqlite3*
1c690 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f , int, int(*)(vo
1c6a0 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f id*), void*);../
1c6b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
1c6c0 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 pening A New Dat
1c6d0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e abase Connection
1c6e0 20 7b 48 31 32 37 30 30 7d 20 3c 53 34 30 32 30 {H12700} <S4020
1c6f0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 0>.**.** These r
1c700 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 outines open an
1c710 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 SQLite database
1c720 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 file whose name
1c730 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a is given by the.
1c740 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 ** filename argu
1c750 6d 65 6e 74 2e 20 54 68 65 20 66 69 6c 65 6e 61 ment. The filena
1c760 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 me argument is i
1c770 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 nterpreted as UT
1c780 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 F-8 for.** sqlit
1c790 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 e3_open() and sq
1c7a0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
1c7b0 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e and as UTF-16 in
1c7c0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 the native byte
1c7d0 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 .** order for sq
1c7e0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 lite3_open16().
1c7f0 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e A [database conn
1c800 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 ection] handle i
1c810 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 s usually.** ret
1c820 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 urned in *ppDb,
1c830 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 even if an error
1c840 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e occurs. The on
1c850 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 ly exception is
1c860 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 that.** if SQLit
1c870 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 e is unable to a
1c880 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 llocate memory t
1c890 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 o hold the [sqli
1c8a0 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 te3] object,.**
1c8b0 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 a NULL will be w
1c8c0 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 ritten into *ppD
1c8d0 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 b instead of a p
1c8e0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 ointer to the [s
1c8f0 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 qlite3].** objec
1c900 74 2e 20 49 66 20 74 68 65 20 64 61 74 61 62 61 t. If the databa
1c910 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e se is opened (an
1c920 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 d/or created) su
1c930 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e ccessfully, then
1c940 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 .** [SQLITE_OK]
1c950 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 is returned. Ot
1c960 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f herwise an [erro
1c970 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 r code] is retur
1c980 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 ned. The.** [sq
1c990 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 lite3_errmsg()]
1c9a0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d or [sqlite3_errm
1c9b0 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 sg16()] routines
1c9c0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
1c9d0 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 obtain.** an Eng
1c9e0 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 lish language de
1c9f0 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 scription of the
1ca00 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 error..**.** Th
1ca10 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 e default encodi
1ca20 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 ng for the datab
1ca30 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d ase will be UTF-
1ca40 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 8 if.** sqlite3_
1ca50 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 open() or sqlite
1ca60 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 3_open_v2() is c
1ca70 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 alled and.** UTF
1ca80 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 -16 in the nativ
1ca90 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 e byte order if
1caa0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
1cab0 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 is used..**.**
1cac0 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 Whether or not a
1cad0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 n error occurs w
1cae0 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 hen it is opened
1caf0 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 , resources.** a
1cb00 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
1cb10 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
1cb20 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 nection] handle
1cb30 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 should be releas
1cb40 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 ed by.** passing
1cb50 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f it to [sqlite3_
1cb60 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 close()] when it
1cb70 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 is no longer re
1cb80 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 quired..**.** Th
1cb90 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 e sqlite3_open_v
1cba0 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 2() interface wo
1cbb0 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 rks like sqlite3
1cbc0 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 _open().** excep
1cbd0 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 t that it accept
1cbe0 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c s two additional
1cbf0 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 parameters for
1cc00 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 additional contr
1cc10 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e ol.** over the n
1cc20 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ew database conn
1cc30 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61 ection. The fla
1cc40 67 73 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e gs parameter can
1cc50 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 take one of.**
1cc60 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 the following th
1cc70 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 ree values, opti
1cc80 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 onally combined
1cc90 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 with the .** [SQ
1cca0 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 LITE_OPEN_NOMUTE
1ccb0 58 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 X] or [SQLITE_OP
1ccc0 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c EN_FULLMUTEX] fl
1ccd0 61 67 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a ags:.**.** <dl>.
1cce0 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f ** <dt>[SQLITE_O
1ccf0 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 PEN_READONLY]</d
1cd00 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 t>.** <dd>The da
1cd10 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 tabase is opened
1cd20 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f in read-only mo
1cd30 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 de. If the data
1cd40 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a base does not.**
1cd50 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 already exist,
1cd60 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 an error is retu
1cd70 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a rned.</dd>.**.**
1cd80 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 <dt>[SQLITE_OPE
1cd90 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 N_READWRITE]</dt
1cda0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 >.** <dd>The dat
1cdb0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 abase is opened
1cdc0 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 for reading and
1cdd0 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 writing if possi
1cde0 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a ble, or reading.
1cdf0 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 ** only if the f
1ce00 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f ile is write pro
1ce10 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 tected by the op
1ce20 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 erating system.
1ce30 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 In either.** ca
1ce40 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 se the database
1ce50 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 must already exi
1ce60 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e st, otherwise an
1ce70 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e error is return
1ce80 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c ed.</dd>.**.** <
1ce90 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f dt>[SQLITE_OPEN_
1cea0 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 READWRITE] | [SQ
1ceb0 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
1cec0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 ]</dt>.** <dd>Th
1ced0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 e database is op
1cee0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 ened for reading
1cef0 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e and writing, an
1cf00 64 20 69 73 20 63 72 65 61 74 65 73 20 69 74 20 d is creates it
1cf10 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f if.** it does no
1cf20 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e t already exist.
1cf30 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68 This is the beh
1cf40 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c avior that is al
1cf50 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a ways used for.**
1cf60 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 sqlite3_open()
1cf70 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e and sqlite3_open
1cf80 31 36 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 16().</dd>.** </
1cf90 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 dl>.**.** If the
1cfa0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 3rd parameter t
1cfb0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 o sqlite3_open_v
1cfc0 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 2() is not one o
1cfd0 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 f the.** combina
1cfe0 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 tions shown abov
1cff0 65 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 e or one of the
1d000 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f combinations sho
1d010 77 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e 65 wn above combine
1d020 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 d.** with the [S
1d030 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 QLITE_OPEN_NOMUT
1d040 45 58 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f EX] or [SQLITE_O
1d050 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 PEN_FULLMUTEX] f
1d060 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 lags,.** then th
1d070 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e e behavior is un
1d080 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 defined..**.** I
1d090 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 f the [SQLITE_OP
1d0a0 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 EN_NOMUTEX] flag
1d0b0 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 is set, then th
1d0c0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
1d0d0 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 ction.** opens i
1d0e0 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 n the multi-thre
1d0f0 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ad [threading mo
1d100 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 de] as long as t
1d110 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 he single-thread
1d120 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 .** mode has not
1d130 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d been set at com
1d140 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 pile-time or sta
1d150 72 74 2d 74 69 6d 65 2e 20 20 49 66 20 74 68 65 rt-time. If the
1d160 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e .** [SQLITE_OPEN
1d170 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 _FULLMUTEX] flag
1d180 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 is set then the
1d190 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1d1a0 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e tion opens.** in
1d1b0 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 the serialized
1d1c0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d [threading mode]
1d1d0 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 unless single-t
1d1e0 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 hread was.** pre
1d1f0 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 viously selected
1d200 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 at compile-time
1d210 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a or start-time..
1d220 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c **.** If the fil
1d230 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 ename is ":memor
1d240 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 y:", then a priv
1d250 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 ate, temporary i
1d260 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 n-memory databas
1d270 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 e.** is created
1d280 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 for the connecti
1d290 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65 6d on. This in-mem
1d2a0 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c ory database wil
1d2b0 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a l vanish when.**
1d2c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
1d2d0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 nnection is clos
1d2e0 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 ed. Future vers
1d2f0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d ions of SQLite m
1d300 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 ight.** make use
1d310 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 of additional s
1d320 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 pecial filenames
1d330 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 that begin with
1d340 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 the ":" charact
1d350 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 er..** It is rec
1d360 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 ommended that wh
1d370 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 en a database fi
1d380 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 lename actually
1d390 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a does begin with.
1d3a0 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 ** a ":" charact
1d3b0 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 er you should pr
1d3c0 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d efix the filenam
1d3d0 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d e with a pathnam
1d3e0 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f e such as.** "./
1d3f0 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 " to avoid ambig
1d400 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 uity..**.** If t
1d410 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 he filename is a
1d420 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 n empty string,
1d430 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 then a private,
1d440 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d temporary.** on-
1d450 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 disk database wi
1d460 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 ll be created.
1d470 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 This private dat
1d480 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a abase will be.**
1d490 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 automatically d
1d4a0 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 eleted as soon a
1d4b0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 s the database c
1d4c0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f onnection is clo
1d4d0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 sed..**.** The f
1d4e0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
1d4f0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f to sqlite3_open_
1d500 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 v2() is the name
1d510 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 of the.** [sqli
1d520 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 te3_vfs] object
1d530 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 that defines the
1d540 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 operating syste
1d550 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 m interface that
1d560 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 .** the new data
1d570 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
1d580 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49 66 20 should use. If
1d590 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
1d5a0 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c eter is.** a NUL
1d5b0 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 L pointer then t
1d5c0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 he default [sqli
1d5d0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 te3_vfs] object
1d5e0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c is used..**.** <
1d5f0 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 b>Note to Window
1d600 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 s users:</b> Th
1d610 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 e encoding used
1d620 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 for the filename
1d630 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 argument.** of
1d640 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 sqlite3_open() a
1d650 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f nd sqlite3_open_
1d660 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 v2() must be UTF
1d670 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 -8, not whatever
1d680 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 .** codepage is
1d690 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 currently define
1d6a0 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f d. Filenames co
1d6b0 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 ntaining interna
1d6c0 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 tional.** charac
1d6d0 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e ters must be con
1d6e0 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 verted to UTF-8
1d6f0 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 prior to passing
1d700 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 them into.** sq
1d710 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 lite3_open() or
1d720 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
1d730 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 )..**.** INVARIA
1d740 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 NTS:.**.** {H127
1d750 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 01} The [sqlite3
1d760 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 _open()], [sqlit
1d770 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e e3_open16()], an
1d780 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 d.** [s
1d790 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
1d7a0 5d 20 69 6e 74 65 72 66 61 63 65 73 20 63 72 65 ] interfaces cre
1d7b0 61 74 65 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 ate a new.**
1d7c0 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 [database
1d7d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f connection] asso
1d7e0 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 20 ciated with.**
1d7f0 20 20 20 20 20 20 20 20 74 68 65 20 64 61 74 61 the data
1d800 62 61 73 65 20 66 69 6c 65 20 67 69 76 65 6e 20 base file given
1d810 69 6e 20 74 68 65 69 72 20 66 69 72 73 74 20 70 in their first p
1d820 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 arameter..**.**
1d830 7b 48 31 32 37 30 32 7d 20 54 68 65 20 66 69 6c {H12702} The fil
1d840 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 ename argument i
1d850 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 s interpreted as
1d860 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 UTF-8.**
1d870 20 20 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f for [sqlite3_
1d880 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c open()] and [sql
1d890 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 ite3_open_v2()]
1d8a0 61 6e 64 20 61 73 20 55 54 46 2d 31 36 0a 2a 2a and as UTF-16.**
1d8b0 20 20 20 20 20 20 20 20 20 20 69 6e 20 74 68 65 in the
1d8c0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
1d8d0 65 72 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f er for [sqlite3_
1d8e0 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a open16()]..**.**
1d8f0 20 7b 48 31 32 37 30 33 7d 20 41 20 73 75 63 63 {H12703} A succ
1d900 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f essful invocatio
1d910 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 n of [sqlite3_op
1d920 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f en()], [sqlite3_
1d930 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 open16()],.**
1d940 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 or [sqlit
1d950 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 72 e3_open_v2()] wr
1d960 69 74 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 ites a pointer t
1d970 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 o a new.**
1d980 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f [database co
1d990 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 2a nnection] into *
1d9a0 70 70 44 62 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 ppDb..**.** {H12
1d9b0 37 30 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 704} The [sqlite
1d9c0 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 3_open()], [sqli
1d9d0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 te3_open16()], a
1d9e0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b nd.** [
1d9f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
1da00 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 )] interfaces re
1da10 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d turn [SQLITE_OK]
1da20 20 75 70 6f 6e 20 73 75 63 63 65 73 73 2c 0a 2a upon success,.*
1da30 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 61 6e * or an
1da40 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 appropriate [er
1da50 72 6f 72 20 63 6f 64 65 5d 20 6f 6e 20 66 61 69 ror code] on fai
1da60 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 lure..**.** {H12
1da70 37 30 36 7d 20 54 68 65 20 64 65 66 61 75 6c 74 706} The default
1da80 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 66 text encoding f
1da90 6f 72 20 61 20 6e 65 77 20 64 61 74 61 62 61 73 or a new databas
1daa0 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a e created using.
1dab0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
1dac0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 ite3_open()] or
1dad0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
1dae0 28 29 5d 20 77 69 6c 6c 20 62 65 20 55 54 46 2d ()] will be UTF-
1daf0 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 37 8..**.** {H12707
1db00 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 74 65 } The default te
1db10 78 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 xt encoding for
1db20 61 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 a new database c
1db30 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 reated using.**
1db40 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
1db50 33 5f 6f 70 65 6e 31 36 28 29 5d 20 77 69 6c 6c 3_open16()] will
1db60 20 62 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a be UTF-16..**.*
1db70 2a 20 7b 48 31 32 37 30 39 7d 20 54 68 65 20 5b * {H12709} The [
1db80 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 46 2c 44 sqlite3_open(F,D
1db90 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 )] interface is
1dba0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 0a 2a 2a equivalent to.**
1dbb0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
1dbc0 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 e3_open_v2(F,D,G
1dbd0 2c 30 29 5d 20 77 68 65 72 65 20 74 68 65 20 47 ,0)] where the G
1dbe0 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a parameter is.**
1dbf0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 [SQLIT
1dc00 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 E_OPEN_READWRITE
1dc10 5d 7c 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 ]|[SQLITE_OPEN_C
1dc20 52 45 41 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 REATE]..**.** {H
1dc30 31 32 37 31 31 7d 20 49 66 20 74 68 65 20 47 20 12711} If the G
1dc40 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 parameter to [sq
1dc50 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c lite3_open_v2(F,
1dc60 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 D,G,V)] contains
1dc70 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
1dc80 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 bit value [SQLI
1dc90 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 TE_OPEN_READONLY
1dca0 5d 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 ] then the datab
1dcb0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a ase is opened.**
1dcc0 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 72 65 for re
1dcd0 61 64 69 6e 67 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a ading only..**.*
1dce0 2a 20 7b 48 31 32 37 31 32 7d 20 49 66 20 74 68 * {H12712} If th
1dcf0 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f e G parameter to
1dd00 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
1dd10 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 2(F,D,G,V)] cont
1dd20 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 ains the.**
1dd30 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b bit value [
1dd40 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
1dd50 57 52 49 54 45 5d 20 74 68 65 6e 20 74 68 65 20 WRITE] then the
1dd60 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e database is open
1dd70 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 ed.** r
1dd80 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 eading and writi
1dd90 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 ng if possible,
1dda0 6f 72 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f or for reading o
1ddb0 6e 6c 79 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 nly if the.**
1ddc0 20 20 20 20 20 20 20 66 69 6c 65 20 69 73 20 77 file is w
1ddd0 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 rite protected b
1dde0 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 y the operating
1ddf0 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 system..**.** {H
1de00 31 32 37 31 33 7d 20 49 66 20 74 68 65 20 47 20 12713} If the G
1de10 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 parameter to [sq
1de20 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c lite3_open_v2(F,
1de30 44 2c 47 2c 56 29 5d 20 6f 6d 69 74 73 20 74 68 D,G,V)] omits th
1de40 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 e.** bi
1de50 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f t value [SQLITE_
1de60 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64 OPEN_CREATE] and
1de70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f the database do
1de80 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 es not.**
1de90 20 20 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78 previously ex
1dea0 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 ist, an error is
1deb0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
1dec0 20 7b 48 31 32 37 31 34 7d 20 49 66 20 74 68 65 {H12714} If the
1ded0 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 G parameter to
1dee0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
1def0 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 (F,D,G,V)] conta
1df00 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 ins the.**
1df10 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 bit value [S
1df20 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
1df30 45 5d 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 E] and the datab
1df40 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 ase does not.**
1df50 20 20 20 20 20 20 20 20 20 70 72 65 76 69 6f 75 previou
1df60 73 6c 79 20 65 78 69 73 74 2c 20 74 68 65 6e 20 sly exist, then
1df70 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 an attempt is ma
1df80 64 65 20 74 6f 20 63 72 65 61 74 65 20 61 6e 64 de to create and
1df90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 69 .** ini
1dfa0 74 69 61 6c 69 7a 65 20 74 68 65 20 64 61 74 61 tialize the data
1dfb0 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 base..**.** {H12
1dfc0 37 31 37 7d 20 49 66 20 74 68 65 20 66 69 6c 65 717} If the file
1dfd0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 74 6f name argument to
1dfe0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
1dff0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ], [sqlite3_open
1e000 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 16()],.**
1e010 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f or [sqlite3_o
1e020 70 65 6e 5f 76 32 28 29 5d 20 69 73 20 22 3a 6d pen_v2()] is ":m
1e030 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 6e emory:", then an
1e040 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20 private,.**
1e050 20 20 20 20 20 20 65 70 68 65 6d 65 72 61 6c 2c ephemeral,
1e060 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 in-memory datab
1e070 61 73 65 20 69 73 20 63 72 65 61 74 65 64 20 66 ase is created f
1e080 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f or the connectio
1e090 6e 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c n..** <
1e0a0 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f 4f todo>Is SQLITE_O
1e0b0 50 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49 54 PEN_CREATE|SQLIT
1e0c0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 E_OPEN_READWRITE
1e0d0 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 20 20 20 required.**
1e0e0 20 20 20 20 20 20 69 6e 20 73 71 6c 69 74 65 33 in sqlite3
1e0f0 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64 _open_v2()?</tod
1e100 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 39 o>.**.** {H12719
1e110 7d 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d } If the filenam
1e120 65 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 e is NULL or an
1e130 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 empty string, th
1e140 65 6e 20 61 20 70 72 69 76 61 74 65 2c 0a 2a 2a en a private,.**
1e150 20 20 20 20 20 20 20 20 20 20 65 70 68 65 6d 65 epheme
1e160 72 61 6c 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 ral on-disk data
1e170 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 base will be cre
1e180 61 74 65 64 2e 0a 2a 2a 20 20 20 20 20 20 20 20 ated..**
1e190 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54 <todo>Is SQLIT
1e1a0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 51 E_OPEN_CREATE|SQ
1e1b0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
1e1c0 49 54 45 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 ITE required.**
1e1d0 20 20 20 20 20 20 20 20 20 69 6e 20 73 71 6c 69 in sqli
1e1e0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f te3_open_v2()?</
1e1f0 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 todo>.**.** {H12
1e200 37 32 31 7d 20 54 68 65 20 5b 64 61 74 61 62 61 721} The [databa
1e210 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 se connection] c
1e220 72 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 reated by [sqlit
1e230 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 e3_open_v2(F,D,G
1e240 2c 56 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 ,V)].**
1e250 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 5b 73 will use the [s
1e260 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
1e270 63 74 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 ct identified by
1e280 20 74 68 65 20 56 20 70 61 72 61 6d 65 74 65 72 the V parameter
1e290 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 ,.** or
1e2a0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 the default [sq
1e2b0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 lite3_vfs] objec
1e2c0 74 20 69 66 20 56 20 69 73 20 61 20 4e 55 4c 4c t if V is a NULL
1e2d0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 pointer..**.**
1e2e0 7b 48 31 32 37 32 33 7d 20 54 77 6f 20 5b 64 61 {H12723} Two [da
1e2f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1e300 6e 73 5d 20 77 69 6c 6c 20 73 68 61 72 65 20 61 ns] will share a
1e310 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 20 69 66 common cache if
1e320 20 62 6f 74 68 20 77 65 72 65 0a 2a 2a 20 20 20 both were.**
1e330 20 20 20 20 20 20 20 6f 70 65 6e 65 64 20 77 69 opened wi
1e340 74 68 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 th the same VFS
1e350 77 68 69 6c 65 20 5b 73 68 61 72 65 64 20 63 61 while [shared ca
1e360 63 68 65 20 6d 6f 64 65 5d 20 77 61 73 20 65 6e che mode] was en
1e370 61 62 6c 65 64 20 61 6e 64 0a 2a 2a 20 20 20 20 abled and.**
1e380 20 20 20 20 20 20 69 66 20 62 6f 74 68 20 66 69 if both fi
1e390 6c 65 6e 61 6d 65 73 20 63 6f 6d 70 61 72 65 20 lenames compare
1e3a0 65 71 75 61 6c 20 75 73 69 6e 67 20 6d 65 6d 63 equal using memc
1e3b0 6d 70 28 29 20 61 66 74 65 72 20 68 61 76 69 6e mp() after havin
1e3c0 67 20 62 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20 g been.**
1e3d0 20 20 20 70 72 6f 63 65 73 73 65 64 20 62 79 20 processed by
1e3e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 the [sqlite3_vfs
1e3f0 20 7c 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 | xFullPathname
1e400 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 ] method of the
1e410 56 46 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 VFS..*/.int sqli
1e420 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 te3_open(. cons
1e430 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 t char *filename
1e440 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 , /* Database
1e450 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 filename (UTF-8)
1e460 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a */. sqlite3 **
1e470 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a ppDb /*
1e480 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 OUT: SQLite db
1e490 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 handle */.);.int
1e4a0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 sqlite3_open16(
1e4b0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 . const void *f
1e4c0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 ilename, /* Da
1e4d0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 tabase filename
1e4e0 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 (UTF-16) */. sq
1e4f0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 lite3 **ppDb
1e500 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 /* OUT: SQ
1e510 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a Lite db handle *
1e520 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 /.);.int sqlite3
1e530 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 _open_v2(. cons
1e540 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 t char *filename
1e550 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 , /* Database
1e560 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 filename (UTF-8)
1e570 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a */. sqlite3 **
1e580 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a ppDb, /*
1e590 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 OUT: SQLite db
1e5a0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 handle */. int
1e5b0 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 flags,
1e5c0 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a /* Flags */.
1e5d0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 const char *zV
1e5e0 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d fs /* Nam
1e5f0 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 e of VFS module
1e600 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a to use */.);../*
1e610 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 .** CAPI3REF: Er
1e620 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 ror Codes And Me
1e630 73 73 61 67 65 73 20 7b 48 31 32 38 30 30 7d 20 ssages {H12800}
1e640 3c 53 36 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S60200>.**.** T
1e650 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f he sqlite3_errco
1e660 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 de() interface r
1e670 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 eturns the numer
1e680 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d ic [result code]
1e690 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 or.** [extended
1e6a0 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f result code] fo
1e6b0 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e r the most recen
1e6c0 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 t failed sqlite3
1e6d0 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 _* API call.** a
1e6e0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 ssociated with a
1e6f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
1e700 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 ction]. If a pri
1e710 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c or API call fail
1e720 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f ed.** but the mo
1e730 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 st recent API ca
1e740 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 ll succeeded, th
1e750 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 e return value f
1e760 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 rom.** sqlite3_e
1e770 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 rrcode() is unde
1e780 66 69 6e 65 64 2e 20 20 54 68 65 20 73 71 6c 69 fined. The sqli
1e790 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 te3_extended_err
1e7a0 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 code().** interf
1e7b0 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 ace is the same
1e7c0 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 except that it a
1e7d0 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 lways returns th
1e7e0 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 e .** [extended
1e7f0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 result code] eve
1e800 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 n when extended
1e810 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 result codes are
1e820 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a .** disabled..**
1e830 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
1e840 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c errmsg() and sql
1e850 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 ite3_errmsg16()
1e860 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c return English-l
1e870 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 anguage.** text
1e880 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 that describes t
1e890 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 he error, as eit
1e8a0 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 her UTF-8 or UTF
1e8b0 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 -16 respectively
1e8c0 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 68 ..** Memory to h
1e8d0 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 old the error me
1e8e0 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 ssage string is
1e8f0 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c managed internal
1e900 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 ly..** The appli
1e910 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 cation does not
1e920 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 need to worry ab
1e930 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 out freeing the
1e940 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 result..** Howev
1e950 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 er, the error st
1e960 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 ring might be ov
1e970 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 erwritten or dea
1e980 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 llocated by.** s
1e990 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 ubsequent calls
1e9a0 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 to other SQLite
1e9b0 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 interface functi
1e9c0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e ons..**.** If an
1e9d0 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 interface fails
1e9e0 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 with SQLITE_MIS
1e9f0 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 USE, that means
1ea00 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a the interface.**
1ea10 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 was invoked inc
1ea20 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 orrectly by the
1ea30 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e application. In
1ea40 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a that case, the.
1ea50 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e ** error code an
1ea60 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 d message may or
1ea70 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e may not be set.
1ea80 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
1ea90 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 31 S:.**.** {H12801
1eaa0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 } The [sqlite3_e
1eab0 72 72 63 6f 64 65 28 44 29 5d 20 69 6e 74 65 72 rrcode(D)] inter
1eac0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 face returns the
1ead0 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 20 20 20 20 numeric.**
1eae0 20 20 20 20 20 5b 72 65 73 75 6c 74 20 63 6f 64 [result cod
1eaf0 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 e] or [extended
1eb00 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 result code] for
1eb10 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
1eb20 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 ly.** f
1eb30 61 69 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20 ailed interface
1eb40 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20 call associated
1eb50 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 with the [databa
1eb60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
1eb70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 32 7d ..**.** {H12802}
1eb80 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 The [sqlite3_ex
1eb90 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 44 tended_errcode(D
1eba0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
1ebb0 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 urns the numeric
1ebc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 65 78 .** [ex
1ebd0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
1ebe0 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 de] for the most
1ebf0 20 72 65 63 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 recently.**
1ec00 20 20 20 20 20 20 66 61 69 6c 65 64 20 69 6e 74 failed int
1ec10 65 72 66 61 63 65 20 63 61 6c 6c 20 61 73 73 6f erface call asso
1ec20 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 ciated with the
1ec30 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
1ec40 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b tion] D..**.** {
1ec50 48 31 32 38 30 33 7d 20 54 68 65 20 5b 73 71 6c H12803} The [sql
1ec60 69 74 65 33 5f 65 72 72 6d 73 67 28 44 29 5d 20 ite3_errmsg(D)]
1ec70 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 and [sqlite3_err
1ec80 6d 73 67 31 36 28 44 29 5d 0a 2a 2a 20 20 20 20 msg16(D)].**
1ec90 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 interfaces
1eca0 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d return English-
1ecb0 6c 61 6e 67 75 61 67 65 20 74 65 78 74 20 74 68 language text th
1ecc0 61 74 20 64 65 73 63 72 69 62 65 73 0a 2a 2a 20 at describes.**
1ecd0 20 20 20 20 20 20 20 20 20 74 68 65 20 65 72 72 the err
1ece0 6f 72 20 69 6e 20 74 68 65 20 6d 6f 73 74 6c 79 or in the mostly
1ecf0 20 72 65 63 65 6e 74 6c 79 20 66 61 69 6c 65 64 recently failed
1ed00 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 2c interface call,
1ed10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e 63 .** enc
1ed20 6f 64 65 64 20 61 73 20 65 69 74 68 65 72 20 55 oded as either U
1ed30 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 TF-8 or UTF-16 r
1ed40 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a espectively..**.
1ed50 2a 2a 20 7b 48 31 32 38 30 37 7d 20 54 68 65 20 ** {H12807} The
1ed60 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 strings returned
1ed70 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 by [sqlite3_err
1ed80 6d 73 67 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 msg()] and [sqli
1ed90 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a te3_errmsg16()].
1eda0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20 ** are
1edb0 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 valid until the
1edc0 6e 65 78 74 20 53 51 4c 69 74 65 20 69 6e 74 65 next SQLite inte
1edd0 72 66 61 63 65 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a rface call..**.*
1ede0 2a 20 7b 48 31 32 38 30 38 7d 20 43 61 6c 6c 73 * {H12808} Calls
1edf0 20 74 6f 20 41 50 49 20 72 6f 75 74 69 6e 65 73 to API routines
1ee00 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 72 65 74 that do not ret
1ee10 75 72 6e 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 urn an error cod
1ee20 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 28 65 e.** (e
1ee30 78 61 6d 70 6c 65 3a 20 5b 73 71 6c 69 74 65 33 xample: [sqlite3
1ee40 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 29 20 _data_count()])
1ee50 64 6f 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 do not.**
1ee60 20 20 20 63 68 61 6e 67 65 20 74 68 65 20 65 72 change the er
1ee70 72 6f 72 20 63 6f 64 65 20 6f 72 20 6d 65 73 73 ror code or mess
1ee80 61 67 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a age returned by.
1ee90 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
1eea0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c ite3_errcode()],
1eeb0 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 [sqlite3_extend
1eec0 65 64 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a ed_errcode()],.*
1eed0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
1eee0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 6f te3_errmsg()], o
1eef0 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 r [sqlite3_errms
1ef00 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 g16()]..**.** {H
1ef10 31 32 38 30 39 7d 20 49 6e 74 65 72 66 61 63 65 12809} Interface
1ef20 73 20 74 68 61 74 20 61 72 65 20 6e 6f 74 20 61 s that are not a
1ef30 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 ssociated with a
1ef40 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 20 20 20 specific.**
1ef50 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 [database
1ef60 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 65 78 61 connection] (exa
1ef70 6d 70 6c 65 73 3a 0a 2a 2a 20 20 20 20 20 20 20 mples:.**
1ef80 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 [sqlite3_mpri
1ef90 6e 74 66 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 ntf()] or [sqlit
1efa0 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 e3_enable_shared
1efb0 5f 63 61 63 68 65 28 29 5d 0a 2a 2a 20 20 20 20 _cache()].**
1efc0 20 20 20 20 20 20 64 6f 20 6e 6f 74 20 63 68 61 do not cha
1efd0 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 20 72 nge the values r
1efe0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 eturned by.**
1eff0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
1f000 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c errcode()], [sql
1f010 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 ite3_extended_er
1f020 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20 rcode()],.**
1f030 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 [sqlite3_e
1f040 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71 rrmsg()], or [sq
1f050 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 lite3_errmsg16()
1f060 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 ]..*/.int sqlite
1f070 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 3_errcode(sqlite
1f080 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 3 *db);.int sqli
1f090 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 te3_extended_err
1f0a0 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 code(sqlite3 *db
1f0b0 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 );.const char *s
1f0c0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 qlite3_errmsg(sq
1f0d0 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 lite3*);.const v
1f0e0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 oid *sqlite3_err
1f0f0 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b msg16(sqlite3*);
1f100 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1f110 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 : SQL Statement
1f120 4f 62 6a 65 63 74 20 7b 48 31 33 30 30 30 7d 20 Object {H13000}
1f130 3c 48 31 33 30 31 30 3e 0a 2a 2a 20 4b 45 59 57 <H13010>.** KEYW
1f140 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 ORDS: {prepared
1f150 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 statement} {prep
1f160 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d ared statements}
1f170 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e .**.** An instan
1f180 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 ce of this objec
1f190 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 t represents a s
1f1a0 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d ingle SQL statem
1f1b0 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a ent..** This obj
1f1c0 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 ect is variously
1f1d0 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 known as a "pre
1f1e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 pared statement"
1f1f0 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c or a.** "compil
1f200 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ed SQL statement
1f210 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 " or simply as a
1f220 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a "statement"..**
1f230 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 .** The life of
1f240 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 a statement obje
1f250 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e ct goes somethin
1f260 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a g like this:.**.
1f270 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ol>.** <li>
1f280 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 Create the objec
1f290 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
1f2a0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
1f2b0 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 r a related.**
1f2c0 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a function..**
1f2d0 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 <li> Bind value
1f2e0 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d s to [host param
1f2f0 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 eters] using the
1f300 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 sqlite3_bind_*(
1f310 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 ).** interf
1f320 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 aces..** <li> Ru
1f330 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c n the SQL by cal
1f340 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 ling [sqlite3_st
1f350 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 ep()] one or mor
1f360 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e e times..** <li>
1f370 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74 65 Reset the state
1f380 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 ment using [sqli
1f390 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 te3_reset()] the
1f3a0 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 n go back.**
1f3b0 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f to step 2. Do
1f3c0 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f this zero or mo
1f3d0 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 re times..** <li
1f3e0 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 > Destroy the ob
1f3f0 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 ject using [sqli
1f400 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e te3_finalize()].
1f410 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ol>.**.**
1f420 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e Refer to documen
1f430 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 tation on indivi
1f440 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f dual methods abo
1f450 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 ve for additiona
1f460 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e l.** information
1f470 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
1f480 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 uct sqlite3_stmt
1f490 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a sqlite3_stmt;..
1f4a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1f4b0 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 20 Run-time Limits
1f4c0 7b 48 31 32 37 36 30 7d 20 3c 53 32 30 36 30 30 {H12760} <S20600
1f4d0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 >.**.** This int
1f4e0 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 erface allows th
1f4f0 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 e size of variou
1f500 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 s constructs to
1f510 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e be limited.** on
1f520 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 a connection by
1f530 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 connection basi
1f540 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 s. The first pa
1f550 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a rameter is the.*
1f560 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
1f570 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 ection] whose li
1f580 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 mit is to be set
1f590 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 or queried. Th
1f5a0 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 e.** second para
1f5b0 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 meter is one of
1f5c0 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 the [limit categ
1f5d0 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 ories] that defi
1f5e0 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 ne a.** class of
1f5f0 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 constructs to b
1f600 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 e size limited.
1f610 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d The third param
1f620 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e eter is the.** n
1f630 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 ew limit for tha
1f640 74 20 63 6f 6e 73 74 72 75 63 74 2e 20 20 54 68 t construct. Th
1f650 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 e function retur
1f660 6e 73 20 74 68 65 20 6f 6c 64 20 6c 69 6d 69 74 ns the old limit
1f670 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e ..**.** If the n
1f680 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 ew limit is a ne
1f690 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 gative number, t
1f6a0 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 he limit is unch
1f6b0 61 6e 67 65 64 2e 0a 2a 2a 20 46 6f 72 20 74 68 anged..** For th
1f6c0 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 e limit category
1f6d0 20 6f 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 of SQLITE_LIMIT
1f6e0 5f 58 59 5a 20 74 68 65 72 65 20 69 73 20 61 20 _XYZ there is a
1f6f0 68 61 72 64 20 75 70 70 65 72 0a 2a 2a 20 62 6f hard upper.** bo
1f700 75 6e 64 20 73 65 74 20 62 79 20 61 20 63 6f 6d und set by a com
1f710 70 69 6c 65 2d 74 69 6d 65 20 43 20 70 72 65 70 pile-time C prep
1f720 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 6e rocessor macro n
1f730 61 6d 65 64 20 53 51 4c 49 54 45 5f 4d 41 58 5f amed SQLITE_MAX_
1f740 58 59 5a 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c XYZ..** (The "_L
1f750 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 IMIT_" in the na
1f760 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f me is changed to
1f770 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a 2a 20 41 74 "_MAX_".).** At
1f780 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 tempts to increa
1f790 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 se a limit above
1f7a0 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 its hard upper
1f7b0 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c bound are.** sil
1f7c0 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 ently truncated
1f7d0 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 to the hard uppe
1f7e0 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 52 r limit..**.** R
1f7f0 75 6e 20 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 un time limits a
1f800 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 re intended for
1f810 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 use in applicati
1f820 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a ons that manage.
1f830 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 ** both their ow
1f840 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 n internal datab
1f850 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 ase and also dat
1f860 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 abases that are
1f870 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 controlled.** by
1f880 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 untrusted exter
1f890 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e nal sources. An
1f8a0 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 example applica
1f8b0 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a tion might be a.
1f8c0 2a 2a 20 77 65 62 62 72 6f 77 73 65 72 20 74 68 ** webbrowser th
1f8d0 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 at has its own d
1f8e0 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f atabases for sto
1f8f0 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 ring history and
1f900 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 .** separate dat
1f910 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 abases controlle
1f920 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 d by JavaScript
1f930 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 applications dow
1f940 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 nloaded.** off t
1f950 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 he Internet. Th
1f960 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 e internal datab
1f970 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 ases can be give
1f980 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 n the.** large,
1f990 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 default limits.
1f9a0 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 Databases manag
1f9b0 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 ed by external s
1f9c0 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 ources can.** be
1f9d0 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c given much smal
1f9e0 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 ler limits desig
1f9f0 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 ned to prevent a
1fa00 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 denial of servi
1fa10 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 ce.** attack. D
1fa20 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 evelopers might
1fa30 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 also want to use
1fa40 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 the [sqlite3_se
1fa50 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a t_authorizer()].
1fa60 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 ** interface to
1fa70 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 further control
1fa80 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 untrusted SQL.
1fa90 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 The size of the
1faa0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 database.** crea
1fab0 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 ted by an untrus
1fac0 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 ted script can b
1fad0 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e e contained usin
1fae0 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 g the.** [max_pa
1faf0 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d ge_count] [PRAGM
1fb00 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 A]..**.** New ru
1fb10 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 n-time limit cat
1fb20 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 egories may be a
1fb30 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 dded in future r
1fb40 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 eleases..**.** I
1fb50 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
1fb60 20 7b 48 31 32 37 36 32 7d 20 41 20 73 75 63 63 {H12762} A succ
1fb70 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b essful call to [
1fb80 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c sqlite3_limit(D,
1fb90 43 2c 56 29 5d 20 77 68 65 72 65 20 56 20 69 73 C,V)] where V is
1fba0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 73 .** pos
1fbb0 69 74 69 76 65 20 63 68 61 6e 67 65 73 20 74 68 itive changes th
1fbc0 65 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 73 e limit on the s
1fbd0 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 ize of construct
1fbe0 20 43 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 C in the.**
1fbf0 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 [database
1fc00 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74 6f connection] D to
1fc10 20 74 68 65 20 6c 65 73 73 65 72 20 6f 66 20 56 the lesser of V
1fc20 20 61 6e 64 20 74 68 65 20 68 61 72 64 20 75 70 and the hard up
1fc30 70 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 per.**
1fc40 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 73 69 7a bound on the siz
1fc50 65 20 6f 66 20 43 20 74 68 61 74 20 69 73 20 73 e of C that is s
1fc60 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 et at compile-ti
1fc70 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36 me..**.** {H1276
1fc80 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 6} A successful
1fc90 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
1fca0 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20 77 _limit(D,C,V)] w
1fcb0 68 65 72 65 20 56 20 69 73 20 6e 65 67 61 74 69 here V is negati
1fcc0 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c ve.** l
1fcd0 65 61 76 65 73 20 74 68 65 20 73 74 61 74 65 20 eaves the state
1fce0 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 of the [database
1fcf0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 75 connection] D u
1fd00 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 nchanged..**.**
1fd10 7b 48 31 32 37 36 39 7d 20 41 20 73 75 63 63 65 {H12769} A succe
1fd20 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 ssful call to [s
1fd30 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 qlite3_limit(D,C
1fd40 2c 56 29 5d 20 72 65 74 75 72 6e 73 20 74 68 65 ,V)] returns the
1fd50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c .** val
1fd60 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 20 ue of the limit
1fd70 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 63 on the size of c
1fd80 6f 6e 73 74 72 75 63 74 20 43 20 69 6e 20 74 68 onstruct C in th
1fd90 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 e.** [d
1fda0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1fdb0 6f 6e 5d 20 44 20 61 73 20 69 74 20 77 61 73 20 on] D as it was
1fdc0 70 72 69 6f 72 20 74 6f 20 74 68 65 20 63 61 6c prior to the cal
1fdd0 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 l..*/.int sqlite
1fde0 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 3_limit(sqlite3*
1fdf0 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 , int id, int ne
1fe00 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 wVal);../*.** CA
1fe10 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 PI3REF: Run-Time
1fe20 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 Limit Categorie
1fe30 73 20 7b 48 31 32 37 39 30 7d 20 3c 48 31 32 37 s {H12790} <H127
1fe40 36 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 60>.** KEYWORDS:
1fe50 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 {limit category
1fe60 7d 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 } {limit categor
1fe70 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ies}.**.** These
1fe80 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e constants defin
1fe90 65 20 76 61 72 69 6f 75 73 20 61 73 70 65 63 74 e various aspect
1fea0 73 20 6f 66 20 61 20 5b 64 61 74 61 62 61 73 65 s of a [database
1feb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 connection].**
1fec0 74 68 61 74 20 63 61 6e 20 62 65 20 6c 69 6d 69 that can be limi
1fed0 74 65 64 20 69 6e 20 73 69 7a 65 20 62 79 20 63 ted in size by c
1fee0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
1fef0 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 _limit()]..** Th
1ff00 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 e meanings of th
1ff10 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 e various limits
1ff20 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a are as follows:
1ff30 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c .**.** <dl>.** <
1ff40 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
1ff50 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c LENGTH</dt>.** <
1ff60 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 dd>The maximum s
1ff70 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e ize of any strin
1ff80 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 g or BLOB or tab
1ff90 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a 2a 0a 2a le row.<dd>.**.*
1ffa0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d * <dt>SQLITE_LIM
1ffb0 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 IT_SQL_LENGTH</d
1ffc0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
1ffd0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
1ffe0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 an SQL statement
1fff0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
20000 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f >SQLITE_LIMIT_CO
20010 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 LUMN</dt>.** <dd
20020 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d >The maximum num
20030 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 ber of columns i
20040 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 n a table defini
20050 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a tion or in the.*
20060 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 * result set of
20070 61 20 53 45 4c 45 43 54 20 6f 72 20 74 68 65 20 a SELECT or the
20080 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
20090 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 f columns in an
200a0 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 index.** or in a
200b0 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 n ORDER BY or GR
200c0 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f OUP BY clause.</
200d0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
200e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f LITE_LIMIT_EXPR_
200f0 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 DEPTH</dt>.** <d
20100 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 d>The maximum de
20110 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 pth of the parse
20120 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 tree on any exp
20130 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a ression.</dd>.**
20140 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c .** <dt>SQLITE_L
20150 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 IMIT_COMPOUND_SE
20160 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 LECT</dt>.** <dd
20170 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d >The maximum num
20180 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 ber of terms in
20190 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 a compound SELEC
201a0 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 T statement.</dd
201b0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
201c0 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 TE_LIMIT_VDBE_OP
201d0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
201e0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
201f0 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 of instructions
20200 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 in a virtual mac
20210 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 hine program.**
20220 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e used to implemen
20230 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 t an SQL stateme
20240 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c nt.</dd>.**.** <
20250 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
20260 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 FUNCTION_ARG</dt
20270 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
20280 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 imum number of a
20290 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 rguments on a fu
202a0 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a nction.</dd>.**.
202b0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ** <dt>SQLITE_LI
202c0 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 MIT_ATTACHED</dt
202d0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
202e0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 imum number of a
202f0 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 ttached database
20300 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 s.</dd>.**.** <d
20310 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c t>SQLITE_LIMIT_L
20320 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 IKE_PATTERN_LENG
20330 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 TH</dt>.** <dd>T
20340 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 he maximum lengt
20350 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e h of the pattern
20360 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
20370 20 4c 49 4b 45 20 6f 72 0a 2a 2a 20 47 4c 4f 42 LIKE or.** GLOB
20380 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e operators.</dd>
20390 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
203a0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 E_LIMIT_VARIABLE
203b0 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 _NUMBER</dt>.**
203c0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
203d0 6e 75 6d 62 65 72 20 6f 66 20 76 61 72 69 61 62 number of variab
203e0 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 les in an SQL st
203f0 61 74 65 6d 65 6e 74 20 74 68 61 74 20 63 61 6e atement that can
20400 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 .** be bound.</d
20410 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 d>.** </dl>.*/.#
20420 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
20430 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 MIT_LENGTH
20440 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 0.
20450 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
20460 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 IMIT_SQL_LENGTH
20470 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 1
20480 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
20490 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 LIMIT_COLUMN
204a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
204b0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
204c0 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 _LIMIT_EXPR_DEPT
204d0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 H
204e0 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 3.#define SQLIT
204f0 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 E_LIMIT_COMPOUND
20500 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 _SELECT
20510 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 4.#define SQLI
20520 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 TE_LIMIT_VDBE_OP
20530 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
20540 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 5.#define SQL
20550 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 ITE_LIMIT_FUNCTI
20560 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 ON_ARG
20570 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 6.#define SQ
20580 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 LITE_LIMIT_ATTAC
20590 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 HED
205a0 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 7.#define S
205b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 QLITE_LIMIT_LIKE
205c0 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 _PATTERN_LENGTH
205d0 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 8.#define
205e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 SQLITE_LIMIT_VAR
205f0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 IABLE_NUMBER
20600 20 20 20 20 20 20 20 39 0a 0a 2f 2a 0a 2a 2a 20 9../*.**
20610 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c CAPI3REF: Compil
20620 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 ing An SQL State
20630 6d 65 6e 74 20 7b 48 31 33 30 31 30 7d 20 3c 53 ment {H13010} <S
20640 31 30 30 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 10000>.** KEYWOR
20650 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 DS: {SQL stateme
20660 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a nt compiler}.**.
20670 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e ** To execute an
20680 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d SQL query, it m
20690 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d ust first be com
206a0 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 piled into a byt
206b0 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 e-code.** progra
206c0 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 m using one of t
206d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a hese routines..*
206e0 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 *.** The first a
206f0 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 rgument, "db", i
20700 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f s a [database co
20710 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e nnection] obtain
20720 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 ed from a.** pri
20730 6f 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 or call to [sqli
20740 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 te3_open()], [sq
20750 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d lite3_open_v2()]
20760 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 or [sqlite3_ope
20770 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 n16()]..**.** Th
20780 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
20790 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 t, "zSql", is th
207a0 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 e statement to b
207b0 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f e compiled, enco
207c0 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 ded.** as either
207d0 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 UTF-8 or UTF-16
207e0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 . The sqlite3_p
207f0 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c repare() and sql
20800 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
20810 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 ).** interfaces
20820 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 use UTF-8, and s
20830 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
20840 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 () and sqlite3_p
20850 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a repare16_v2().**
20860 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a use UTF-16..**.
20870 2a 2a 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 ** If the nByte
20880 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 argument is less
20890 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e than zero, then
208a0 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 zSql is read up
208b0 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 to the.** first
208c0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 zero terminator
208d0 2e 20 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f . If nByte is no
208e0 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e n-negative, then
208f0 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d it is the maxim
20900 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 um.** number of
20910 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d bytes read from
20920 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20 6e 42 79 zSql. When nBy
20930 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 te is non-negati
20940 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 ve, the.** zSql
20950 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 string ends at e
20960 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20 ither the first
20970 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 '\000' or '\u000
20980 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 0' character or.
20990 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 ** the nByte-th
209a0 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 byte, whichever
209b0 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 comes first. If
209c0 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 the caller knows
209d0 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 .** that the sup
209e0 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 plied string is
209f0 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 nul-terminated,
20a00 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 then there is a
20a10 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d small.** perform
20a20 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 ance advantage t
20a30 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 o be gained by p
20a40 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 assing an nByte
20a50 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a parameter that.*
20a60 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 * is equal to th
20a70 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
20a80 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 s in the input s
20a90 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 tring <i>includi
20aa0 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 ng</i>.** the nu
20ab0 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 l-terminator byt
20ac0 65 73 2e 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61 69 es..**.** *pzTai
20ad0 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 l is made to poi
20ae0 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 nt to the first
20af0 62 79 74 65 20 70 61 73 74 20 74 68 65 20 65 6e byte past the en
20b00 64 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 d of the.** firs
20b10 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 t SQL statement
20b20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 in zSql. These
20b30 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 20 63 6f routines only co
20b40 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 0a mpile the first.
20b50 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 ** statement in
20b60 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c zSql, so *pzTail
20b70 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e is left pointin
20b80 67 20 74 6f 20 77 68 61 74 20 72 65 6d 61 69 6e g to what remain
20b90 73 0a 2a 2a 20 75 6e 63 6f 6d 70 69 6c 65 64 2e s.** uncompiled.
20ba0 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69 .**.** *ppStmt i
20bb0 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 s left pointing
20bc0 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 to a compiled [p
20bd0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
20be0 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a t] that can be.*
20bf0 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 * executed using
20c00 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
20c10 5d 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 ]. If there is
20c20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d an error, *ppStm
20c30 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e t is set.** to N
20c40 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 69 6e 70 ULL. If the inp
20c50 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 ut text contains
20c60 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 no SQL (if the
20c70 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 input is an empt
20c80 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 y.** string or a
20c90 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a comment) then *
20ca0 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f ppStmt is set to
20cb0 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b 41 31 33 30 31 NULL..** {A1301
20cc0 38 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 8} The calling p
20cd0 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 rocedure is resp
20ce0 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 onsible for dele
20cf0 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 ting the compile
20d00 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 d.** SQL stateme
20d10 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 nt using [sqlite
20d20 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 3_finalize()] af
20d30 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 ter it has finis
20d40 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 0a hed with it..**.
20d50 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b ** On success, [
20d60 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 SQLITE_OK] is re
20d70 74 75 72 6e 65 64 2c 20 6f 74 68 65 72 77 69 73 turned, otherwis
20d80 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 e an [error code
20d90 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a ] is returned..*
20da0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
20db0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e _prepare_v2() an
20dc0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 d sqlite3_prepar
20dd0 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 e16_v2() interfa
20de0 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d ces are.** recom
20df0 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e mended for all n
20e00 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 ew programs. The
20e10 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 two older inter
20e20 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e faces are retain
20e30 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 ed.** for backwa
20e40 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 rds compatibilit
20e50 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 y, but their use
20e60 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e is discouraged.
20e70 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76 32 22 20 .** In the "v2"
20e80 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 interfaces, the
20e90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
20ea0 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 nt.** that is re
20eb0 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c turned (the [sql
20ec0 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 ite3_stmt] objec
20ed0 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f t) contains a co
20ee0 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 py of the.** ori
20ef0 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 ginal SQL text.
20f00 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 This causes the
20f10 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
20f20 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a interface to.**
20f30 20 62 65 68 61 76 65 20 61 20 64 69 66 66 65 72 behave a differ
20f40 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20 77 61 79 ently in two way
20f50 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a s:.**.** <ol>.**
20f60 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20 <li>.** If the
20f70 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 database schema
20f80 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 changes, instead
20f90 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 of returning [S
20fa0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 QLITE_SCHEMA] as
20fb0 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 it.** always us
20fc0 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 ed to do, [sqlit
20fd0 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 e3_step()] will
20fe0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 automatically re
20ff0 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a compile the SQL.
21000 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 ** statement and
21010 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 try to run it a
21020 67 61 69 6e 2e 20 20 49 66 20 74 68 65 20 73 63 gain. If the sc
21030 68 65 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64 hema has changed
21040 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68 61 in.** a way tha
21050 74 20 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74 t makes the stat
21060 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 ement no longer
21070 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f valid, [sqlite3_
21080 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 step()] will sti
21090 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 ll.** return [SQ
210a0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42 LITE_SCHEMA]. B
210b0 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 ut unlike the le
210c0 67 61 63 79 20 62 65 68 61 76 69 6f 72 2c 20 5b gacy behavior, [
210d0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 69 SQLITE_SCHEMA] i
210e0 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c s.** now a fatal
210f0 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 error. Calling
21100 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
21110 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20 77 69 e_v2()] again wi
21120 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a ll not make the.
21130 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77 61 79 ** error go away
21140 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71 . Note: use [sq
21150 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 lite3_errmsg()]
21160 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65 78 74 to find the text
21170 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 72 73 69 .** of the parsi
21180 6e 67 20 65 72 72 6f 72 20 74 68 61 74 20 72 65 ng error that re
21190 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c sults in an [SQL
211a0 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 75 ITE_SCHEMA] retu
211b0 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a rn..** </li>.**.
211c0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20 ** <li>.** When
211d0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c an error occurs,
211e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
211f0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e ] will return on
21200 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 e of the detaile
21210 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 d.** [error code
21220 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 s] or [extended
21230 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 54 error codes]. T
21240 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 he legacy behavi
21250 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b or was that.** [
21260 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
21270 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 would only retur
21280 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c n a generic [SQL
21290 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c ITE_ERROR] resul
212a0 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 79 6f t code.** and yo
212b0 75 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 u would have to
212c0 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 make a second ca
212d0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 ll to [sqlite3_r
212e0 65 73 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 72 eset()] in order
212f0 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 .** to find the
21300 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 underlying cause
21310 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e of the problem.
21320 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 With the "v2" p
21330 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 repare.** interf
21340 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c aces, the underl
21350 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 ying reason for
21360 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 the error is ret
21370 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c urned immediatel
21380 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c y..** </li>.** <
21390 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 /ol>.**.** INVAR
213a0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 IANTS:.**.** {H1
213b0 33 30 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 3011} The [sqlit
213c0 65 33 5f 70 72 65 70 61 72 65 28 64 62 2c 7a 53 e3_prepare(db,zS
213d0 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20 ql,...)] and.**
213e0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
213f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 3_prepare_v2(db,
21400 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 zSql,...)] inter
21410 66 61 63 65 73 20 69 6e 74 65 72 70 72 65 74 20 faces interpret
21420 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
21430 74 65 78 74 20 69 6e 20 74 68 65 69 72 20 7a 53 text in their zS
21440 71 6c 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 ql parameter as
21450 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 UTF-8..**.** {H1
21460 33 30 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 3012} The [sqlit
21470 65 33 5f 70 72 65 70 61 72 65 31 36 28 64 62 2c e3_prepare16(db,
21480 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a zSql,...)] and.*
21490 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
214a0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
214b0 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 (db,zSql,...)] i
214c0 6e 74 65 72 66 61 63 65 73 20 69 6e 74 65 72 70 nterfaces interp
214d0 72 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 ret the.**
214e0 20 20 20 20 74 65 78 74 20 69 6e 20 74 68 65 69 text in thei
214f0 72 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 72 r zSql parameter
21500 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 as UTF-16 in th
21510 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 e native byte or
21520 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 der..**.** {H130
21530 31 33 7d 20 49 66 20 74 68 65 20 6e 42 79 74 65 13} If the nByte
21540 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 argument to [sq
21550 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
21560 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e (db,zSql,nByte,.
21570 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 ..)].**
21580 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 and its variant
21590 73 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a s is less than z
215a0 65 72 6f 2c 20 74 68 65 20 53 51 4c 20 74 65 78 ero, the SQL tex
215b0 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 t is.**
215c0 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 20 read from zSql
215d0 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 is read up to th
215e0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 e first zero ter
215f0 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b minator..**.** {
21600 48 31 33 30 31 34 7d 20 49 66 20 74 68 65 20 6e H13014} If the n
21610 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 74 6f Byte argument to
21620 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
21630 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 e_v2(db,zSql,nBy
21640 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 te,...)].**
21650 20 20 20 20 20 61 6e 64 20 69 74 73 20 76 61 72 and its var
21660 69 61 6e 74 73 20 69 73 20 6e 6f 6e 2d 6e 65 67 iants is non-neg
21670 61 74 69 76 65 2c 20 74 68 65 6e 20 61 74 20 6d ative, then at m
21680 6f 73 74 20 6e 42 79 74 65 73 20 62 79 74 65 73 ost nBytes bytes
21690 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 of.**
216a0 53 51 4c 20 74 65 78 74 20 69 73 20 72 65 61 64 SQL text is read
216b0 20 66 72 6f 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a 2a from zSql..**.*
216c0 2a 20 7b 48 31 33 30 31 35 7d 20 49 6e 20 5b 73 * {H13015} In [s
216d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
216e0 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 50 2c 70 7a 2(db,zSql,N,P,pz
216f0 54 61 69 6c 29 5d 20 61 6e 64 20 69 74 73 20 76 Tail)] and its v
21700 61 72 69 61 6e 74 73 0a 2a 2a 20 20 20 20 20 20 ariants.**
21710 20 20 20 20 69 66 20 74 68 65 20 7a 53 71 6c 20 if the zSql
21720 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 input text conta
21730 69 6e 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e ins more than on
21740 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a e SQL statement.
21750 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 ** and
21760 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 pzTail is not NU
21770 4c 4c 2c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c LL, then *pzTail
21780 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e is made to poin
21790 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 t to the.**
217a0 20 20 20 20 20 66 69 72 73 74 20 62 79 74 65 20 first byte
217b0 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 past the end of
217c0 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 the first SQL st
217d0 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e atement in zSql.
217e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f .** <to
217f0 64 6f 3e 57 68 61 74 20 64 6f 65 73 20 2a 70 7a do>What does *pz
21800 54 61 69 6c 20 70 6f 69 6e 74 20 74 6f 20 69 66 Tail point to if
21810 20 74 68 65 72 65 20 69 73 20 6f 6e 65 20 73 74 there is one st
21820 61 74 65 6d 65 6e 74 3f 3c 2f 74 6f 64 6f 3e 0a atement?</todo>.
21830 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 36 7d 20 41 **.** {H13016} A
21840 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c successful call
21850 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 to [sqlite3_pre
21860 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c pare_v2(db,zSql,
21870 4e 2c 70 70 53 74 6d 74 2c 2e 2e 2e 29 5d 0a 2a N,ppStmt,...)].*
21880 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 6f 6e * or on
21890 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 e of its variant
218a0 73 20 77 72 69 74 65 73 20 69 6e 74 6f 20 2a 70 s writes into *p
218b0 70 53 74 6d 74 20 61 20 70 6f 69 6e 74 65 72 20 pStmt a pointer
218c0 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 to a new.**
218d0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 [prepared s
218e0 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 61 20 70 tatement] or a p
218f0 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20 69 ointer to NULL i
21900 66 20 7a 53 71 6c 20 63 6f 6e 74 61 69 6e 73 0a f zSql contains.
21910 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 74 68 ** noth
21920 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 77 ing other than w
21930 68 69 74 65 73 70 61 63 65 20 6f 72 20 63 6f 6d hitespace or com
21940 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ments..**.** {H1
21950 33 30 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 3019} The [sqlit
21960 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
21970 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 20 69 interface and i
21980 74 73 20 76 61 72 69 61 6e 74 73 20 72 65 74 75 ts variants retu
21990 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b rn.** [
219a0 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 61 6e SQLITE_OK] or an
219b0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 appropriate [er
219c0 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 20 66 ror code] upon f
219d0 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ailure..**.** {H
219e0 31 33 30 32 31 7d 20 42 65 66 6f 72 65 20 5b 73 13021} Before [s
219f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 64 qlite3_prepare(d
21a00 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 70 70 53 b,zSql,nByte,ppS
21a10 74 6d 74 2c 70 7a 54 61 69 6c 29 5d 20 6f 72 20 tmt,pzTail)] or
21a20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 its.**
21a30 76 61 72 69 61 6e 74 73 20 72 65 74 75 72 6e 73 variants returns
21a40 20 61 6e 20 65 72 72 6f 72 20 28 61 6e 79 20 76 an error (any v
21a50 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 alue other than
21a60 5b 53 51 4c 49 54 45 5f 4f 4b 5d 29 2c 0a 2a 2a [SQLITE_OK]),.**
21a70 20 20 20 20 20 20 20 20 20 20 74 68 65 79 20 66 they f
21a80 69 72 73 74 20 73 65 74 20 2a 70 70 53 74 6d 74 irst set *ppStmt
21a90 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 to NULL..*/.int
21aa0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
21ab0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
21ac0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 /* D
21ad0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a atabase handle *
21ae0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
21af0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 zSql, /* S
21b00 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 QL statement, UT
21b10 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 F-8 encoded */.
21b20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 int nByte,
21b30 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 /* Maxi
21b40 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 mum length of zS
21b50 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a ql in bytes. */.
21b60 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a sqlite3_stmt *
21b70 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 *ppStmt, /* OUT
21b80 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 : Statement hand
21b90 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 le */. const ch
21ba0 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 ar **pzTail
21bb0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 /* OUT: Pointer
21bc0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f to unused portio
21bd0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a n of zSql */.);.
21be0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 int sqlite3_prep
21bf0 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 are_v2(. sqlite
21c00 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
21c10 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 /* Database ha
21c20 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
21c30 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 char *zSql,
21c40 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 /* SQL stateme
21c50 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 nt, UTF-8 encode
21c60 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 d */. int nByte
21c70 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f , /
21c80 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 * Maximum length
21c90 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 of zSql in byte
21ca0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f s. */. sqlite3_
21cb0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 stmt **ppStmt,
21cc0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e /* OUT: Statemen
21cd0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f t handle */. co
21ce0 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 nst char **pzTai
21cf0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f l /* OUT: Po
21d00 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 inter to unused
21d10 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 portion of zSql
21d20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 */.);.int sqlite
21d30 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 3_prepare16(. s
21d40 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
21d50 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
21d60 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 se handle */. c
21d70 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c onst void *zSql,
21d80 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 /* SQL st
21d90 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 atement, UTF-16
21da0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 encoded */. int
21db0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 nByte,
21dc0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 /* Maximum
21dd0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 length of zSql i
21de0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 n bytes. */. sq
21df0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 lite3_stmt **ppS
21e00 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 tmt, /* OUT: St
21e10 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a atement handle *
21e20 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a /. const void *
21e30 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f *pzTail /* O
21e40 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 UT: Pointer to u
21e50 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 nused portion of
21e60 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 zSql */.);.int
21e70 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
21e80 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 6_v2(. sqlite3
21e90 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
21ea0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 /* Database hand
21eb0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f le */. const vo
21ec0 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 id *zSql,
21ed0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 /* SQL statement
21ee0 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 , UTF-16 encoded
21ef0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c */. int nByte,
21f00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
21f10 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 Maximum length
21f20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 of zSql in bytes
21f30 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 . */. sqlite3_s
21f40 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f tmt **ppStmt, /
21f50 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 * OUT: Statement
21f60 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
21f70 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c st void **pzTail
21f80 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 /* OUT: Poi
21f90 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 nter to unused p
21fa0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a ortion of zSql *
21fb0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.);../*.** CAPI
21fc0 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 3REF: Retrieving
21fd0 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b Statement SQL {
21fe0 48 31 33 31 30 30 7d 20 3c 48 31 33 30 30 30 3e H13100} <H13000>
21ff0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 .**.** This inte
22000 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 rface can be use
22010 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 d to retrieve a
22020 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 saved copy of th
22030 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 e original.** SQ
22040 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 L text used to c
22050 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 reate a [prepare
22060 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 d statement] if
22070 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 that statement w
22080 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 as.** compiled u
22090 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c sing either [sql
220a0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
220b0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 )] or [sqlite3_p
220c0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a repare16_v2()]..
220d0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
220e0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30 31 7d :.**.** {H13101}
220f0 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 If the [prepare
22100 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 61 73 d statement] pas
22110 73 65 64 20 61 73 20 74 68 65 20 61 72 67 75 6d sed as the argum
22120 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 ent to.**
22130 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 [sqlite3_sql(
22140 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 )] was compiled
22150 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 using either [sq
22160 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
22170 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 ()] or.**
22180 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 [sqlite3_prep
22190 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 74 68 65 are16_v2()], the
221a0 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 n [sqlite3_sql()
221b0 5d 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 ] returns.**
221c0 20 20 20 20 20 20 61 20 70 6f 69 6e 74 65 72 20 a pointer
221d0 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e to a zero-termin
221e0 61 74 65 64 20 73 74 72 69 6e 67 20 63 6f 6e 74 ated string cont
221f0 61 69 6e 69 6e 67 20 61 20 55 54 46 2d 38 20 72 aining a UTF-8 r
22200 65 6e 64 65 72 69 6e 67 0a 2a 2a 20 20 20 20 20 endering.**
22210 20 20 20 20 20 6f 66 20 74 68 65 20 6f 72 69 67 of the orig
22220 69 6e 61 6c 20 53 51 4c 20 73 74 61 74 65 6d 65 inal SQL stateme
22230 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30 nt..**.** {H1310
22240 32 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 2} If the [prepa
22250 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 red statement] p
22260 61 73 73 65 64 20 61 73 20 74 68 65 20 61 72 67 assed as the arg
22270 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 ument to.**
22280 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 71 [sqlite3_sq
22290 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c 65 l()] was compile
222a0 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b d using either [
222b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
222c0 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 )] or.**
222d0 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 [sqlite3_prepa
222e0 72 65 31 36 28 29 5d 2c 20 74 68 65 6e 20 5b 73 re16()], then [s
222f0 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 72 65 qlite3_sql()] re
22300 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 turns a NULL poi
22310 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 nter..**.** {H13
22320 31 30 33 7d 20 54 68 65 20 73 74 72 69 6e 67 20 103} The string
22330 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c returned by [sql
22340 69 74 65 33 5f 73 71 6c 28 53 29 5d 20 69 73 20 ite3_sql(S)] is
22350 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 0a valid until the.
22360 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 ** [pre
22370 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
22380 20 53 20 69 73 20 64 65 6c 65 74 65 64 20 75 73 S is deleted us
22390 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e ing [sqlite3_fin
223a0 61 6c 69 7a 65 28 53 29 5d 2e 0a 2a 2f 0a 63 6f alize(S)]..*/.co
223b0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
223c0 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 3_sql(sqlite3_st
223d0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a mt *pStmt);../*.
223e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e ** CAPI3REF: Dyn
223f0 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 amically Typed V
22400 61 6c 75 65 20 4f 62 6a 65 63 74 20 7b 48 31 35 alue Object {H15
22410 30 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 000} <S20200>.**
22420 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 KEYWORDS: {prot
22430 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
22440 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 lue} {unprotecte
22450 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d d sqlite3_value}
22460 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 .**.** SQLite us
22470 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 es the sqlite3_v
22480 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 alue object to r
22490 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c epresent all val
224a0 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 ues.** that can
224b0 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 be stored in a d
224c0 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 atabase table. S
224d0 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d QLite uses dynam
224e0 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 ic typing.** for
224f0 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 the values it s
22500 74 6f 72 65 73 2e 20 56 61 6c 75 65 73 20 73 74 tores. Values st
22510 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f ored in sqlite3_
22520 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a value objects.**
22530 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 can be integers
22540 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 , floating point
22550 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 values, strings
22560 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c , BLOBs, or NULL
22570 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 ..**.** An sqlit
22580 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 e3_value object
22590 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 may be either "p
225a0 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e rotected" or "un
225b0 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 protected"..** S
225c0 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 ome interfaces r
225d0 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 equire a protect
225e0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
225f0 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 . Other interfa
22600 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 ces.** will acce
22610 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 pt either a prot
22620 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 ected or an unpr
22630 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
22640 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 value..** Every
22650 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 interface that a
22660 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 ccepts sqlite3_v
22670 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 alue arguments s
22680 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 pecifies.** whet
22690 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 her or not it re
226a0 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 quires a protect
226b0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
226c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d ..**.** The term
226d0 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e s "protected" an
226e0 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 d "unprotected"
226f0 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 refer to whether
22700 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 or not.** a mut
22710 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 20 69 ex is held. A i
22720 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 nternal mutex is
22730 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 held for a prot
22740 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ected.** sqlite3
22750 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 _value object bu
22760 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 t no mutex is he
22770 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 ld for an unprot
22780 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ected.** sqlite3
22790 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 _value object.
227a0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
227b0 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 piled to be sing
227c0 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 le-threaded.** (
227d0 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 with [SQLITE_THR
227e0 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 EADSAFE=0] and w
227f0 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 ith [sqlite3_thr
22800 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 eadsafe()] retur
22810 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 ning 0).** or if
22820 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 SQLite is run i
22830 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 n one of reduced
22840 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a mutex modes .**
22850 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
22860 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 SINGLETHREAD] or
22870 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
22880 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 MULTITHREAD].**
22890 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f then there is no
228a0 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 distinction bet
228b0 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 ween protected a
228c0 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a nd unprotected.*
228d0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 * sqlite3_value
228e0 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 objects and they
228f0 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 can be used int
22900 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 erchangeably. H
22910 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d owever,.** for m
22920 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 aximum code port
22930 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 ability it is re
22940 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 commended that a
22950 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 pplications.** s
22960 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 till make the di
22970 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 stinction betwee
22980 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 n between protec
22990 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 ted and unprotec
229a0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 ted.** sqlite3_v
229b0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 alue objects eve
229c0 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 n when not stric
229d0 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a tly required..**
229e0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
229f0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 value objects th
22a00 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 at are passed as
22a10 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f parameters into
22a20 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e the.** implemen
22a30 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 tation of [appli
22a40 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 cation-defined S
22a50 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 QL functions] ar
22a60 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 e protected..**
22a70 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 The sqlite3_valu
22a80 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 e object returne
22a90 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 d by.** [sqlite3
22aa0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d _column_value()]
22ab0 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e is unprotected.
22ac0 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 .** Unprotected
22ad0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
22ae0 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 jects may only b
22af0 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b e used with.** [
22b00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 sqlite3_result_v
22b10 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c alue()] and [sql
22b20 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 ite3_bind_value(
22b30 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 )]..** The [sqli
22b40 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c te3_value_blob |
22b50 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
22b60 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 ype()] family of
22b70 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 .** interfaces r
22b80 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 equire protected
22b90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
22ba0 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 bjects..*/.typed
22bb0 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 ef struct Mem sq
22bc0 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a lite3_value;../*
22bd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 .** CAPI3REF: SQ
22be0 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 L Function Conte
22bf0 78 74 20 4f 62 6a 65 63 74 20 7b 48 31 36 30 30 xt Object {H1600
22c00 31 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 1} <S20200>.**.*
22c10 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e * The context in
22c20 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 which an SQL fu
22c30 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 nction executes
22c40 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a is stored in an.
22c50 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ** sqlite3_conte
22c60 78 74 20 6f 62 6a 65 63 74 2e 20 20 41 20 70 6f xt object. A po
22c70 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 inter to an sqli
22c80 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 te3_context obje
22c90 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 ct.** is always
22ca0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
22cb0 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d to [application-
22cc0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
22cd0 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 tions]..** The a
22ce0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
22cf0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 ed SQL function
22d00 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 implementation w
22d10 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a ill pass this.**
22d20 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 pointer through
22d30 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b into calls to [
22d40 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 sqlite3_result_i
22d50 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 nt | sqlite3_res
22d60 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 ult()],.** [sqli
22d70 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
22d80 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 ntext()], [sqlit
22d90 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c e3_user_data()],
22da0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
22db0 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 text_db_handle()
22dc0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f ], [sqlite3_get_
22dd0 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 auxdata()],.** a
22de0 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 nd/or [sqlite3_s
22df0 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a et_auxdata()]..*
22e00 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
22e10 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
22e20 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
22e30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
22e40 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 F: Binding Value
22e50 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 s To Prepared St
22e60 61 74 65 6d 65 6e 74 73 20 7b 48 31 33 35 30 30 atements {H13500
22e70 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 20 4b 45 } <S70300>.** KE
22e80 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 YWORDS: {host pa
22e90 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 rameter} {host p
22ea0 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 arameters} {host
22eb0 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d parameter name}
22ec0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 .** KEYWORDS: {S
22ed0 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 QL parameter} {S
22ee0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b QL parameters} {
22ef0 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e parameter bindin
22f00 67 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 g}.**.** In the
22f10 53 51 4c 20 73 74 72 69 6e 67 73 20 69 6e 70 75 SQL strings inpu
22f20 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 t to [sqlite3_pr
22f30 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 epare_v2()] and
22f40 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a its variants,.**
22f50 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 literals may be
22f60 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 70 replaced by a p
22f70 61 72 61 6d 65 74 65 72 20 69 6e 20 6f 6e 65 20 arameter in one
22f80 6f 66 20 74 68 65 73 65 20 66 6f 72 6d 73 3a 0a of these forms:.
22f90 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
22fa0 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f i> ?.** <li> ?
22fb0 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 NNN.** <li> :VV
22fc0 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a V.** <li> @VVV.
22fd0 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a ** <li> $VVV.**
22fe0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 </ul>.**.** In
22ff0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 66 6f the parameter fo
23000 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 rms shown above
23010 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65 67 65 NNN is an intege
23020 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e r literal,.** an
23030 64 20 56 56 56 20 69 73 20 61 6e 20 61 6c 70 68 d VVV is an alph
23040 61 2d 6e 75 6d 65 72 69 63 20 70 61 72 61 6d 65 a-numeric parame
23050 74 65 72 20 6e 61 6d 65 2e 20 54 68 65 20 76 61 ter name. The va
23060 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a lues of these.**
23070 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 parameters (als
23080 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 o called "host p
23090 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 arameter names"
230a0 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 or "SQL paramete
230b0 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 rs").** can be s
230c0 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c et using the sql
230d0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f ite3_bind_*() ro
230e0 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 utines defined h
230f0 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 ere..**.** The f
23100 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
23110 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e the sqlite3_bin
23120 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 d_*() routines i
23130 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f s always.** a po
23140 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 inter to the [sq
23150 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 lite3_stmt] obje
23160 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d ct returned from
23170 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
23180 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 pare_v2()] or it
23190 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a s variants..**.*
231a0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 * The second arg
231b0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 ument is the ind
231c0 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 ex of the SQL pa
231d0 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 rameter to be se
231e0 74 2e 0a 2a 2a 20 54 68 65 20 6c 65 66 74 6d 6f t..** The leftmo
231f0 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 st SQL parameter
23200 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 has an index of
23210 20 31 2e 20 20 57 68 65 6e 20 74 68 65 20 73 61 1. When the sa
23220 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 me named.** SQL
23230 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 parameter is use
23240 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 d more than once
23250 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 , second and sub
23260 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 sequent.** occur
23270 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 rences have the
23280 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 same index as th
23290 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e e first occurren
232a0 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6e 64 65 78 ce..** The index
232b0 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d for named param
232c0 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f eters can be loo
232d0 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 ked up using the
232e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
232f0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 d_parameter_inde
23300 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 x()] API if desi
23310 72 65 64 2e 20 20 54 68 65 20 69 6e 64 65 78 0a red. The index.
23320 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 ** for "?NNN" pa
23330 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 rameters is the
23340 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a value of NNN..**
23350 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d The NNN value m
23360 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 ust be between 1
23370 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 and the [sqlite
23380 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 3_limit()].** pa
23390 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f rameter [SQLITE_
233a0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e LIMIT_VARIABLE_N
233b0 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 UMBER] (default
233c0 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a value: 999)..**.
233d0 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 72 67 ** The third arg
233e0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c ument is the val
233f0 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 ue to bind to th
23400 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a e parameter..**.
23410 2a 2a 20 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 ** In those rout
23420 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 ines that have a
23430 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 fourth argument
23440 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 , its value is t
23450 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 he.** number of
23460 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 bytes in the par
23470 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 ameter. To be c
23480 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 lear: the value
23490 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 is the.** number
234a0 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e of <u>bytes</u>
234b0 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e in the value, n
234c0 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ot the number of
234d0 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 characters..**
234e0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 If the fourth pa
234f0 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 rameter is negat
23500 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 ive, the length
23510 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 of the string is
23520 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f .** the number o
23530 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 f bytes up to th
23540 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 e first zero ter
23550 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 minator..**.** T
23560 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e he fifth argumen
23570 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e t to sqlite3_bin
23580 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 d_blob(), sqlite
23590 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 3_bind_text(), a
235a0 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 nd.** sqlite3_bi
235b0 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 nd_text16() is a
235c0 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 destructor used
235d0 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 to dispose of t
235e0 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 he BLOB or.** st
235f0 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 ring after SQLit
23600 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 e has finished w
23610 69 74 68 20 69 74 2e 20 49 66 20 74 68 65 20 66 ith it. If the f
23620 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 ifth argument is
23630 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 .** the special
23640 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 value [SQLITE_ST
23650 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 ATIC], then SQLi
23660 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 te assumes that
23670 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 the.** informati
23680 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c on is in static,
23690 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 unmanaged space
236a0 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 and does not ne
236b0 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a ed to be freed..
236c0 2a 2a 20 49 66 20 74 68 65 20 66 69 66 74 68 20 ** If the fifth
236d0 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 argument has the
236e0 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 value [SQLITE_T
236f0 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a RANSIENT], then.
23700 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 ** SQLite makes
23710 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 its own private
23720 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 copy of the data
23730 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 immediately, be
23740 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 fore.** the sqli
23750 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
23760 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a tine returns..**
23770 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
23780 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 bind_zeroblob()
23790 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 routine binds a
237a0 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e BLOB of length N
237b0 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c that.** is fill
237c0 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 ed with zeroes.
237d0 20 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 A zeroblob uses
237e0 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 a fixed amount
237f0 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 of memory.** (ju
23800 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f st an integer to
23810 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 hold its size)
23820 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e while it is bein
23830 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 g processed..**
23840 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e Zeroblobs are in
23850 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 tended to serve
23860 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 as placeholders
23870 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a for BLOBs whose.
23880 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 ** content is la
23890 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e ter written usin
238a0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c g.** [sqlite3_bl
238b0 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d ob_open | increm
238c0 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 ental BLOB I/O]
238d0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 41 20 6e routines..** A n
238e0 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f egative value fo
238f0 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 r the zeroblob r
23900 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f esults in a zero
23910 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a -length BLOB..**
23920 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
23930 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 bind_*() routine
23940 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 s must be called
23950 20 61 66 74 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 after.** [sqlit
23960 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
23970 20 28 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e (and its varian
23980 74 73 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ts) or [sqlite3_
23990 72 65 73 65 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 reset()] and.**
239a0 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f before [sqlite3_
239b0 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 step()]..** Bind
239c0 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 ings are not cle
239d0 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c ared by the [sql
239e0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f ite3_reset()] ro
239f0 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e utine..** Unboun
23a00 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 d parameters are
23a10 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
23a20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 NULL..**.** Thes
23a30 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 e routines retur
23a40 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e n [SQLITE_OK] on
23a50 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 20 65 success or an e
23a60 72 72 6f 72 20 63 6f 64 65 20 69 66 0a 2a 2a 20 rror code if.**
23a70 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 anything goes wr
23a80 6f 6e 67 2e 20 20 5b 53 51 4c 49 54 45 5f 52 41 ong. [SQLITE_RA
23a90 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 NGE] is returned
23aa0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 if the paramete
23ab0 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 r.** index is ou
23ac0 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5b 53 51 t of range. [SQ
23ad0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 LITE_NOMEM] is r
23ae0 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f eturned if mallo
23af0 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53 c() fails..** [S
23b00 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 69 QLITE_MISUSE] mi
23b10 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 ght be returned
23b20 69 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 if these routine
23b30 73 20 61 72 65 20 63 61 6c 6c 65 64 20 6f 6e 20 s are called on
23b40 61 0a 2a 2a 20 76 69 72 74 75 61 6c 20 6d 61 63 a.** virtual mac
23b50 68 69 6e 65 20 74 68 61 74 20 69 73 20 74 68 65 hine that is the
23b60 20 77 72 6f 6e 67 20 73 74 61 74 65 20 6f 72 20 wrong state or
23b70 77 68 69 63 68 20 68 61 73 20 61 6c 72 65 61 64 which has alread
23b80 79 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 y been finalized
23b90 2e 0a 2a 2a 20 44 65 74 65 63 74 69 6f 6e 20 6f ..** Detection o
23ba0 66 20 6d 69 73 75 73 65 20 69 73 20 75 6e 72 65 f misuse is unre
23bb0 6c 69 61 62 6c 65 2e 20 20 41 70 70 6c 69 63 61 liable. Applica
23bc0 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 tions should not
23bd0 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 53 51 depend.** on SQ
23be0 4c 49 54 45 5f 4d 49 53 55 53 45 20 72 65 74 75 LITE_MISUSE retu
23bf0 72 6e 73 2e 20 20 53 51 4c 49 54 45 5f 4d 49 53 rns. SQLITE_MIS
23c00 55 53 45 20 69 73 20 69 6e 74 65 6e 64 65 64 20 USE is intended
23c10 74 6f 20 69 6e 64 69 63 61 74 65 20 61 0a 2a 2a to indicate a.**
23c20 20 61 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 a logic error i
23c30 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f n the applicatio
23c40 6e 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 n. Future versi
23c50 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 ons of SQLite mi
23c60 67 68 74 0a 2a 2a 20 70 61 6e 69 63 20 72 61 74 ght.** panic rat
23c70 68 65 72 20 74 68 61 6e 20 72 65 74 75 72 6e 20 her than return
23c80 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a SQLITE_MISUSE..*
23c90 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
23ca0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
23cb0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c ameter_count()],
23cc0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
23cd0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
23ce0 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 ()], and [sqlite
23cf0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
23d00 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a _index()]..**.**
23d10 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
23d20 2a 2a 20 7b 48 31 33 35 30 36 7d 20 54 68 65 20 ** {H13506} The
23d30 5b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 [SQL statement c
23d40 6f 6d 70 69 6c 65 72 5d 20 72 65 63 6f 67 6e 69 ompiler] recogni
23d50 7a 65 73 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 zes tokens of th
23d60 65 20 66 6f 72 6d 73 0a 2a 2a 20 20 20 20 20 20 e forms.**
23d70 20 20 20 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c "?", "?NNN",
23d80 20 22 24 56 56 56 22 2c 20 22 3a 56 56 56 22 2c "$VVV", ":VVV",
23d90 20 61 6e 64 20 22 40 56 56 56 22 20 61 73 20 53 and "@VVV" as S
23da0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 2c 0a 2a QL parameters,.*
23db0 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 72 65 * where
23dc0 20 4e 4e 4e 20 69 73 20 61 6e 79 20 73 65 71 75 NNN is any sequ
23dd0 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d ence of one or m
23de0 6f 72 65 20 64 69 67 69 74 73 0a 2a 2a 20 20 20 ore digits.**
23df0 20 20 20 20 20 20 20 61 6e 64 20 77 68 65 72 65 and where
23e00 20 56 56 56 20 69 73 20 61 6e 79 20 73 65 71 75 VVV is any sequ
23e10 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d ence of one or m
23e20 6f 72 65 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 ore alphanumeric
23e30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 68 61 .** cha
23e40 72 61 63 74 65 72 73 20 6f 72 20 22 3a 3a 22 20 racters or "::"
23e50 6f 70 74 69 6f 6e 61 6c 6c 79 20 66 6f 6c 6c 6f optionally follo
23e60 77 65 64 20 62 79 20 61 20 73 74 72 69 6e 67 20 wed by a string
23e70 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 20 20 containing.**
23e80 20 20 20 20 20 20 20 6e 6f 20 73 70 61 63 65 73 no spaces
23e90 20 61 6e 64 20 63 6f 6e 74 61 69 6e 65 64 20 77 and contained w
23ea0 69 74 68 69 6e 20 70 61 72 65 6e 74 68 65 73 65 ithin parenthese
23eb0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 30 39 s..**.** {H13509
23ec0 7d 20 54 68 65 20 69 6e 69 74 69 61 6c 20 76 61 } The initial va
23ed0 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 lue of an SQL pa
23ee0 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 2e rameter is NULL.
23ef0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 32 7d 20 .**.** {H13512}
23f00 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 The index of an
23f10 22 3f 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 "?" SQL paramete
23f20 72 20 69 73 20 6f 6e 65 20 6c 61 72 67 65 72 20 r is one larger
23f30 74 68 61 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 than the.**
23f40 20 20 20 20 20 6c 61 72 67 65 73 74 20 69 6e 64 largest ind
23f50 65 78 20 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 ex of SQL parame
23f60 74 65 72 20 74 6f 20 74 68 65 20 6c 65 66 74 2c ter to the left,
23f70 20 6f 72 20 31 20 69 66 0a 2a 2a 20 20 20 20 20 or 1 if.**
23f80 20 20 20 20 20 74 68 65 20 22 3f 22 20 69 73 20 the "?" is
23f90 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c the leftmost SQL
23fa0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a parameter..**.*
23fb0 2a 20 7b 48 31 33 35 31 35 7d 20 54 68 65 20 69 * {H13515} The i
23fc0 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f 4e 4e 4e ndex of an "?NNN
23fd0 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 " SQL parameter
23fe0 69 73 20 74 68 65 20 69 6e 74 65 67 65 72 20 4e is the integer N
23ff0 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 NN..**.** {H1351
24000 38 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 8} The index of
24010 61 6e 20 22 3a 56 56 56 22 2c 20 22 24 56 56 56 an ":VVV", "$VVV
24020 22 2c 20 6f 72 20 22 40 56 56 56 22 20 53 51 4c ", or "@VVV" SQL
24030 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a parameter is.**
24040 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61 the sa
24050 6d 65 20 61 73 20 74 68 65 20 69 6e 64 65 78 20 me as the index
24060 6f 66 20 6c 65 66 74 6d 6f 73 74 20 6f 63 63 75 of leftmost occu
24070 72 72 65 6e 63 65 73 20 6f 66 20 74 68 65 20 73 rrences of the s
24080 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ame.**
24090 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 6f 6e parameter, or on
240a0 65 20 6d 6f 72 65 20 74 68 61 6e 20 74 68 65 20 e more than the
240b0 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f 76 largest index ov
240c0 65 72 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 er all.**
240d0 20 20 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f parameters to
240e0 20 74 68 65 20 6c 65 66 74 20 69 66 20 74 68 69 the left if thi
240f0 73 20 69 73 20 74 68 65 20 66 69 72 73 74 20 6f s is the first o
24100 63 63 75 72 72 65 6e 63 65 0a 2a 2a 20 20 20 20 ccurrence.**
24110 20 20 20 20 20 20 6f 66 20 74 68 69 73 20 70 61 of this pa
24120 72 61 6d 65 74 65 72 2c 20 6f 72 20 31 20 69 66 rameter, or 1 if
24130 20 74 68 69 73 20 69 73 20 74 68 65 20 6c 65 66 this is the lef
24140 74 6d 6f 73 74 20 70 61 72 61 6d 65 74 65 72 2e tmost parameter.
24150 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 31 7d 20 .**.** {H13521}
24160 54 68 65 20 5b 53 51 4c 20 73 74 61 74 65 6d 65 The [SQL stateme
24170 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 66 61 69 nt compiler] fai
24180 6c 73 20 77 69 74 68 20 61 6e 20 5b 53 51 4c 49 ls with an [SQLI
24190 54 45 5f 52 41 4e 47 45 5d 0a 2a 2a 20 20 20 20 TE_RANGE].**
241a0 20 20 20 20 20 20 65 72 72 6f 72 20 69 66 20 74 error if t
241b0 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 he index of an S
241c0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 QL parameter is
241d0 6c 65 73 73 20 74 68 61 6e 20 31 0a 2a 2a 20 20 less than 1.**
241e0 20 20 20 20 20 20 20 20 6f 72 20 67 72 65 61 74 or great
241f0 65 72 20 74 68 61 6e 20 74 68 65 20 63 6f 6d 70 er than the comp
24200 69 6c 65 2d 74 69 6d 65 20 53 51 4c 49 54 45 5f ile-time SQLITE_
24210 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d MAX_VARIABLE_NUM
24220 42 45 52 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 BER.**
24230 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a parameter..**.**
24240 20 7b 48 31 33 35 32 34 7d 20 43 61 6c 6c 73 20 {H13524} Calls
24250 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 to [sqlite3_bind
24260 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33 5f _text | sqlite3_
24270 62 69 6e 64 28 53 2c 4e 2c 56 2c 2e 2e 2e 29 5d bind(S,N,V,...)]
24280 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 73 .** ass
24290 6f 63 69 61 74 65 20 74 68 65 20 76 61 6c 75 65 ociate the value
242a0 20 56 20 77 69 74 68 20 61 6c 6c 20 53 51 4c 20 V with all SQL
242b0 70 61 72 61 6d 65 74 65 72 73 20 68 61 76 69 6e parameters havin
242c0 67 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 g an.**
242d0 20 69 6e 64 65 78 20 6f 66 20 4e 20 69 6e 20 74 index of N in t
242e0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
242f0 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a tement] S..**.**
24300 20 7b 48 31 33 35 32 37 7d 20 43 61 6c 6c 73 20 {H13527} Calls
24310 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 to [sqlite3_bind
24320 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33 5f _text | sqlite3_
24330 62 69 6e 64 28 53 2c 4e 2c 2e 2e 2e 29 5d 0a 2a bind(S,N,...)].*
24340 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65 72 72 * overr
24350 69 64 65 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 ide prior calls
24360 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 76 61 with the same va
24370 6c 75 65 73 20 6f 66 20 53 20 61 6e 64 20 4e 2e lues of S and N.
24380 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 30 7d 20 .**.** {H13530}
24390 42 69 6e 64 69 6e 67 73 20 65 73 74 61 62 6c 69 Bindings establi
243a0 73 68 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 shed by [sqlite3
243b0 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c _bind_text | sql
243c0 69 74 65 33 5f 62 69 6e 64 28 53 2c 2e 2e 2e 29 ite3_bind(S,...)
243d0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 65 ].** pe
243e0 72 73 69 73 74 20 61 63 72 6f 73 73 20 63 61 6c rsist across cal
243f0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 ls to [sqlite3_r
24400 65 73 65 74 28 53 29 5d 2e 0a 2a 2a 0a 2a 2a 20 eset(S)]..**.**
24410 7b 48 31 33 35 33 33 7d 20 49 6e 20 63 61 6c 6c {H13533} In call
24420 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 s to [sqlite3_bi
24430 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c nd_blob(S,N,V,L,
24440 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 D)],.**
24450 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 [sqlite3_bind_t
24460 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c ext(S,N,V,L,D)],
24470 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 or.**
24480 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 [sqlite3_bind_te
24490 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d xt16(S,N,V,L,D)]
244a0 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20 74 68 SQLite binds th
244b0 65 20 66 69 72 73 74 20 4c 0a 2a 2a 20 20 20 20 e first L.**
244c0 20 20 20 20 20 20 62 79 74 65 73 20 6f 66 20 74 bytes of t
244d0 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e he BLOB or strin
244e0 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 g pointed to by
244f0 56 2c 20 77 68 65 6e 20 4c 0a 2a 2a 20 20 20 20 V, when L.**
24500 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d 6e 65 67 is non-neg
24510 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ative..**.** {H1
24520 33 35 33 36 7d 20 49 6e 20 63 61 6c 6c 73 20 74 3536} In calls t
24530 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f o [sqlite3_bind_
24540 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d text(S,N,V,L,D)]
24550 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 or.**
24560 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 [sqlite3_bind_te
24570 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d xt16(S,N,V,L,D)]
24580 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20 63 68 SQLite binds ch
24590 61 72 61 63 74 65 72 73 0a 2a 2a 20 20 20 20 20 aracters.**
245a0 20 20 20 20 20 66 72 6f 6d 20 56 20 74 68 72 6f from V thro
245b0 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 ugh the first ze
245c0 72 6f 20 63 68 61 72 61 63 74 65 72 20 77 68 65 ro character whe
245d0 6e 20 4c 20 69 73 20 6e 65 67 61 74 69 76 65 2e n L is negative.
245e0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 39 7d 20 .**.** {H13539}
245f0 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c In calls to [sql
24600 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 ite3_bind_blob(S
24610 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 ,N,V,L,D)],.**
24620 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
24630 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 _bind_text(S,N,V
24640 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 ,L,D)], or.**
24650 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
24660 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c bind_text16(S,N,
24670 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 V,L,D)] when D i
24680 73 20 74 68 65 20 73 70 65 63 69 61 6c 0a 2a 2a s the special.**
24690 20 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74 61 consta
246a0 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 nt [SQLITE_STATI
246b0 43 5d 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d C], SQLite assum
246c0 65 73 20 74 68 61 74 20 74 68 65 20 76 61 6c 75 es that the valu
246d0 65 20 56 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 e V.**
246e0 69 73 20 68 65 6c 64 20 69 6e 20 73 74 61 74 69 is held in stati
246f0 63 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 c unmanaged spac
24700 65 20 74 68 61 74 20 77 69 6c 6c 20 6e 6f 74 20 e that will not
24710 63 68 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20 change.**
24720 20 20 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 during the li
24730 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20 62 69 fetime of the bi
24740 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 nding..**.** {H1
24750 33 35 34 32 7d 20 49 6e 20 63 61 6c 6c 73 20 74 3542} In calls t
24760 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f o [sqlite3_bind_
24770 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d blob(S,N,V,L,D)]
24780 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 ,.** [s
24790 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
247a0 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 (S,N,V,L,D)], or
247b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
247c0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 lite3_bind_text1
247d0 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 6(S,N,V,L,D)] wh
247e0 65 6e 20 44 20 69 73 20 74 68 65 20 73 70 65 63 en D is the spec
247f0 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ial.**
24800 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 constant [SQLITE
24810 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 _TRANSIENT], the
24820 20 72 6f 75 74 69 6e 65 20 6d 61 6b 65 73 20 61 routine makes a
24830 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 69 .** pri
24840 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 vate copy of the
24850 20 76 61 6c 75 65 20 56 20 62 65 66 6f 72 65 20 value V before
24860 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a it returns..**.*
24870 2a 20 7b 48 31 33 35 34 35 7d 20 49 6e 20 63 61 * {H13545} In ca
24880 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
24890 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c bind_blob(S,N,V,
248a0 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 L,D)],.**
248b0 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 [sqlite3_bind
248c0 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 _text(S,N,V,L,D)
248d0 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 ], or.**
248e0 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f [sqlite3_bind_
248f0 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 text16(S,N,V,L,D
24900 29 5d 20 77 68 65 6e 20 44 20 69 73 20 61 20 70 )] when D is a p
24910 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 ointer to.**
24920 20 20 20 20 20 20 61 20 66 75 6e 63 74 69 6f 6e a function
24930 2c 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 , SQLite invokes
24940 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 74 that function t
24950 6f 20 64 65 73 74 72 6f 79 20 74 68 65 0a 2a 2a o destroy the.**
24960 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 value
24970 56 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 V after it has f
24980 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 inished using th
24990 65 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a e value V..**.**
249a0 20 7b 48 31 33 35 34 38 7d 20 49 6e 20 63 61 6c {H13548} In cal
249b0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 ls to [sqlite3_b
249c0 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 53 2c 4e ind_zeroblob(S,N
249d0 2c 56 2c 4c 29 5d 20 74 68 65 20 76 61 6c 75 65 ,V,L)] the value
249e0 20 62 6f 75 6e 64 0a 2a 2a 20 20 20 20 20 20 20 bound.**
249f0 20 20 20 69 73 20 61 20 42 4c 4f 42 20 6f 66 20 is a BLOB of
24a00 4c 20 62 79 74 65 73 2c 20 6f 72 20 61 20 7a 65 L bytes, or a ze
24a10 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 ro-length BLOB i
24a20 66 20 4c 20 69 73 20 6e 65 67 61 74 69 76 65 2e f L is negative.
24a30 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 35 31 7d 20 .**.** {H13551}
24a40 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c In calls to [sql
24a50 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 ite3_bind_value(
24a60 53 2c 4e 2c 56 29 5d 20 74 68 65 20 56 20 61 72 S,N,V)] the V ar
24a70 67 75 6d 65 6e 74 20 6d 61 79 0a 2a 2a 20 20 20 gument may.**
24a80 20 20 20 20 20 20 20 62 65 20 65 69 74 68 65 72 be either
24a90 20 61 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 a [protected sq
24aa0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
24ab0 65 63 74 20 6f 72 20 61 6e 0a 2a 2a 20 20 20 20 ect or an.**
24ac0 20 20 20 20 20 20 5b 75 6e 70 72 6f 74 65 63 74 [unprotect
24ad0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
24ae0 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 ] object..*/.int
24af0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c sqlite3_bind_bl
24b00 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ob(sqlite3_stmt*
24b10 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 , int, const voi
24b20 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 d*, int n, void(
24b30 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 *)(void*));.int
24b40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 sqlite3_bind_dou
24b50 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ble(sqlite3_stmt
24b60 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b *, int, double);
24b70 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
24b80 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 d_int(sqlite3_st
24b90 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a mt*, int, int);.
24ba0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
24bb0 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 _int64(sqlite3_s
24bc0 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 tmt*, int, sqlit
24bd0 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 e3_int64);.int s
24be0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c qlite3_bind_null
24bf0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
24c00 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 int);.int sqlite
24c10 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 3_bind_text(sqli
24c20 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
24c30 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 const char*, int
24c40 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 n, void(*)(void
24c50 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 *));.int sqlite3
24c60 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c _bind_text16(sql
24c70 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
24c80 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
24c90 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a t, void(*)(void*
24ca0 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f ));.int sqlite3_
24cb0 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 bind_value(sqlit
24cc0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 e3_stmt*, int, c
24cd0 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c onst sqlite3_val
24ce0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 ue*);.int sqlite
24cf0 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 3_bind_zeroblob(
24d00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
24d10 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a nt, int n);../*.
24d20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d ** CAPI3REF: Num
24d30 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d ber Of SQL Param
24d40 65 74 65 72 73 20 7b 48 31 33 36 30 30 7d 20 3c eters {H13600} <
24d50 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S70300>.**.** Th
24d60 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 is routine can b
24d70 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 e used to find t
24d80 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 he number of [SQ
24d90 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a L parameters].**
24da0 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 in a [prepared
24db0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c statement]. SQL
24dc0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 parameters are
24dd0 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a tokens of the.**
24de0 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e form "?", "?NNN
24df0 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 ", ":AAA", "$AAA
24e00 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 ", or "@AAA" tha
24e10 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c t serve as.** pl
24e20 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 aceholders for v
24e30 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b alues that are [
24e40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
24e50 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f b | bound].** to
24e60 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 the parameters
24e70 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e at a later time.
24e80 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
24e90 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 ine actually ret
24ea0 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f urns the index o
24eb0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 f the largest (r
24ec0 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 ightmost).** par
24ed0 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 ameter. For all
24ee0 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e forms except ?NN
24ef0 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 N, this will cor
24f00 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a respond to the.*
24f10 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 * number of uniq
24f20 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 ue parameters.
24f30 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 If parameters of
24f40 20 74 68 65 20 3f 4e 4e 4e 20 61 72 65 20 75 73 the ?NNN are us
24f50 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 ed,.** there may
24f60 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 be gaps in the
24f70 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 list..**.** See
24f80 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 also: [sqlite3_b
24f90 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 ind_blob|sqlite3
24fa0 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 _bind()],.** [sq
24fb0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
24fc0 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e eter_name()], an
24fd0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 d.** [sqlite3_bi
24fe0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 nd_parameter_ind
24ff0 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 ex()]..**.** INV
25000 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
25010 48 31 33 36 30 31 7d 20 54 68 65 20 5b 73 71 6c H13601} The [sql
25020 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
25030 74 65 72 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e ter_count(S)] in
25040 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a terface returns.
25050 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
25060 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f 66 largest index of
25070 20 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d 65 74 all SQL paramet
25080 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 ers in the.**
25090 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 [prepared
250a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 20 6f statement] S, o
250b0 72 20 30 20 69 66 20 53 20 63 6f 6e 74 61 69 6e r 0 if S contain
250c0 73 20 6e 6f 20 53 51 4c 20 70 61 72 61 6d 65 74 s no SQL paramet
250d0 65 72 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ers..*/.int sqli
250e0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
250f0 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 er_count(sqlite3
25100 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 _stmt*);../*.**
25110 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f CAPI3REF: Name O
25120 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 f A Host Paramet
25130 65 72 20 7b 48 31 33 36 32 30 7d 20 3c 53 37 30 er {H13620} <S70
25140 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 300>.**.** This
25150 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
25160 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
25170 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74 name of the n-t
25180 68 0a 2a 2a 20 5b 53 51 4c 20 70 61 72 61 6d 65 h.** [SQL parame
25190 74 65 72 5d 20 69 6e 20 61 20 5b 70 72 65 70 61 ter] in a [prepa
251a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a red statement]..
251b0 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 ** SQL parameter
251c0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f s of the form "?
251d0 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f NNN" or ":AAA" o
251e0 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 r "@AAA" or "$AA
251f0 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d A".** have a nam
25200 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 e which is the s
25210 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 tring "?NNN" or
25220 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 ":AAA" or "@AAA"
25230 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 or "$AAA".** re
25240 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 spectively..** I
25250 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 n other words, t
25260 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f he initial ":" o
25270 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 r "$" or "@" or
25280 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 "?".** is includ
25290 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 ed as part of th
252a0 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d e name..** Param
252b0 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 eters of the for
252c0 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 m "?" without a
252d0 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 following intege
252e0 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a r have no name.*
252f0 2a 20 61 6e 64 20 61 72 65 20 61 6c 73 6f 20 72 * and are also r
25300 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 61 eferred to as "a
25310 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 nonymous paramet
25320 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ers"..**.** The
25330 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d first host param
25340 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 eter has an inde
25350 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a x of 1, not 0..*
25360 2a 0a 2a 2a 20 49 66 20 74 68 65 20 76 61 6c 75 *.** If the valu
25370 65 20 6e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 e n is out of ra
25380 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 6e 2d nge or if the n-
25390 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a th parameter is.
253a0 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 ** nameless, the
253b0 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e n NULL is return
253c0 65 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 ed. The returne
253d0 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 d string is.** a
253e0 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 lways in UTF-8 e
253f0 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 ncoding even if
25400 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 the named parame
25410 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 ter was.** origi
25420 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 nally specified
25430 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 as UTF-16 in [sq
25440 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
25450 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 )] or.** [sqlite
25460 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
25470 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 ]..**.** See als
25480 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 o: [sqlite3_bind
25490 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 _blob|sqlite3_bi
254a0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 nd()],.** [sqlit
254b0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
254c0 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a r_count()], and.
254d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
254e0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 _parameter_index
254f0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 ()]..**.** INVAR
25500 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 IANTS:.**.** {H1
25510 33 36 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 3621} The [sqlit
25520 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
25530 72 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 r_name(S,N)] int
25540 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a erface returns.*
25550 2a 20 20 20 20 20 20 20 20 20 20 61 20 55 54 46 * a UTF
25560 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 -8 rendering of
25570 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
25580 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e SQL parameter in
25590 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
255a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
255b0 6d 65 6e 74 5d 20 53 20 68 61 76 69 6e 67 20 69 ment] S having i
255c0 6e 64 65 78 20 4e 2c 20 6f 72 0a 2a 2a 20 20 20 ndex N, or.**
255d0 20 20 20 20 20 20 20 4e 55 4c 4c 20 69 66 20 74 NULL if t
255e0 68 65 72 65 20 69 73 20 6e 6f 20 53 51 4c 20 70 here is no SQL p
255f0 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 69 6e arameter with in
25600 64 65 78 20 4e 20 6f 72 20 69 66 20 74 68 65 0a dex N or if the.
25610 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 ** para
25620 6d 65 74 65 72 20 77 69 74 68 20 69 6e 64 65 78 meter with index
25630 20 4e 20 69 73 20 61 6e 20 61 6e 6f 6e 79 6d 6f N is an anonymo
25640 75 73 20 70 61 72 61 6d 65 74 65 72 20 22 3f 22 us parameter "?"
25650 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 ..*/.const char
25660 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 *sqlite3_bind_pa
25670 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c rameter_name(sql
25680 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 ite3_stmt*, int)
25690 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
256a0 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 F: Index Of A Pa
256b0 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 rameter With A G
256c0 69 76 65 6e 20 4e 61 6d 65 20 7b 48 31 33 36 34 iven Name {H1364
256d0 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 0} <S70300>.**.*
256e0 2a 20 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 * Return the ind
256f0 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 ex of an SQL par
25700 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 ameter given its
25710 20 6e 61 6d 65 2e 20 20 54 68 65 0a 2a 2a 20 69 name. The.** i
25720 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 ndex value retur
25730 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 ned is suitable
25740 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 for use as the s
25750 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 econd.** paramet
25760 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 er to [sqlite3_b
25770 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 ind_blob|sqlite3
25780 5f 62 69 6e 64 28 29 5d 2e 20 20 41 20 7a 65 72 _bind()]. A zer
25790 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 o.** is returned
257a0 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 if no matching
257b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 parameter is fou
257c0 6e 64 2e 20 20 54 68 65 20 70 61 72 61 6d 65 74 nd. The paramet
257d0 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 er.** name must
257e0 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d be given in UTF-
257f0 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 8 even if the or
25800 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 iginal statement
25810 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 .** was prepared
25820 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 from UTF-16 tex
25830 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
25840 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
25850 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
25860 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f : [sqlite3_bind_
25870 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e blob|sqlite3_bin
25880 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 d()],.** [sqlite
25890 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
258a0 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a _count()], and.*
258b0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
258c0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 parameter_index(
258d0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 )]..**.** INVARI
258e0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 ANTS:.**.** {H13
258f0 36 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 641} The [sqlite
25900 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
25910 5f 69 6e 64 65 78 28 53 2c 4e 29 5d 20 69 6e 74 _index(S,N)] int
25920 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a erface returns.*
25930 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 69 * the i
25940 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72 61 ndex of SQL para
25950 6d 65 74 65 72 20 69 6e 20 74 68 65 20 5b 70 72 meter in the [pr
25960 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
25970 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 20 ].** S
25980 77 68 6f 73 65 20 6e 61 6d 65 20 6d 61 74 63 68 whose name match
25990 65 73 20 74 68 65 20 55 54 46 2d 38 20 73 74 72 es the UTF-8 str
259a0 69 6e 67 20 4e 2c 20 6f 72 20 30 20 69 66 20 74 ing N, or 0 if t
259b0 68 65 72 65 20 69 73 0a 2a 2a 20 20 20 20 20 20 here is.**
259c0 20 20 20 20 6e 6f 20 6d 61 74 63 68 2e 0a 2a 2f no match..*/
259d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
259e0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 d_parameter_inde
259f0 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c x(sqlite3_stmt*,
25a00 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
25a10 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 me);../*.** CAPI
25a20 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 3REF: Reset All
25a30 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 Bindings On A Pr
25a40 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 epared Statement
25a50 20 7b 48 31 33 36 36 30 7d 20 3c 53 37 30 33 30 {H13660} <S7030
25a60 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61 72 0>.**.** Contrar
25a70 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 y to the intuiti
25a80 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c on of many, [sql
25a90 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f ite3_reset()] do
25aa0 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 es not reset.**
25ab0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e the [sqlite3_bin
25ac0 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 d_blob | binding
25ad0 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 s] on a [prepare
25ae0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a d statement]..**
25af0 20 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e Use this routin
25b00 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 e to reset all h
25b10 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 ost parameters t
25b20 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e o NULL..**.** IN
25b30 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
25b40 7b 48 31 33 36 36 31 7d 20 54 68 65 20 5b 73 71 {H13661} The [sq
25b50 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 lite3_clear_bind
25b60 69 6e 67 73 28 53 29 5d 20 69 6e 74 65 72 66 61 ings(S)] interfa
25b70 63 65 20 72 65 73 65 74 73 20 61 6c 6c 20 53 51 ce resets all SQ
25b80 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 L.** pa
25b90 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 73 rameter bindings
25ba0 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 in the [prepare
25bb0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 62 d statement] S b
25bc0 61 63 6b 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a ack to NULL..*/.
25bd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 int sqlite3_clea
25be0 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 r_bindings(sqlit
25bf0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a e3_stmt*);../*.*
25c00 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 * CAPI3REF: Numb
25c10 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e er Of Columns In
25c20 20 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b 48 A Result Set {H
25c30 31 33 37 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a 13710} <S10700>.
25c40 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 **.** Return the
25c50 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
25c60 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 ns in the result
25c70 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 set returned by
25c80 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the.** [prepare
25c90 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54 68 d statement]. Th
25ca0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 is routine retur
25cb0 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 ns 0 if pStmt is
25cc0 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 an SQL.** state
25cd0 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e ment that does n
25ce0 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 ot return data (
25cf0 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b for example an [
25d00 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 UPDATE])..**.**
25d10 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
25d20 2a 20 7b 48 31 33 37 31 31 7d 20 54 68 65 20 5b * {H13711} The [
25d30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 sqlite3_column_c
25d40 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72 66 61 ount(S)] interfa
25d50 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e ce returns the n
25d60 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 umber of.**
25d70 20 20 20 20 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 columns in
25d80 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 67 the result set g
25d90 65 6e 65 72 61 74 65 64 20 62 79 20 74 68 65 20 enerated by the
25da0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
25db0 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20 20 20 20 20 ent] S,.**
25dc0 20 20 20 20 6f 72 20 30 20 69 66 20 53 20 64 6f or 0 if S do
25dd0 65 73 20 6e 6f 74 20 67 65 6e 65 72 61 74 65 20 es not generate
25de0 61 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2f a result set..*/
25df0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c .int sqlite3_col
25e00 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 umn_count(sqlite
25e10 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 3_stmt *pStmt);.
25e20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
25e30 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e Column Names In
25e40 20 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b 48 A Result Set {H
25e50 31 33 37 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 13720} <S10700>.
25e60 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
25e70 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 ines return the
25e80 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f name assigned to
25e90 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f a particular co
25ea0 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 lumn.** in the r
25eb0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b esult set of a [
25ec0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
25ed0 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f t. The sqlite3_
25ee0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a column_name().**
25ef0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
25f00 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
25f10 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
25f20 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a d UTF-8 string.*
25f30 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f * and sqlite3_co
25f40 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 lumn_name16() re
25f50 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
25f60 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e to a zero-termin
25f70 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 ated.** UTF-16 s
25f80 74 72 69 6e 67 2e 20 20 54 68 65 20 66 69 72 73 tring. The firs
25f90 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 t parameter is t
25fa0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
25fb0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 tement].** that
25fc0 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b implements the [
25fd0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
25fe0 74 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 t. The second pa
25ff0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a rameter is the.*
26000 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e * column number.
26010 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 The leftmost c
26020 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 olumn is number
26030 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 0..**.** The ret
26040 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 urned string poi
26050 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e nter is valid un
26060 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b til either the [
26070 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
26080 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f nt].** is destro
26090 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f yed by [sqlite3_
260a0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 finalize()] or u
260b0 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 ntil the next ca
260c0 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 ll to.** sqlite3
260d0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f _column_name() o
260e0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e r sqlite3_column
260f0 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 _name16() on the
26100 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a same column..**
26110 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d .** If sqlite3_m
26120 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 alloc() fails du
26130 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 ring the process
26140 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f ing of either ro
26150 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 utine.** (for ex
26160 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 ample during a c
26170 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 onversion from U
26180 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 TF-8 to UTF-16)
26190 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 then a.** NULL p
261a0 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e ointer is return
261b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 ed..**.** The na
261c0 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 me of a result c
261d0 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c olumn is the val
261e0 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 ue of the "AS" c
261f0 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 lause for.** tha
26200 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 t column, if the
26210 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 re is an AS clau
26220 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 se. If there is
26230 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a no AS clause.**
26240 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f then the name o
26250 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 f the column is
26260 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 unspecified and
26270 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a may change from.
26280 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f ** one release o
26290 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 f SQLite to the
262a0 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 next..**.** INVA
262b0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 RIANTS:.**.** {H
262c0 31 33 37 32 31 7d 20 41 20 73 75 63 63 65 73 73 13721} A success
262d0 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f ful invocation o
262e0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 f the [sqlite3_c
262f0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d olumn_name(S,N)]
26300 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 .** int
26310 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 erface returns t
26320 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e he name of the N
26330 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72 65 th column (where
26340 20 30 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 0 is.**
26350 20 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 the leftmost c
26360 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65 20 72 olumn) for the r
26370 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 esult set of the
26380 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 .** [pr
26390 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
263a0 5d 20 53 20 61 73 20 61 20 7a 65 72 6f 2d 74 65 ] S as a zero-te
263b0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 rminated UTF-8 s
263c0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 tring..**.** {H1
263d0 33 37 32 33 7d 20 41 20 73 75 63 63 65 73 73 66 3723} A successf
263e0 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 ul invocation of
263f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f the [sqlite3_co
26400 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 lumn_name16(S,N)
26410 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e ].** in
26420 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
26430 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
26440 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72 Nth column (wher
26450 65 20 30 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 e 0 is.**
26460 20 20 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 the leftmost
26470 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65 20 column) for the
26480 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 result set of th
26490 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 e.** [p
264a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
264b0 74 5d 20 53 20 61 73 20 61 20 7a 65 72 6f 2d 74 t] S as a zero-t
264c0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36 erminated UTF-16
264d0 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 string.**
264e0 20 20 20 20 69 6e 20 74 68 65 20 6e 61 74 69 76 in the nativ
264f0 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a e byte order..**
26500 0a 2a 2a 20 7b 48 31 33 37 32 34 7d 20 54 68 65 .** {H13724} The
26510 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
26520 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 5b 73 71 _name()] and [sq
26530 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
26540 65 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 e16()].**
26550 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 interfaces re
26560 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e turn a NULL poin
26570 74 65 72 20 69 66 20 74 68 65 79 20 61 72 65 20 ter if they are
26580 75 6e 61 62 6c 65 20 74 6f 0a 2a 2a 20 20 20 20 unable to.**
26590 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 20 6d allocate m
265a0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 emory to hold th
265b0 65 69 72 20 6e 6f 72 6d 61 6c 20 72 65 74 75 72 eir normal retur
265c0 6e 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a n strings..**.**
265d0 20 7b 48 31 33 37 32 35 7d 20 49 66 20 74 68 65 {H13725} If the
265e0 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 N parameter to
265f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
26600 6e 61 6d 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a name(S,N)] or.**
26610 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
26620 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 e3_column_name16
26630 28 53 2c 4e 29 5d 20 69 73 20 6f 75 74 20 6f 66 (S,N)] is out of
26640 20 72 61 6e 67 65 2c 20 74 68 65 6e 20 74 68 65 range, then the
26650 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 .** int
26660 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 61 erfaces return a
26670 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a NULL pointer..*
26680 2a 0a 2a 2a 20 7b 48 31 33 37 32 36 7d 20 54 68 *.** {H13726} Th
26690 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e e strings return
266a0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 ed by [sqlite3_c
266b0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d olumn_name(S,N)]
266c0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 and.**
266d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
266e0 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 61 72 _name16(S,N)] ar
266f0 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 e valid until th
26700 65 20 6e 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 e next.**
26710 20 20 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 call to eithe
26720 72 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 74 r routine with t
26730 68 65 20 73 61 6d 65 20 53 20 61 6e 64 20 4e 20 he same S and N
26740 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20 20 parameters.**
26750 20 20 20 20 20 20 20 6f 72 20 75 6e 74 69 6c 20 or until
26760 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
26770 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e e(S)] is called.
26780 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 37 7d 20 .**.** {H13727}
26790 57 68 65 6e 20 61 20 72 65 73 75 6c 74 20 63 6f When a result co
267a0 6c 75 6d 6e 20 6f 66 20 61 20 5b 53 45 4c 45 43 lumn of a [SELEC
267b0 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6e T] statement con
267c0 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 tains.**
267d0 20 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2c 20 an AS clause,
267e0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 61 74 the name of that
267f0 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 69 column is the i
26800 64 65 6e 74 69 66 69 65 72 0a 2a 2a 20 20 20 20 dentifier.**
26810 20 20 20 20 20 20 74 6f 20 74 68 65 20 72 69 67 to the rig
26820 68 74 20 6f 66 20 74 68 65 20 41 53 20 6b 65 79 ht of the AS key
26830 77 6f 72 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 word..*/.const c
26840 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c har *sqlite3_col
26850 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 umn_name(sqlite3
26860 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a _stmt*, int N);.
26870 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
26880 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 te3_column_name1
26890 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
268a0 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 int N);../*.**
268b0 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 CAPI3REF: Source
268c0 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 Of Data In A Qu
268d0 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31 33 37 ery Result {H137
268e0 34 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 40} <S10700>.**.
268f0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
26900 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e s provide a mean
26910 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 77 s to determine w
26920 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 77 68 hat column of wh
26930 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e 20 77 at.** table in w
26940 68 69 63 68 20 64 61 74 61 62 61 73 65 20 61 20 hich database a
26950 72 65 73 75 6c 74 20 6f 66 20 61 20 5b 53 45 4c result of a [SEL
26960 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 63 ECT] statement c
26970 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68 omes from..** Th
26980 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 e name of the da
26990 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 tabase or table
269a0 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 or column can be
269b0 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 returned as.**
269c0 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f either a UTF-8 o
269d0 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e r UTF-16 string.
269e0 20 20 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f The _database_
269f0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
26a00 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 .** the database
26a10 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c name, the _tabl
26a20 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 e_ routines retu
26a30 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d rn the table nam
26a40 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 e, and.** the or
26a50 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 igin_ routines r
26a60 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e eturn the column
26a70 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 72 65 name..** The re
26a80 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 turned string is
26a90 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 valid until the
26aa0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
26ab0 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 ment] is destroy
26ac0 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c ed.** using [sql
26ad0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
26ae0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 or until the sa
26af0 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 me information i
26b00 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 s requested.** a
26b10 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 gain in a differ
26b20 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a ent encoding..**
26b30 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73 20 72 65 .** The names re
26b40 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f turned are the o
26b50 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 riginal un-alias
26b60 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a ed names of the.
26b70 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 ** database, tab
26b80 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a le, and column..
26b90 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
26ba0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
26bb0 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c 73 20 following calls
26bc0 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 is a [prepared s
26bd0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68 tatement]..** Th
26be0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 ese functions re
26bf0 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e turn information
26c00 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 63 about the Nth c
26c10 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 olumn returned b
26c20 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 y.** the stateme
26c30 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 nt, where N is t
26c40 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 he second functi
26c50 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a on argument..**.
26c60 2a 2a 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f ** If the Nth co
26c70 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 lumn returned by
26c80 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
26c90 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 s an expression
26ca0 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 or.** subquery a
26cb0 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 nd is not a colu
26cc0 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 mn value, then a
26cd0 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 ll of these func
26ce0 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 tions return.**
26cf0 4e 55 4c 4c 2e 20 20 54 68 65 73 65 20 72 6f 75 NULL. These rou
26d00 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 tine might also
26d10 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 return NULL if a
26d20 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
26d30 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 on error.** occu
26d40 72 73 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 rs. Otherwise,
26d50 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 they return the
26d60 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 name of the atta
26d70 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 ched database, t
26d80 61 62 6c 65 0a 2a 2a 20 61 6e 64 20 63 6f 6c 75 able.** and colu
26d90 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 mn that query re
26da0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 sult column was
26db0 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a extracted from..
26dc0 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 68 20 61 6c **.** As with al
26dd0 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 l other SQLite A
26de0 50 49 73 2c 20 74 68 6f 73 65 20 70 6f 73 74 66 PIs, those postf
26df0 69 78 65 64 20 77 69 74 68 20 22 31 36 22 20 72 ixed with "16" r
26e00 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 eturn.** UTF-16
26e10 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 2c encoded strings,
26e20 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 the other funct
26e30 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d ions return UTF-
26e40 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 8. {END}.**.** T
26e50 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e hese APIs are on
26e60 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 ly available if
26e70 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 the library was
26e80 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 compiled with th
26e90 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 e.** [SQLITE_ENA
26ea0 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 BLE_COLUMN_METAD
26eb0 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 ATA] C-preproces
26ec0 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e sor symbol defin
26ed0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 37 35 ed..**.** {A1375
26ee0 31 7d 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 1}.** If two or
26ef0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c more threads cal
26f00 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 l one or more of
26f10 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
26f20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 against the same
26f30 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 .** prepared sta
26f40 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d tement and colum
26f50 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 n at the same ti
26f60 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 me then the resu
26f70 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 lts are.** undef
26f80 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 ined..**.** INVA
26f90 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 RIANTS:.**.** {H
26fa0 31 33 37 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 13741} The [sqli
26fb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 te3_column_datab
26fc0 61 73 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 ase_name(S,N)] i
26fd0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
26fe0 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 either.**
26ff0 20 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65 the UTF-8 ze
27000 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 ro-terminated na
27010 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 me of the databa
27020 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 se from which th
27030 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 e.** Nt
27040 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 h result column
27050 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 of the [prepared
27060 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 statement] S is
27070 20 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20 extracted,.**
27080 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 or NULL
27090 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d if the Nth colum
270a0 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 n of S is a gene
270b0 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a ral expression.*
270c0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 * or if
270d0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 unable to alloc
270e0 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 ate memory to st
270f0 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a ore the name..**
27100 0a 2a 2a 20 7b 48 31 33 37 34 32 7d 20 54 68 65 .** {H13742} The
27110 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
27120 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 _database_name16
27130 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 (S,N)] interface
27140 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a returns either.
27150 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
27160 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 UTF-16 native by
27170 74 65 20 6f 72 64 65 72 20 7a 65 72 6f 2d 74 65 te order zero-te
27180 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 rminated name of
27190 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a the database.**
271a0 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 77 from w
271b0 68 69 63 68 20 74 68 65 20 4e 74 68 20 72 65 73 hich the Nth res
271c0 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 ult column of th
271d0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
271e0 65 6d 65 6e 74 5d 20 53 20 69 73 0a 2a 2a 20 20 ement] S is.**
271f0 20 20 20 20 20 20 20 20 65 78 74 72 61 63 74 65 extracte
27200 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 d, or NULL if th
27210 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 e Nth column of
27220 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 S is a general e
27230 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 xpression.**
27240 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62 or if unab
27250 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d le to allocate m
27260 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74 emory to store t
27270 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b he name..**.** {
27280 48 31 33 37 34 33 7d 20 54 68 65 20 5b 73 71 6c H13743} The [sql
27290 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c ite3_column_tabl
272a0 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 e_name(S,N)] int
272b0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 erface returns e
272c0 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 ither.**
272d0 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f the UTF-8 zero
272e0 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 -terminated name
272f0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 66 72 of the table fr
27300 6f 6d 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 om which the.**
27310 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73 Nth res
27320 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 ult column of th
27330 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
27340 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74 72 ement] S is extr
27350 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 acted,.**
27360 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 or NULL if th
27370 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 e Nth column of
27380 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 S is a general e
27390 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 xpression.**
273a0 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62 or if unab
273b0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d le to allocate m
273c0 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74 emory to store t
273d0 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b he name..**.** {
273e0 48 31 33 37 34 34 7d 20 54 68 65 20 5b 73 71 6c H13744} The [sql
273f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c ite3_column_tabl
27400 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 e_name16(S,N)] i
27410 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
27420 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 either.**
27430 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e the UTF-16 n
27440 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
27450 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
27460 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 name of the tab
27470 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 le.** f
27480 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 4e 74 rom which the Nt
27490 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 h result column
274a0 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 of the [prepared
274b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 statement] S is
274c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78 74 .** ext
274d0 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 racted, or NULL
274e0 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d if the Nth colum
274f0 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 n of S is a gene
27500 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a ral expression.*
27510 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 * or if
27520 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 unable to alloc
27530 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 ate memory to st
27540 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a ore the name..**
27550 0a 2a 2a 20 7b 48 31 33 37 34 35 7d 20 54 68 65 .** {H13745} The
27560 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
27570 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 53 2c 4e _origin_name(S,N
27580 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
27590 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 urns either.**
275a0 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d the UTF-
275b0 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 8 zero-terminate
275c0 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 d name of the ta
275d0 62 6c 65 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 ble column from
275e0 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 20 20 20 which the.**
275f0 20 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 Nth result
27600 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b column of the [
27610 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
27620 6e 74 5d 20 53 20 69 73 20 65 78 74 72 61 63 74 nt] S is extract
27630 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ed,.**
27640 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e or NULL if the N
27650 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 th column of S i
27660 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 s a general expr
27670 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 ession.**
27680 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 or if unable
27690 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f to allocate memo
276a0 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 ry to store the
276b0 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 name..**.** {H13
276c0 37 34 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 746} The [sqlite
276d0 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 3_column_origin_
276e0 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 name16(S,N)] int
276f0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 erface returns e
27700 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 ither.**
27710 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 the UTF-16 nat
27720 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 7a ive byte order z
27730 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e ero-terminated n
27740 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 ame of the table
27750 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c .** col
27760 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68 20 74 umn from which t
27770 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f he Nth result co
27780 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 20 lumn of the.**
27790 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 [prepare
277a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 d statement] S i
277b0 73 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 s extracted, or
277c0 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 NULL if the Nth
277d0 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20 20 20 column.**
277e0 20 20 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e of S is a gen
277f0 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 eral expression
27800 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 or if unable to
27810 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a allocate memory.
27820 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 73 ** to s
27830 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a tore the name..*
27840 2a 0a 2a 2a 20 7b 48 31 33 37 34 38 7d 20 54 68 *.** {H13748} Th
27850 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 20 e return values
27860 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 from.**
27870 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
27880 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c _database_name |
27890 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 column metadata
278a0 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 interfaces].**
278b0 20 20 20 20 20 20 20 20 20 61 72 65 20 76 61 6c are val
278c0 69 64 20 66 6f 72 20 74 68 65 20 6c 69 66 65 74 id for the lifet
278d0 69 6d 65 20 6f 66 20 74 68 65 20 5b 70 72 65 70 ime of the [prep
278e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a ared statement].
278f0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 75 ** or u
27900 6e 74 69 6c 20 74 68 65 20 65 6e 63 6f 64 69 6e ntil the encodin
27910 67 20 69 73 20 63 68 61 6e 67 65 64 20 62 79 20 g is changed by
27920 61 6e 6f 74 68 65 72 20 6d 65 74 61 64 61 74 61 another metadata
27930 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 .** int
27940 65 72 66 61 63 65 20 63 61 6c 6c 20 66 6f 72 20 erface call for
27950 74 68 65 20 73 61 6d 65 20 70 72 65 70 61 72 65 the same prepare
27960 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 d statement and
27970 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 41 53 column..**.** AS
27980 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a SUMPTIONS:.**.**
27990 20 7b 41 31 33 37 35 31 7d 20 49 66 20 74 77 6f {A13751} If two
279a0 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 or more threads
279b0 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 call one or mor
279c0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 e.** [s
279d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 qlite3_column_da
279e0 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f tabase_name | co
279f0 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e lumn metadata in
27a00 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20 20 terfaces].**
27a10 20 20 20 20 20 20 66 6f 72 20 74 68 65 20 73 61 for the sa
27a20 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 me [prepared sta
27a30 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 tement] and resu
27a40 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20 lt column.**
27a50 20 20 20 20 20 20 61 74 20 74 68 65 20 73 61 6d at the sam
27a60 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 e time then the
27a70 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 results are unde
27a80 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 fined..*/.const
27a90 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
27aa0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 lumn_database_na
27ab0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
27ac0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 ,int);.const voi
27ad0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
27ae0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 n_database_name1
27af0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
27b00 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 int);.const char
27b10 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
27b20 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 _table_name(sqli
27b30 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
27b40 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
27b50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 te3_column_table
27b60 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f _name16(sqlite3_
27b70 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 stmt*,int);.cons
27b80 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
27b90 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 column_origin_na
27ba0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
27bb0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 ,int);.const voi
27bc0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
27bd0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 n_origin_name16(
27be0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
27bf0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
27c00 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 REF: Declared Da
27c10 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 tatype Of A Quer
27c20 79 20 52 65 73 75 6c 74 20 7b 48 31 33 37 36 30 y Result {H13760
27c30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a } <S10700>.**.**
27c40 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d The first param
27c50 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 eter is a [prepa
27c60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a red statement]..
27c70 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 ** If this state
27c80 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 ment is a [SELEC
27c90 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 T] statement and
27ca0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
27cb0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e of the.** return
27cc0 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 ed result set of
27cd0 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 that [SELECT] i
27ce0 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e s a table column
27cf0 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 (not an.** expr
27d00 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 ession or subque
27d10 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 ry) then the dec
27d20 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 lared type of th
27d30 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d e table.** colum
27d40 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 n is returned.
27d50 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d If the Nth colum
27d60 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 n of the result
27d70 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 set is an.** exp
27d80 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 ression or subqu
27d90 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c ery, then a NULL
27da0 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 pointer is retu
27db0 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74 rned..** The ret
27dc0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 urned string is
27dd0 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 always UTF-8 enc
27de0 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a oded. {END}.**.*
27df0 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 * For example, g
27e00 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 iven the databas
27e10 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 e schema:.**.**
27e20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 CREATE TABLE t1(
27e30 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a c1 VARIANT);.**.
27e40 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f ** and the follo
27e50 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 wing statement t
27e60 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a o be compiled:.*
27e70 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b *.** SELECT c1 +
27e80 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 1, c1 FROM t1;.
27e90 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 **.** this routi
27ea0 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 ne would return
27eb0 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 the string "VARI
27ec0 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 ANT" for the sec
27ed0 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f ond result.** co
27ee0 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 lumn (i==1), and
27ef0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
27f00 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 for the first re
27f10 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d sult column (i==
27f20 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 0)..**.** SQLite
27f30 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 uses dynamic ru
27f40 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 n-time typing.
27f50 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 So just because
27f60 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 a column.** is d
27f70 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 eclared to conta
27f80 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 in a particular
27f90 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 type does not me
27fa0 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 an that the.** d
27fb0 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 ata stored in th
27fc0 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 at column is of
27fd0 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 the declared typ
27fe0 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a e. SQLite is.**
27ff0 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c strongly typed,
28000 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 but the typing
28010 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 is dynamic not s
28020 74 61 74 69 63 2e 20 20 54 79 70 65 0a 2a 2a 20 tatic. Type.**
28030 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 is associated wi
28040 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 th individual va
28050 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 lues, not with t
28060 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a he containers.**
28070 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 used to hold th
28080 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a ose values..**.*
28090 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
280a0 0a 2a 2a 20 7b 48 31 33 37 36 31 7d 20 20 41 20 .** {H13761} A
280b0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 successful call
280c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to [sqlite3_colu
280d0 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e 29 mn_decltype(S,N)
280e0 5d 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 ] returns a.**
280f0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 zero-te
28100 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 rminated UTF-8 s
28110 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 tring containing
28120 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 64 61 the declared da
28130 74 61 74 79 70 65 0a 2a 2a 20 20 20 20 20 20 20 tatype.**
28140 20 20 20 20 6f 66 20 74 68 65 20 74 61 62 6c 65 of the table
28150 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70 70 column that app
28160 65 61 72 73 20 61 73 20 74 68 65 20 4e 74 68 20 ears as the Nth
28170 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 column (numbered
28180 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 66 72 .** fr
28190 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65 73 om 0) of the res
281a0 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65 20 5b ult set to the [
281b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
281c0 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 nt] S..**.** {H1
281d0 33 37 36 32 7d 20 20 41 20 73 75 63 63 65 73 73 3762} A success
281e0 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ful call to [sql
281f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c ite3_column_decl
28200 74 79 70 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20 type16(S,N)].**
28210 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e return
28220 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 s a zero-termina
28230 74 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 ted UTF-16 nativ
28240 65 20 62 79 74 65 20 6f 72 64 65 72 20 73 74 72 e byte order str
28250 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ing.**
28260 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 containing the
28270 64 65 63 6c 61 72 65 64 20 64 61 74 61 74 79 70 declared datatyp
28280 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 e of the table c
28290 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70 70 65 61 olumn that appea
282a0 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 rs.**
282b0 61 73 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d as the Nth colum
282c0 6e 20 28 6e 75 6d 62 65 72 65 64 20 66 72 6f 6d n (numbered from
282d0 20 30 29 20 6f 66 20 74 68 65 20 72 65 73 75 6c 0) of the resul
282e0 74 20 73 65 74 20 74 6f 20 74 68 65 0a 2a 2a 20 t set to the.**
282f0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 [prepa
28300 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
28310 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36 33 7d ..**.** {H13763}
28320 20 20 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 If N is less t
28330 68 61 6e 20 30 20 6f 72 20 4e 20 69 73 20 67 72 han 0 or N is gr
28340 65 61 74 65 72 20 74 68 61 6e 20 6f 72 20 65 71 eater than or eq
28350 75 61 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 ual to.**
28360 20 20 20 20 74 68 65 20 6e 75 6d 62 65 72 20 6f the number o
28370 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 f columns in the
28380 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
28390 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20 20 20 20 ment] S,.**
283a0 20 20 20 20 20 20 6f 72 20 69 66 20 74 68 65 20 or if the
283b0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 Nth column of S
283c0 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e is an expression
283d0 20 6f 72 20 73 75 62 71 75 65 72 79 20 72 61 74 or subquery rat
283e0 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 her.**
283f0 20 74 68 61 6e 20 61 20 74 61 62 6c 65 20 63 6f than a table co
28400 6c 75 6d 6e 2c 20 6f 72 20 69 66 20 61 20 6d 65 lumn, or if a me
28410 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
28420 66 61 69 6c 75 72 65 0a 2a 2a 20 20 20 20 20 20 failure.**
28430 20 20 20 20 20 6f 63 63 75 72 73 20 64 75 72 69 occurs duri
28440 6e 67 20 65 6e 63 6f 64 69 6e 67 20 63 6f 6e 76 ng encoding conv
28450 65 72 73 69 6f 6e 73 2c 20 74 68 65 6e 0a 2a 2a ersions, then.**
28460 20 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 73 calls
28470 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c to [sqlite3_col
28480 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e umn_decltype(S,N
28490 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 )] or.**
284a0 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 [sqlite3_colu
284b0 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 53 2c mn_decltype16(S,
284c0 4e 29 5d 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e N)] return NULL.
284d0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a .*/.const char *
284e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
284f0 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f ecltype(sqlite3_
28500 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 stmt*,int);.cons
28510 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
28520 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 column_decltype1
28530 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
28540 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 int);../*.** CAP
28550 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 I3REF: Evaluate
28560 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 An SQL Statement
28570 20 7b 48 31 33 32 30 30 7d 20 3c 53 31 30 30 30 {H13200} <S1000
28580 30 3e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 0>.**.** After a
28590 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
285a0 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 ment] has been p
285b0 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 repared using ei
285c0 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ther.** [sqlite3
285d0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
285e0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
285f0 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e re16_v2()] or on
28600 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a e of the legacy.
28610 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 ** interfaces [s
28620 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
28630 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 ] or [sqlite3_pr
28640 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 epare16()], this
28650 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 function.** mus
28660 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 t be called one
28670 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f or more times to
28680 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 evaluate the st
28690 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 atement..**.** T
286a0 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 he details of th
286b0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 e behavior of th
286c0 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 e sqlite3_step()
286d0 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e interface depen
286e0 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 d.** on whether
286f0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 the statement wa
28700 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 s prepared using
28710 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 the newer "v2"
28720 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 interface.** [sq
28730 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
28740 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
28750 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
28760 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 or the older le
28770 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 gacy.** interfac
28780 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 e [sqlite3_prepa
28790 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 re()] and [sqlit
287a0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e e3_prepare16()].
287b0 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 The use of the
287c0 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 .** new "v2" int
287d0 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d erface is recomm
287e0 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 ended for new ap
287f0 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 plications but t
28800 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 he legacy.** int
28810 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 erface will cont
28820 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f inue to be suppo
28830 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 rted..**.** In t
28840 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 he legacy interf
28850 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 ace, the return
28860 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 value will be ei
28870 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 ther [SQLITE_BUS
28880 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 Y],.** [SQLITE_D
28890 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f ONE], [SQLITE_RO
288a0 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f W], [SQLITE_ERRO
288b0 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d R], or [SQLITE_M
288c0 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 68 20 ISUSE]..** With
288d0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
288e0 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f ce, any of the o
288f0 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 ther [result cod
28900 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e es] or.** [exten
28910 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
28920 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 ] might be retur
28930 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a ned as well..**.
28940 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d ** [SQLITE_BUSY]
28950 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 means that the
28960 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 database engine
28970 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 was unable to ac
28980 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 quire the.** dat
28990 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e abase locks it n
289a0 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a eeds to do its j
289b0 6f 62 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 ob. If the stat
289c0 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d ement is a [COMM
289d0 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 IT].** or occurs
289e0 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 outside of an e
289f0 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 xplicit transact
28a00 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 ion, then you ca
28a10 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 n retry the.** s
28a20 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 tatement. If th
28a30 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e e statement is n
28a40 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e ot a [COMMIT] an
28a50 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 d occurs within
28a60 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 a.** explicit tr
28a70 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 ansaction then y
28a80 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 ou should rollba
28a90 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 ck the transacti
28aa0 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e on before.** con
28ab0 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b tinuing..**.** [
28ac0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 SQLITE_DONE] mea
28ad0 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 ns that the stat
28ae0 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 ement has finish
28af0 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 ed executing.**
28b00 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 successfully. s
28b10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 qlite3_step() sh
28b20 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c ould not be call
28b30 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 ed again on this
28b40 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 virtual.** mach
28b50 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 ine without firs
28b60 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 t calling [sqlit
28b70 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 e3_reset()] to r
28b80 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c eset the virtual
28b90 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b .** machine back
28ba0 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 to its initial
28bb0 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 state..**.** If
28bc0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
28bd0 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 t being executed
28be0 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 returns any dat
28bf0 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f a, then [SQLITE_
28c00 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 ROW].** is retur
28c10 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 ned each time a
28c20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 new row of data
28c30 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f is ready for pro
28c40 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a cessing by the.*
28c50 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 * caller. The va
28c60 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 lues may be acce
28c70 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b ssed using the [
28c80 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 column access fu
28c90 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c nctions]..** sql
28ca0 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 ite3_step() is c
28cb0 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 alled again to r
28cc0 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 etrieve the next
28cd0 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a row of data..**
28ce0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f .** [SQLITE_ERRO
28cf0 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 R] means that a
28d00 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 run-time error (
28d10 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 such as a constr
28d20 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f aint.** violatio
28d30 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e n) has occurred.
28d40 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 sqlite3_step()
28d50 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 should not be c
28d60 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a alled again on.*
28d70 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 * the VM. More i
28d80 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 nformation may b
28d90 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 e found by calli
28da0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d ng [sqlite3_errm
28db0 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 sg()]..** With t
28dc0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 he legacy interf
28dd0 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 ace, a more spec
28de0 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 ific error code
28df0 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a (for example,.**
28e00 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 [SQLITE_INTERRU
28e10 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 PT], [SQLITE_SCH
28e20 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f EMA], [SQLITE_CO
28e30 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 RRUPT], and so f
28e40 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 orth).** can be
28e50 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c obtained by call
28e60 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ing [sqlite3_res
28e70 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 et()] on the.**
28e80 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
28e90 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20 22 76 ent]. In the "v
28ea0 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 2" interface,.**
28eb0 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 the more specif
28ec0 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 ic error code is
28ed0 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 returned direct
28ee0 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 ly by sqlite3_st
28ef0 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c ep()..**.** [SQL
28f00 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e ITE_MISUSE] mean
28f10 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 s that the this
28f20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c routine was call
28f30 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 ed inappropriate
28f40 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 ly..** Perhaps i
28f50 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 t was called on
28f60 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
28f70 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a ement] that has.
28f80 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 ** already been
28f90 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
28fa0 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f e | finalized] o
28fb0 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 r on one that ha
28fc0 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 d.** previously
28fd0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 returned [SQLITE
28fe0 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 _ERROR] or [SQLI
28ff0 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 TE_DONE]. Or it
29000 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 could.** be the
29010 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 case that the s
29020 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e ame database con
29030 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 nection is being
29040 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a used by two or.
29050 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 ** more threads
29060 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 at the same mome
29070 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a nt in time..**.*
29080 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 * <b>Goofy Inter
29090 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 face Alert:</b>
290a0 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e In the legacy in
290b0 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c terface, the sql
290c0 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 ite3_step().** A
290d0 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e PI always return
290e0 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f s a generic erro
290f0 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f r code, [SQLITE_
29100 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e ERROR], followin
29110 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f g any.** error o
29120 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
29130 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c E_BUSY] and [SQL
29140 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f ITE_MISUSE]. Yo
29150 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b u must call.** [
29160 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
29170 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e or [sqlite3_fin
29180 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 alize()] in orde
29190 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 r to find one of
291a0 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 the.** specific
291b0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 [error codes] t
291c0 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72 hat better descr
291d0 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a ibes the error..
291e0 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 ** We admit that
291f0 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 this is a goofy
29200 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 design. The pr
29210 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 oblem has been f
29220 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 ixed.** with the
29230 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e "v2" interface.
29240 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 If you prepare
29250 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c all of your SQL
29260 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 statements.** u
29270 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c sing either [sql
29280 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
29290 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 )] or [sqlite3_p
292a0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 repare16_v2()] i
292b0 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 nstead.** of the
292c0 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 legacy [sqlite3
292d0 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 _prepare()] and
292e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
292f0 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 16()] interfaces
29300 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f ,.** then the mo
29310 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 re specific [err
29320 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 or codes] are re
29330 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a turned directly.
29340 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 ** by sqlite3_st
29350 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f ep(). The use o
29360 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 f the "v2" inter
29370 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e face is recommen
29380 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 ded..**.** INVAR
29390 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 IANTS:.**.** {H1
293a0 33 32 30 32 7d 20 20 49 66 20 74 68 65 20 5b 70 3202} If the [p
293b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
293c0 74 5d 20 53 20 69 73 20 72 65 61 64 79 20 74 6f t] S is ready to
293d0 20 62 65 20 72 75 6e 2c 20 74 68 65 6e 0a 2a 2a be run, then.**
293e0 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 [sqli
293f0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 61 64 76 te3_step(S)] adv
29400 61 6e 63 65 73 20 74 68 61 74 20 70 72 65 70 61 ances that prepa
29410 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 6e red statement un
29420 74 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 til.**
29430 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 72 20 75 completion or u
29440 6e 74 69 6c 20 69 74 20 69 73 20 72 65 61 64 79 ntil it is ready
29450 20 74 6f 20 72 65 74 75 72 6e 20 61 6e 6f 74 68 to return anoth
29460 65 72 20 72 6f 77 20 6f 66 20 74 68 65 0a 2a 2a er row of the.**
29470 20 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c resul
29480 74 20 73 65 74 2c 20 6f 72 20 75 6e 74 69 6c 20 t set, or until
29490 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 an [sqlite3_inte
294a0 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70 rrupt | interrup
294b0 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 t].**
294c0 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 or a run-time er
294d0 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a ror occurs..**.*
294e0 2a 20 7b 48 31 35 33 30 34 7d 20 20 57 68 65 6e * {H15304} When
294f0 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 a call to [sqli
29500 74 65 33 5f 73 74 65 70 28 53 29 5d 20 63 61 75 te3_step(S)] cau
29510 73 65 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 ses the [prepare
29520 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 d statement].**
29530 20 20 20 20 20 20 20 20 20 20 53 20 74 6f 20 72 S to r
29540 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e un to completion
29550 2c 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 , the function r
29560 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 eturns [SQLITE_D
29570 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 ONE]..**.** {H15
29580 33 30 36 7d 20 20 57 68 65 6e 20 61 20 63 61 6c 306} When a cal
29590 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 l to [sqlite3_st
295a0 65 70 28 53 29 5d 20 73 74 6f 70 73 20 62 65 63 ep(S)] stops bec
295b0 61 75 73 65 20 69 74 20 69 73 20 72 65 61 64 79 ause it is ready
295c0 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 to.**
295d0 20 72 65 74 75 72 6e 20 61 6e 6f 74 68 65 72 20 return another
295e0 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c row of the resul
295f0 74 20 73 65 74 2c 20 69 74 20 72 65 74 75 72 6e t set, it return
29600 73 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2e 0a s [SQLITE_ROW]..
29610 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 38 7d 20 20 **.** {H15308}
29620 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 If a call to [sq
29630 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 65 lite3_step(S)] e
29640 6e 63 6f 75 6e 74 65 72 73 20 61 6e 0a 2a 2a 20 ncounters an.**
29650 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
29660 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 e3_interrupt | i
29670 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 61 20 72 nterrupt] or a r
29680 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 2c 0a 2a un-time error,.*
29690 2a 20 20 20 20 20 20 20 20 20 20 20 69 74 20 72 * it r
296a0 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 eturns an approp
296b0 72 69 61 74 65 20 65 72 72 6f 72 20 63 6f 64 65 riate error code
296c0 20 74 68 61 74 20 69 73 20 6e 6f 74 20 6f 6e 65 that is not one
296d0 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 of.**
296e0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 5b 53 [SQLITE_OK], [S
296f0 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 6f 72 20 5b QLITE_ROW], or [
29700 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a SQLITE_DONE]..**
29710 0a 2a 2a 20 7b 48 31 35 33 31 30 7d 20 20 49 66 .** {H15310} If
29720 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 an [sqlite3_int
29730 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75 errupt | interru
29740 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d pt] or a run-tim
29750 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20 e error.**
29760 20 20 20 20 20 6f 63 63 75 72 73 20 64 75 72 69 occurs duri
29770 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 ng a call to [sq
29780 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 0a 2a lite3_step(S)].*
29790 2a 20 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 * for
297a0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
297b0 65 6d 65 6e 74 5d 20 53 20 63 72 65 61 74 65 64 ement] S created
297c0 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 using.**
297d0 20 20 20 20 6c 65 67 61 63 79 20 69 6e 74 65 72 legacy inter
297e0 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 faces [sqlite3_p
297f0 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 repare()] or.**
29800 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
29810 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c e3_prepare16()],
29820 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 then the functi
29830 6f 6e 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 on returns eithe
29840 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b r.** [
29850 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 5b SQLITE_ERROR], [
29860 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 6f 72 SQLITE_BUSY], or
29870 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
29880 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
29890 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 _step(sqlite3_st
298a0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 mt*);../*.** CAP
298b0 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 I3REF: Number of
298c0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 columns in a re
298d0 73 75 6c 74 20 73 65 74 20 7b 48 31 33 37 37 30 sult set {H13770
298e0 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a } <S10700>.**.**
298f0 20 52 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d Returns the num
29900 62 65 72 20 6f 66 20 76 61 6c 75 65 73 20 69 6e ber of values in
29910 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 the current row
29920 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 of the result s
29930 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 et..**.** INVARI
29940 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 ANTS:.**.** {H13
29950 37 37 31 7d 20 20 41 66 74 65 72 20 61 20 63 61 771} After a ca
29960 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 ll to [sqlite3_s
29970 74 65 70 28 53 29 5d 20 74 68 61 74 20 72 65 74 tep(S)] that ret
29980 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f 57 urns [SQLITE_ROW
29990 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 ],.**
299a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 the [sqlite3_dat
299b0 61 5f 63 6f 75 6e 74 28 53 29 5d 20 72 6f 75 74 a_count(S)] rout
299c0 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ine will return
299d0 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 0a 2a the same value.*
299e0 2a 20 20 20 20 20 20 20 20 20 20 20 61 73 20 74 * as t
299f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 he [sqlite3_colu
29a00 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 66 75 6e mn_count(S)] fun
29a10 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ction..**.** {H1
29a20 33 37 37 32 7d 20 20 41 66 74 65 72 20 5b 73 71 3772} After [sq
29a30 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 lite3_step(S)] h
29a40 61 73 20 72 65 74 75 72 6e 65 64 20 61 6e 79 20 as returned any
29a50 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e value other than
29a60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53 .** [S
29a70 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 62 65 QLITE_ROW] or be
29a80 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 fore [sqlite3_st
29a90 65 70 28 53 29 5d 20 68 61 73 20 62 65 65 6e 20 ep(S)] has been
29aa0 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 0a 2a 2a called on the.**
29ab0 20 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 [prep
29ac0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
29ad0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 74 69 for the first ti
29ae0 6d 65 20 73 69 6e 63 65 20 69 74 20 77 61 73 0a me since it was.
29af0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 ** [sq
29b00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 lite3_prepare |
29b10 70 72 65 70 61 72 65 64 5d 20 6f 72 20 5b 73 71 prepared] or [sq
29b20 6c 69 74 65 33 5f 72 65 73 65 74 20 7c 20 72 65 lite3_reset | re
29b30 73 65 74 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 set],.**
29b40 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f the [sqlite3_
29b50 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 20 72 data_count(S)] r
29b60 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a outine returns z
29b70 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ero..*/.int sqli
29b80 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 te3_data_count(s
29b90 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
29ba0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
29bb0 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 3REF: Fundamenta
29bc0 6c 20 44 61 74 61 74 79 70 65 73 20 7b 48 31 30 l Datatypes {H10
29bd0 32 36 35 7d 20 3c 53 31 30 31 31 30 3e 3c 53 31 265} <S10110><S1
29be0 30 31 32 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 0120>.** KEYWORD
29bf0 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a S: SQLITE_TEXT.*
29c00 2a 0a 2a 2a 20 7b 48 31 30 32 36 36 7d 20 45 76 *.** {H10266} Ev
29c10 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c ery value in SQL
29c20 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 ite has one of f
29c30 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 ive fundamental
29c40 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a datatypes:.**.**
29c50 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 <ul>.** <li> 64
29c60 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 -bit signed inte
29c70 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 ger.** <li> 64-b
29c80 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 it IEEE floating
29c90 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a point number.**
29ca0 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 <li> string.**
29cb0 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 <li> BLOB.** <li
29cc0 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 > NULL.** </ul>
29cd0 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 {END}.**.** Thes
29ce0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 e constants are
29cf0 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f codes for each o
29d00 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a f those types..*
29d10 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 *.** Note that t
29d20 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 he SQLITE_TEXT c
29d30 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f onstant was also
29d40 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 used in SQLite
29d50 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 version 2.** for
29d60 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 a completely di
29d70 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e fferent meaning.
29d80 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 Software that
29d90 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f links against bo
29da0 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 th.** SQLite ver
29db0 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 sion 2 and SQLit
29dc0 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 e version 3 shou
29dd0 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 ld use SQLITE3_T
29de0 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 EXT, not.** SQLI
29df0 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 TE_TEXT..*/.#def
29e00 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 ine SQLITE_INTEG
29e10 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 ER 1.#define SQ
29e20 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a LITE_FLOAT 2.
29e30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 #define SQLITE_B
29e40 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e LOB 4.#defin
29e50 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 e SQLITE_NULL
29e60 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 5.#ifdef SQLIT
29e70 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 E_TEXT.# undef S
29e80 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 QLITE_TEXT.#else
29e90 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
29ea0 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 _TEXT 3.#end
29eb0 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 if.#define SQLIT
29ec0 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f E3_TEXT 3../
29ed0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
29ee0 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f esult Values Fro
29ef0 6d 20 41 20 51 75 65 72 79 20 7b 48 31 33 38 30 m A Query {H1380
29f00 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 0} <S10700>.** K
29f10 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e EYWORDS: {column
29f20 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e access function
29f30 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 s}.**.** These r
29f40 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 outines form the
29f50 20 22 72 65 73 75 6c 74 20 73 65 74 20 71 75 65 "result set que
29f60 72 79 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a ry" interface..*
29f70 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
29f80 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 nes return infor
29f90 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 mation about a s
29fa0 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 ingle column of
29fb0 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 the current.** r
29fc0 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 esult row of a q
29fd0 75 65 72 79 2e 20 20 49 6e 20 65 76 65 72 79 20 uery. In every
29fe0 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61 case the first a
29ff0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 rgument is a poi
2a000 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b nter.** to the [
2a010 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2a020 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e nt] that is bein
2a030 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 g evaluated (the
2a040 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d [sqlite3_stmt*]
2a050 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 .** that was ret
2a060 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 urned from [sqli
2a070 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
2a080 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 ] or one of its
2a090 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 variants).** and
2a0a0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
2a0b0 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 ment is the inde
2a0c0 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 x of the column
2a0d0 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d for which inform
2a0e0 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 ation.** should
2a0f0 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 be returned. Th
2a100 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d e leftmost colum
2a110 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 n of the result
2a120 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 set has the inde
2a130 78 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 x 0..**.** If th
2a140 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
2a150 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 does not current
2a160 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 ly point to a va
2a170 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 lid row, or if t
2a180 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 he.** column ind
2a190 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e ex is out of ran
2a1a0 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 ge, the result i
2a1b0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 s undefined..**
2a1c0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d These routines m
2a1d0 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 ay only be calle
2a1e0 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 d when the most
2a1f0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a recent call to.*
2a200 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 * [sqlite3_step(
2a210 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 )] has returned
2a220 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 [SQLITE_ROW] and
2a230 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c neither.** [sql
2a240 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f ite3_reset()] no
2a250 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c r [sqlite3_final
2a260 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e ize()] have been
2a270 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 called subseque
2a280 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 ntly..** If any
2a290 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 of these routine
2a2a0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 s are called aft
2a2b0 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 er [sqlite3_rese
2a2c0 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 t()] or.** [sqli
2a2d0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
2a2e0 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 or after [sqlite
2a2f0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 3_step()] has re
2a300 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 turned.** someth
2a310 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b ing other than [
2a320 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 SQLITE_ROW], the
2a330 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 results are und
2a340 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 efined..** If [s
2a350 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f qlite3_step()] o
2a360 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 r [sqlite3_reset
2a370 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
2a380 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 finalize()].** a
2a390 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 re called from a
2a3a0 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 different threa
2a3b0 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 d while any of t
2a3c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a hese routines.**
2a3d0 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 are pending, th
2a3e0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 en the results a
2a3f0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a re undefined..**
2a400 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
2a410 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f column_type() ro
2a420 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 utine returns th
2a430 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 e.** [SQLITE_INT
2a440 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 EGER | datatype
2a450 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e code] for the in
2a460 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a itial data type.
2a470 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 ** of the result
2a480 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65 column. The re
2a490 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 turned value is
2a4a0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 one of [SQLITE_I
2a4b0 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c NTEGER],.** [SQL
2a4c0 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c ITE_FLOAT], [SQL
2a4d0 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 ITE_TEXT], [SQLI
2a4e0 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 TE_BLOB], or [SQ
2a4f0 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 LITE_NULL]. The
2a500 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e value.** return
2a510 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f ed by sqlite3_co
2a520 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f lumn_type() is o
2a530 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 nly meaningful i
2a540 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e f no type.** con
2a550 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 versions have oc
2a560 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 curred as descri
2a570 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 bed below. Afte
2a580 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 r a type convers
2a590 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 ion,.** the valu
2a5a0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 e returned by sq
2a5b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 lite3_column_typ
2a5c0 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 e() is undefined
2a5d0 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 . Future.** ver
2a5e0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 sions of SQLite
2a5f0 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 may change the b
2a600 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 ehavior of sqlit
2a610 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 e3_column_type()
2a620 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 .** following a
2a630 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e type conversion.
2a640 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 .**.** If the re
2a650 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f sult is a BLOB o
2a660 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 r UTF-8 string t
2a670 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f hen the sqlite3_
2a680 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a column_bytes().*
2a690 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e * routine return
2a6a0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
2a6b0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c bytes in that BL
2a6c0 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a OB or string..**
2a6d0 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 If the result i
2a6e0 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e s a UTF-16 strin
2a6f0 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f g, then sqlite3_
2a700 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 column_bytes() c
2a710 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 onverts.** the s
2a720 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 tring to UTF-8 a
2a730 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 nd then returns
2a740 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
2a750 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 tes..** If the r
2a760 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 esult is a numer
2a770 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 ic value then sq
2a780 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2a790 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 es() uses.** [sq
2a7a0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
2a7b0 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 ] to convert tha
2a7c0 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 t value to a UTF
2a7d0 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 -8 string and re
2a7e0 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d turns.** the num
2a7f0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 ber of bytes in
2a800 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 that string..**
2a810 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e The value return
2a820 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c ed does not incl
2a830 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 ude the zero ter
2a840 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65 minator at the e
2a850 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 nd.** of the str
2a860 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72 69 74 ing. For clarit
2a870 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 y: the value ret
2a880 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d urned is the num
2a890 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 ber of.** bytes
2a8a0 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e in the string, n
2a8b0 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ot the number of
2a8c0 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a characters..**.
2a8d0 2a 2a 20 53 74 72 69 6e 67 73 20 72 65 74 75 72 ** Strings retur
2a8e0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 ned by sqlite3_c
2a8f0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 olumn_text() and
2a900 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2a910 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 text16(),.** eve
2a920 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c n empty strings,
2a930 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f are always zero
2a940 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 terminated. Th
2a950 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 e return.** valu
2a960 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 e from sqlite3_c
2a970 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 olumn_blob() for
2a980 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 a zero-length B
2a990 4c 4f 42 20 69 73 20 61 6e 20 61 72 62 69 74 72 LOB is an arbitr
2a9a0 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 ary.** pointer,
2a9b0 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20 possibly even a
2a9c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
2a9d0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
2a9e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
2a9f0 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 routine is simi
2aa00 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 lar to sqlite3_c
2aa10 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a olumn_bytes().**
2aa20 20 62 75 74 20 6c 65 61 76 65 73 20 74 68 65 20 but leaves the
2aa30 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 36 result in UTF-16
2aa40 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 in native byte
2aa50 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66 order instead of
2aa60 20 55 54 46 2d 38 2e 0a 2a 2a 20 54 68 65 20 7a UTF-8..** The z
2aa70 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 ero terminator i
2aa80 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 s not included i
2aa90 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a n this count..**
2aaa0 0a 2a 2a 20 54 68 65 20 6f 62 6a 65 63 74 20 72 .** The object r
2aab0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 eturned by [sqli
2aac0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 te3_column_value
2aad0 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e ()] is an.** [un
2aae0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
2aaf0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 3_value] object.
2ab00 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 An unprotected
2ab10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
2ab20 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c bject.** may onl
2ab30 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b y be used with [
2ab40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c sqlite3_bind_val
2ab50 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 ue()] and [sqlit
2ab60 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 e3_result_value(
2ab70 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 )]..** If the [u
2ab80 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
2ab90 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
2aba0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 returned by.**
2abb0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
2abc0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 value()] is used
2abd0 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 in any other wa
2abe0 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c y, including cal
2abf0 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 ls.** to routine
2ac00 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f s like [sqlite3_
2ac10 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 value_int()], [s
2ac20 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
2ac30 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c t()],.** or [sql
2ac40 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 ite3_value_bytes
2ac50 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 ()], then the be
2ac60 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 havior is undefi
2ac70 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ned..**.** These
2ac80 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 routines attemp
2ac90 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 t to convert the
2aca0 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 value where app
2acb0 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a ropriate. For.*
2acc0 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 * example, if th
2acd0 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 e internal repre
2ace0 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f sentation is FLO
2acf0 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 AT and a text re
2ad00 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 sult.** is reque
2ad10 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 sted, [sqlite3_s
2ad20 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 nprintf()] is us
2ad30 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f ed internally to
2ad40 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 perform the.**
2ad50 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d conversion autom
2ad60 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 66 atically. The f
2ad70 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 ollowing table d
2ad80 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 etails the conve
2ad90 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 rsions.** that a
2ada0 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a re applied:.**.*
2adb0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a * <blockquote>.*
2adc0 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d * <table border=
2add0 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e "1">.** <tr><th>
2ade0 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 Internal<br>Typ
2adf0 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 e <th> Requested
2ae00 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 <br>Type <th> C
2ae10 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 onversion.**.**
2ae20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 <tr><td> NULL
2ae30 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 <td> INTEGER
2ae40 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 <td> Result is
2ae50 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 0.** <tr><td> N
2ae60 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f ULL <td> FLO
2ae70 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c AT <td> Resul
2ae80 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e t is 0.0.** <tr>
2ae90 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 <td> NULL <t
2aea0 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 d> TEXT <td
2aeb0 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c > Result is NULL
2aec0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e pointer.** <tr>
2aed0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 <td> NULL <t
2aee0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 d> BLOB <td
2aef0 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c > Result is NULL
2af00 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e pointer.** <tr>
2af10 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 <td> INTEGER <t
2af20 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 d> FLOAT <td
2af30 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 > Convert from i
2af40 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a nteger to float.
2af50 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 ** <tr><td> INTE
2af60 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 GER <td> TEXT
2af70 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 <td> ASCII r
2af80 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 endering of the
2af90 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c integer.** <tr><
2afa0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 td> INTEGER <td
2afb0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e > BLOB <td>
2afc0 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 Same as INTEGER
2afd0 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 ->TEXT.** <tr><t
2afe0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e d> FLOAT <td>
2aff0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 INTEGER <td>
2b000 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f Convert from flo
2b010 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a at to integer.**
2b020 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 <tr><td> FLOAT
2b030 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 <td> TEXT
2b040 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e <td> ASCII ren
2b050 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c dering of the fl
2b060 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 oat.** <tr><td>
2b070 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 FLOAT <td>
2b080 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d BLOB <td> Sam
2b090 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 e as FLOAT->TEXT
2b0a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 .** <tr><td> TE
2b0b0 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 XT <td> INTEG
2b0c0 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 ER <td> Use at
2b0d0 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e oi().** <tr><td>
2b0e0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 TEXT <td>
2b0f0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 FLOAT <td> Us
2b100 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e e atof().** <tr>
2b110 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 <td> TEXT <t
2b120 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 d> BLOB <td
2b130 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c > No change.** <
2b140 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 tr><td> BLOB
2b150 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 <td> INTEGER
2b160 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 <td> Convert to
2b170 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 TEXT then use at
2b180 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e oi().** <tr><td>
2b190 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 BLOB <td>
2b1a0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f FLOAT <td> Co
2b1b0 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 nvert to TEXT th
2b1c0 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a en use atof().**
2b1d0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 <tr><td> BLOB
2b1e0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 <td> TEXT
2b1f0 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 <td> Add a zer
2b200 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 o terminator if
2b210 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c needed.** </tabl
2b220 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f e>.** </blockquo
2b230 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 te>.**.** The ta
2b240 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 ble above makes
2b250 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 reference to sta
2b260 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 ndard C library
2b270 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 functions atoi()
2b280 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 .** and atof().
2b290 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 SQLite does not
2b2a0 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 really use thes
2b2b0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 e functions. It
2b2c0 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 has its.** own
2b2d0 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 equivalent inter
2b2e0 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 nal routines. T
2b2f0 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 he atoi() and at
2b300 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a of() names are.*
2b310 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 * used in the ta
2b320 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 ble for brevity
2b330 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79 and because they
2b340 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f are familiar to
2b350 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 most.** C progr
2b360 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f ammers..**.** No
2b370 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 te that when typ
2b380 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 e conversions oc
2b390 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 cur, pointers re
2b3a0 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a turned by prior.
2b3b0 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 ** calls to sqli
2b3c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
2b3d0 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d ), sqlite3_colum
2b3e0 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 n_text(), and/or
2b3f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 .** sqlite3_colu
2b400 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 mn_text16() may
2b410 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a be invalidated..
2b420 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 ** Type conversi
2b430 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 ons and pointer
2b440 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 invalidations mi
2b450 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 ght occur.** in
2b460 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 the following ca
2b470 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a ses:.**.** <ul>.
2b480 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 ** <li> The init
2b490 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 ial content is a
2b4a0 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 BLOB and sqlite
2b4b0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 3_column_text()
2b4c0 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 or.** sqlit
2b4d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
2b4e0 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 () is called. A
2b4f0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 zero-terminator
2b500 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e might.** n
2b510 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 eed to be added
2b520 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f to the string.</
2b530 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 li>.** <li> The
2b540 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 initial content
2b550 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e is UTF-8 text an
2b560 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e d sqlite3_column
2b570 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a _bytes16() or.**
2b580 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f sqlite3_co
2b590 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 lumn_text16() is
2b5a0 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f called. The co
2b5b0 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f ntent must be co
2b5c0 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 nverted.**
2b5d0 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a to UTF-16.</li>.
2b5e0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 ** <li> The init
2b5f0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 ial content is U
2b600 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 TF-16 text and s
2b610 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
2b620 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 tes() or.**
2b630 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2b640 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 text() is called
2b650 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d . The content m
2b660 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 ust be converted
2b670 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d .** to UTF-
2b680 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 8.</li>.** </ul>
2b690 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f .**.** Conversio
2b6a0 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 ns between UTF-1
2b6b0 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 6be and UTF-16le
2b6c0 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 are always done
2b6d0 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f in place and do
2b6e0 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 .** not invalida
2b6f0 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 te a prior point
2b700 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f er, though of co
2b710 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 urse the content
2b720 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a of the buffer.*
2b730 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 * that the prior
2b740 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 pointer points
2b750 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 to will have bee
2b760 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 n modified. Oth
2b770 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 er kinds.** of c
2b780 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f onversion are do
2b790 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e ne in place when
2b7a0 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c it is possible,
2b7b0 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 but sometimes t
2b7c0 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 hey.** are not p
2b7d0 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 ossible and in t
2b7e0 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 hose cases prior
2b7f0 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e pointers are in
2b800 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a validated..**.**
2b810 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 The safest and
2b820 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d easiest to remem
2b830 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f ber policy is to
2b840 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f invoke these ro
2b850 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 utines.** in one
2b860 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e of the followin
2b870 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 g ways:.**.** <u
2b880 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 l>.** <li>sqlit
2b890 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
2b8a0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c followed by sql
2b8b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
2b8c0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 s()</li>.** <li
2b8d0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f >sqlite3_column_
2b8e0 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 blob() followed
2b8f0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d by sqlite3_colum
2b900 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a n_bytes()</li>.*
2b910 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 * <li>sqlite3_c
2b920 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 olumn_text16() f
2b930 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 ollowed by sqlit
2b940 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
2b950 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 6()</li>.** </ul
2b960 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 >.**.** In other
2b970 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 words, you shou
2b980 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f ld call sqlite3_
2b990 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a column_text(),.*
2b9a0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e * sqlite3_column
2b9b0 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 _blob(), or sqli
2b9c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
2b9d0 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 6() first to for
2b9e0 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a ce the result.**
2b9f0 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 into the desire
2ba00 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 d format, then i
2ba10 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f nvoke sqlite3_co
2ba20 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a lumn_bytes() or.
2ba30 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d ** sqlite3_colum
2ba40 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 n_bytes16() to f
2ba50 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 ind the size of
2ba60 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 the result. Do
2ba70 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a not mix calls.**
2ba80 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to sqlite3_colu
2ba90 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c mn_text() or sql
2baa0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 ite3_column_blob
2bab0 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f () with calls to
2bac0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 .** sqlite3_colu
2bad0 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e mn_bytes16(), an
2bae0 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c d do not mix cal
2baf0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ls to sqlite3_co
2bb00 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a lumn_text16().**
2bb10 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 with calls to s
2bb20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
2bb30 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 tes()..**.** The
2bb40 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e pointers return
2bb50 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 ed are valid unt
2bb60 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 il a type conver
2bb70 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a sion occurs as.*
2bb80 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 * described abov
2bb90 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c e, or until [sql
2bba0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 ite3_step()] or
2bbb0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
2bbc0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ] or.** [sqlite3
2bbd0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 _finalize()] is
2bbe0 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65 6d called. The mem
2bbf0 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 ory space used t
2bc00 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a o hold strings.*
2bc10 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 * and BLOBs is f
2bc20 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c reed automatical
2bc30 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f ly. Do <b>not</
2bc40 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e b> pass the poin
2bc50 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a ters returned.**
2bc60 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
2bc70 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 _blob()], [sqlit
2bc80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
2bc90 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 ], etc. into.**
2bca0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
2bcb0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 6d ..**.** If a mem
2bcc0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 ory allocation e
2bcd0 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 rror occurs duri
2bce0 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f ng the evaluatio
2bcf0 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 n of any.** of t
2bd00 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 hese routines, a
2bd10 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 default value i
2bd20 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 s returned. The
2bd30 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a default value.*
2bd40 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 * is either the
2bd50 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 integer 0, the f
2bd60 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 loating point nu
2bd70 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e mber 0.0, or a N
2bd80 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 ULL.** pointer.
2bd90 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c Subsequent call
2bda0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 s to [sqlite3_er
2bdb0 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 rcode()] will re
2bdc0 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f turn.** [SQLITE_
2bdd0 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e NOMEM]..**.** IN
2bde0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
2bdf0 7b 48 31 33 38 30 33 7d 20 54 68 65 20 5b 73 71 {H13803} The [sq
2be00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
2be10 62 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 b(S,N)] interfac
2be20 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a e converts the.*
2be30 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 * Nth c
2be40 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 olumn in the cur
2be50 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 rent row of the
2be60 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a result set for.*
2be70 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b * the [
2be80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2be90 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 42 4c 4f nt] S into a BLO
2bea0 42 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 B and then retur
2beb0 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 ns a.**
2bec0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
2bed0 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65 2e converted value.
2bee0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30 36 7d 20 .**.** {H13806}
2bef0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c The [sqlite3_col
2bf00 75 6d 6e 5f 62 79 74 65 73 28 53 2c 4e 29 5d 20 umn_bytes(S,N)]
2bf10 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
2bf20 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 s the.**
2bf30 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 number of byte
2bf40 73 20 69 6e 20 74 68 65 20 42 4c 4f 42 20 6f 72 s in the BLOB or
2bf50 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 string (exclusi
2bf60 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 ve of the.**
2bf70 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 zero termi
2bf80 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 nator on the str
2bf90 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65 ing) that was re
2bfa0 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a turned by the.**
2bfb0 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 most r
2bfc0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 ecent call to [s
2bfd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
2bfe0 6f 62 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 ob(S,N)] or.**
2bff0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
2c000 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e _column_text(S,N
2c010 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30 )]..**.** {H1380
2c020 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 9} The [sqlite3_
2c030 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 53 column_bytes16(S
2c040 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 ,N)] interface r
2c050 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 eturns the.**
2c060 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 number of
2c070 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 bytes in the st
2c080 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 ring (exclusive
2c090 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 of the.**
2c0a0 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 zero terminat
2c0b0 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 or on the string
2c0c0 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 ) that was retur
2c0d0 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 ned by the.**
2c0e0 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 most rece
2c0f0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 nt call to [sqli
2c100 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
2c110 36 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 6(S,N)]..**.** {
2c120 48 31 33 38 31 32 7d 20 54 68 65 20 5b 73 71 6c H13812} The [sql
2c130 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 ite3_column_doub
2c140 6c 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 le(S,N)] interfa
2c150 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a ce converts the.
2c160 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 ** Nth
2c170 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 column in the cu
2c180 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 rrent row of the
2c190 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 20 result set for
2c1a0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
2c1b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2c1c0 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 66 6c ent] S into a fl
2c1d0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c oating point val
2c1e0 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 ue and.**
2c1f0 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 returns a cop
2c200 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e y of that value.
2c210 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 31 35 7d 20 .**.** {H13815}
2c220 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c The [sqlite3_col
2c230 75 6d 6e 5f 69 6e 74 28 53 2c 4e 29 5d 20 69 6e umn_int(S,N)] in
2c240 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 terface converts
2c250 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
2c260 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 Nth column in t
2c270 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f he current row o
2c280 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 f the result set
2c290 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 for the.**
2c2a0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 [prepared s
2c2b0 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f tatement] S into
2c2c0 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 a 64-bit signed
2c2d0 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 integer and.**
2c2e0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 returns
2c2f0 20 74 68 65 20 6c 6f 77 65 72 20 33 32 20 62 69 the lower 32 bi
2c300 74 73 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 ts of that integ
2c310 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 31 er..**.** {H1381
2c320 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 8} The [sqlite3_
2c330 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 53 2c 4e column_int64(S,N
2c340 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e )] interface con
2c350 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 verts the.**
2c360 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e Nth column
2c370 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 in the current
2c380 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c row of the resul
2c390 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a t set for the.**
2c3a0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 [prepa
2c3b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
2c3c0 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 into a 64-bit s
2c3d0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e igned integer an
2c3e0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 d.** re
2c3f0 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 turns a copy of
2c400 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a that integer..**
2c410 0a 2a 2a 20 7b 48 31 33 38 32 31 7d 20 54 68 65 .** {H13821} The
2c420 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
2c430 5f 74 65 78 74 28 53 2c 4e 29 5d 20 69 6e 74 65 _text(S,N)] inte
2c440 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 rface converts t
2c450 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e he.** N
2c460 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 th column in the
2c470 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 current row of
2c480 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 the result set f
2c490 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 or.** t
2c4a0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
2c4b0 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 tement] S into a
2c4c0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
2c4d0 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 UTF-8.**
2c4e0 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 string and re
2c4f0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
2c500 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a to that string..
2c510 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 34 7d 20 54 **.** {H13824} T
2c520 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 he [sqlite3_colu
2c530 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d 20 mn_text16(S,N)]
2c540 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 interface conver
2c550 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 ts the.**
2c560 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e Nth column in
2c570 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 the current row
2c580 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 of the result s
2c590 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 et for the.**
2c5a0 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 [prepared
2c5b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e statement] S in
2c5c0 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e to a zero-termin
2c5d0 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 ated 2-byte.**
2c5e0 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 aligned
2c5f0 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 UTF-16 native by
2c600 74 65 20 6f 72 64 65 72 20 73 74 72 69 6e 67 20 te order string
2c610 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 and returns.**
2c620 20 20 20 20 20 20 20 20 61 20 70 6f 69 6e 74 65 a pointe
2c630 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 r to that string
2c640 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 37 7d ..**.** {H13827}
2c650 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f The [sqlite3_co
2c660 6c 75 6d 6e 5f 74 79 70 65 28 53 2c 4e 29 5d 20 lumn_type(S,N)]
2c670 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
2c680 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e s.** on
2c690 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c e of [SQLITE_NUL
2c6a0 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 L], [SQLITE_INTE
2c6b0 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c GER], [SQLITE_FL
2c6c0 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 OAT],.**
2c6d0 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c [SQLITE_TEXT],
2c6e0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 or [SQLITE_BLOB
2c6f0 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61 74 65 ] as appropriate
2c700 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 for.**
2c710 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
2c720 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 in the current r
2c730 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 ow of the result
2c740 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 set for.**
2c750 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61 72 the [prepar
2c760 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e ed statement] S.
2c770 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 33 30 7d 20 .**.** {H13830}
2c780 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c The [sqlite3_col
2c790 75 6d 6e 5f 76 61 6c 75 65 28 53 2c 4e 29 5d 20 umn_value(S,N)]
2c7a0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
2c7b0 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 s a.**
2c7c0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 75 pointer to an [u
2c7d0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
2c7e0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
2c7f0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 for the.**
2c800 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 Nth column
2c810 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 in the current r
2c820 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 ow of the result
2c830 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 set for.**
2c840 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61 72 the [prepar
2c850 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e ed statement] S.
2c860 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a .*/.const void *
2c870 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2c880 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 lob(sqlite3_stmt
2c890 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e *, int iCol);.in
2c8a0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e t sqlite3_column
2c8b0 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 _bytes(sqlite3_s
2c8c0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
2c8d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c .int sqlite3_col
2c8e0 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 umn_bytes16(sqli
2c8f0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
2c900 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c Col);.double sql
2c910 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 ite3_column_doub
2c920 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a le(sqlite3_stmt*
2c930 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 , int iCol);.int
2c940 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2c950 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 int(sqlite3_stmt
2c960 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 *, int iCol);.sq
2c970 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 lite3_int64 sqli
2c980 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 te3_column_int64
2c990 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
2c9a0 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 int iCol);.const
2c9b0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a unsigned char *
2c9c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2c9d0 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ext(sqlite3_stmt
2c9e0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f *, int iCol);.co
2c9f0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
2ca00 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
2ca10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2ca20 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 nt iCol);.int sq
2ca30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 lite3_column_typ
2ca40 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
2ca50 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 int iCol);.sqli
2ca60 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 te3_value *sqlit
2ca70 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 e3_column_value(
2ca80 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2ca90 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a nt iCol);../*.**
2caa0 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 CAPI3REF: Destr
2cab0 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74 oy A Prepared St
2cac0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b atement Object {
2cad0 48 31 33 33 30 30 7d 20 3c 53 37 30 33 30 30 3e H13300} <S70300>
2cae0 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S30100>.**.** T
2caf0 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c he sqlite3_final
2cb00 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 ize() function i
2cb10 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 s called to dele
2cb20 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 te a [prepared s
2cb30 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 tatement]..** If
2cb40 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 the statement w
2cb50 61 73 20 65 78 65 63 75 74 65 64 20 73 75 63 63 as executed succ
2cb60 65 73 73 66 75 6c 6c 79 20 6f 72 20 6e 6f 74 20 essfully or not
2cb70 65 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c executed at all,
2cb80 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f then.** SQLITE_
2cb90 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 OK is returned.
2cba0 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 If execution of
2cbb0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61 the statement fa
2cbc0 69 6c 65 64 20 74 68 65 6e 20 61 6e 0a 2a 2a 20 iled then an.**
2cbd0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 [error code] or
2cbe0 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 [extended error
2cbf0 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 code] is returne
2cc00 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f d..**.** This ro
2cc10 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c utine can be cal
2cc20 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 led at any point
2cc30 20 64 75 72 69 6e 67 20 74 68 65 20 65 78 65 63 during the exec
2cc40 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 ution of the.**
2cc50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2cc60 65 6e 74 5d 2e 20 20 49 66 20 74 68 65 20 76 69 ent]. If the vi
2cc70 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 61 rtual machine ha
2cc80 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74 s not.** complet
2cc90 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77 68 65 ed execution whe
2cca0 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 n this routine i
2ccb0 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 20 69 s called, that i
2ccc0 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e s like.** encoun
2ccd0 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 tering an error
2cce0 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 or an [sqlite3_i
2ccf0 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 nterrupt | inter
2cd00 72 75 70 74 5d 2e 0a 2a 2a 20 49 6e 63 6f 6d 70 rupt]..** Incomp
2cd10 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d 61 79 lete updates may
2cd20 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 be rolled back
2cd30 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 and transactions
2cd40 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64 65 canceled,.** de
2cd50 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 pending on the c
2cd60 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e ircumstances, an
2cd70 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72 6f 72 20 d the.** [error
2cd80 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 20 77 code] returned w
2cd90 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 ill be [SQLITE_A
2cda0 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 BORT]..**.** INV
2cdb0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
2cdc0 48 31 31 33 30 32 7d 20 54 68 65 20 5b 73 71 6c H11302} The [sql
2cdd0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 ite3_finalize(S)
2cde0 5d 20 69 6e 74 65 72 66 61 63 65 20 64 65 73 74 ] interface dest
2cdf0 72 6f 79 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 roys the.**
2ce00 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 [prepared s
2ce10 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 6e 64 20 tatement] S and
2ce20 72 65 6c 65 61 73 65 73 20 61 6c 6c 0a 2a 2a 20 releases all.**
2ce30 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 memory
2ce40 61 6e 64 20 66 69 6c 65 20 72 65 73 6f 75 72 63 and file resourc
2ce50 65 73 20 68 65 6c 64 20 62 79 20 74 68 61 74 20 es held by that
2ce60 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 object..**.** {H
2ce70 31 31 33 30 34 7d 20 49 66 20 74 68 65 20 6d 6f 11304} If the mo
2ce80 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 st recent call t
2ce90 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 o [sqlite3_step(
2cea0 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 S)] for the.**
2ceb0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 [prepare
2cec0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 d statement] S r
2ced0 65 74 75 72 6e 65 64 20 61 6e 20 65 72 72 6f 72 eturned an error
2cee0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 ,.** th
2cef0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 en [sqlite3_fina
2cf00 6c 69 7a 65 28 53 29 5d 20 72 65 74 75 72 6e 73 lize(S)] returns
2cf10 20 74 68 61 74 20 73 61 6d 65 20 65 72 72 6f 72 that same error
2cf20 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
2cf30 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 _finalize(sqlite
2cf40 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 3_stmt *pStmt);.
2cf50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2cf60 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65 Reset A Prepare
2cf70 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 d Statement Obje
2cf80 63 74 20 7b 48 31 33 33 33 30 7d 20 3c 53 37 30 ct {H13330} <S70
2cf90 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 300>.**.** The s
2cfa0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 qlite3_reset() f
2cfb0 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 unction is calle
2cfc0 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 d to reset a [pr
2cfd0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2cfe0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b ].** object back
2cff0 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 to its initial
2d000 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 state, ready to
2d010 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a be re-executed..
2d020 2a 2a 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65 ** Any SQL state
2d030 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 ment variables t
2d040 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 hat had values b
2d050 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 ound to them usi
2d060 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 ng.** the [sqlit
2d070 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 e3_bind_blob | s
2d080 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 qlite3_bind_*()
2d090 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 API] retain thei
2d0a0 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 r values..** Use
2d0b0 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f [sqlite3_clear_
2d0c0 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 bindings()] to r
2d0d0 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 eset the binding
2d0e0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 32 s..**.** {H11332
2d0f0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 } The [sqlite3_r
2d100 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 eset(S)] interfa
2d110 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 ce resets the [p
2d120 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2d130 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 t] S.**
2d140 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 back to the beg
2d150 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 inning of its pr
2d160 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ogram..**.** {H1
2d170 31 33 33 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 1334} If the mos
2d180 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f t recent call to
2d190 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 [sqlite3_step(S
2d1a0 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 )] for the.**
2d1b0 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 [prepared
2d1c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 statement] S re
2d1d0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 turned [SQLITE_R
2d1e0 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 OW] or [SQLITE_D
2d1f0 4f 4e 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 ONE],.**
2d200 20 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 or if [sqlite3
2d210 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 _step(S)] has ne
2d220 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 ver before been
2d230 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 called on S,.**
2d240 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 then [s
2d250 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d qlite3_reset(S)]
2d260 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
2d270 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 _OK]..**.** {H11
2d280 33 33 36 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 336} If the most
2d290 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 recent call to
2d2a0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
2d2b0 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 ] for the.**
2d2c0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 [prepared
2d2d0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 statement] S ind
2d2e0 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c icated an error,
2d2f0 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 then.**
2d300 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 [sqlite3_reset
2d310 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 (S)] returns an
2d320 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 appropriate [err
2d330 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 or code]..**.**
2d340 7b 48 31 31 33 33 38 7d 20 54 68 65 20 5b 73 71 {H11338} The [sq
2d350 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 lite3_reset(S)]
2d360 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e interface does n
2d370 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 ot change the va
2d380 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 lues.**
2d390 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 of any [sqlite3
2d3a0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 _bind_blob|bindi
2d3b0 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 ngs] on the [pre
2d3c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2d3d0 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 S..*/.int sqlit
2d3e0 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 e3_reset(sqlite3
2d3f0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a _stmt *pStmt);..
2d400 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2d410 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 Create Or Redefi
2d420 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 ne SQL Functions
2d430 20 7b 48 31 36 31 30 30 7d 20 3c 53 32 30 32 30 {H16100} <S2020
2d440 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 0>.** KEYWORDS:
2d450 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 {function creati
2d460 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 on routines}.**
2d470 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 KEYWORDS: {appli
2d480 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 cation-defined S
2d490 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 QL function}.**
2d4a0 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 KEYWORDS: {appli
2d4b0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 cation-defined S
2d4c0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a QL functions}.**
2d4d0 0a 2a 2a 20 54 68 65 73 65 20 74 77 6f 20 66 75 .** These two fu
2d4e0 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 nctions (collect
2d4f0 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 ively known as "
2d500 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f function creatio
2d510 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 n routines").**
2d520 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 are used to add
2d530 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 SQL functions or
2d540 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 aggregates or t
2d550 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 o redefine the b
2d560 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 ehavior.** of ex
2d570 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 isting SQL funct
2d580 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 ions or aggregat
2d590 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 es. The only di
2d5a0 66 66 65 72 65 6e 63 65 20 62 65 74 77 65 65 6e fference between
2d5b0 20 74 68 65 0a 2a 2a 20 74 77 6f 20 69 73 20 74 the.** two is t
2d5c0 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 70 hat the second p
2d5d0 61 72 61 6d 65 74 65 72 2c 20 74 68 65 20 6e 61 arameter, the na
2d5e0 6d 65 20 6f 66 20 74 68 65 20 28 73 63 61 6c 61 me of the (scala
2d5f0 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a r) function or.*
2d600 2a 20 61 67 67 72 65 67 61 74 65 2c 20 69 73 20 * aggregate, is
2d610 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 encoded in UTF-8
2d620 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 for sqlite3_cre
2d630 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 ate_function() a
2d640 6e 64 20 55 54 46 2d 31 36 0a 2a 2a 20 66 6f 72 nd UTF-16.** for
2d650 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
2d660 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a function16()..**
2d670 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 .** The first pa
2d680 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b rameter is the [
2d690 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2d6a0 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 ion] to which th
2d6b0 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f e SQL.** functio
2d6c0 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 n is to be added
2d6d0 2e 20 20 49 66 20 61 20 73 69 6e 67 6c 65 20 70 . If a single p
2d6e0 72 6f 67 72 61 6d 20 75 73 65 73 20 6d 6f 72 65 rogram uses more
2d6f0 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 than one databa
2d700 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e se.** connection
2d710 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68 65 internally, the
2d720 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 n SQL functions
2d730 6d 75 73 74 20 62 65 20 61 64 64 65 64 20 69 6e must be added in
2d740 64 69 76 69 64 75 61 6c 6c 79 20 74 6f 0a 2a 2a dividually to.**
2d750 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 each database c
2d760 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a onnection..**.**
2d770 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 The second para
2d780 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d meter is the nam
2d790 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e e of the SQL fun
2d7a0 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 ction to be crea
2d7b0 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 ted or.** redefi
2d7c0 6e 65 64 2e 20 20 54 68 65 20 6c 65 6e 67 74 68 ned. The length
2d7d0 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 of the name is
2d7e0 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 limited to 255 b
2d7f0 79 74 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20 ytes, exclusive
2d800 6f 66 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 2d 74 of.** the zero-t
2d810 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 erminator. Note
2d820 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c that the name l
2d830 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 ength limit is i
2d840 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 n bytes, not.**
2d850 63 68 61 72 61 63 74 65 72 73 2e 20 20 41 6e 79 characters. Any
2d860 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 attempt to crea
2d870 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 te a function wi
2d880 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 th a longer name
2d890 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 .** will result
2d8a0 69 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 in [SQLITE_ERROR
2d8b0 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 ] being returned
2d8c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 ..**.** The thir
2d8d0 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 d parameter (nAr
2d8e0 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d g).** is the num
2d8f0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 ber of arguments
2d900 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 that the SQL fu
2d910 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 nction or.** agg
2d920 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 49 66 regate takes. If
2d930 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 this parameter
2d940 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 is negative, the
2d950 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 n the SQL functi
2d960 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 on or.** aggrega
2d970 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 te may take any
2d980 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 number of argume
2d990 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 nts..**.** The f
2d9a0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c ourth parameter,
2d9b0 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 eTextRep, speci
2d9c0 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 fies what.** [SQ
2d9d0 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 LITE_UTF8 | text
2d9e0 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 encoding] this
2d9f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 SQL function pre
2da00 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 fers for.** its
2da10 70 61 72 61 6d 65 74 65 72 73 2e 20 20 41 6e 79 parameters. Any
2da20 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d SQL function im
2da30 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f plementation sho
2da40 75 6c 64 20 62 65 20 61 62 6c 65 20 74 6f 20 77 uld be able to w
2da50 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68 ork.** work with
2da60 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 UTF-8, UTF-16le
2da70 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 , or UTF-16be.
2da80 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 But some impleme
2da90 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a ntations may be.
2daa0 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e ** more efficien
2dab0 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 t with one encod
2dac0 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 ing than another
2dad0 2e 20 20 49 74 20 69 73 20 61 6c 6c 6f 77 65 64 . It is allowed
2dae0 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 to.** invoke sq
2daf0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
2db00 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 ction() or sqlit
2db10 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
2db20 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a on16() multiple.
2db30 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 ** times with th
2db40 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 e same function
2db50 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65 but with differe
2db60 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 nt values of eTe
2db70 78 74 52 65 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d xtRep..** When m
2db80 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e ultiple implemen
2db90 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 tations of the s
2dba0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 ame function are
2dbb0 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 available, SQLi
2dbc0 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 te.** will pick
2dbd0 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 the one that inv
2dbe0 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 olves the least
2dbf0 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 amount of data c
2dc00 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 onversion..** If
2dc10 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 there is only a
2dc20 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e single implemen
2dc30 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 tation which doe
2dc40 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20 s not care what
2dc50 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 text.** encoding
2dc60 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 is used, then t
2dc70 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 he fourth argume
2dc80 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 nt should be [SQ
2dc90 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a LITE_ANY]..**.**
2dca0 20 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d The fifth param
2dcb0 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 eter is an arbit
2dcc0 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 rary pointer. T
2dcd0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
2dce0 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 n of the.** func
2dcf0 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 tion can gain ac
2dd00 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 cess to this poi
2dd10 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 nter using [sqli
2dd20 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d te3_user_data()]
2dd30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65 ..**.** The seve
2dd40 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20 nth, eighth and
2dd50 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73 ninth parameters
2dd60 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 , xFunc, xStep a
2dd70 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a nd xFinal, are.*
2dd80 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d * pointers to C-
2dd90 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f language functio
2dda0 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e ns that implemen
2ddb0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 t the SQL functi
2ddc0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 on or.** aggrega
2ddd0 74 65 2e 20 41 20 73 63 61 6c 61 72 20 53 51 4c te. A scalar SQL
2dde0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 function requir
2ddf0 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 es an implementa
2de00 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e tion of the xFun
2de10 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e c.** callback on
2de20 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 ly, NULL pointer
2de30 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 s should be pass
2de40 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20 ed as the xStep
2de50 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 and xFinal.** pa
2de60 72 61 6d 65 74 65 72 73 2e 20 41 6e 20 61 67 67 rameters. An agg
2de70 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 regate SQL funct
2de80 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 ion requires an
2de90 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
2dea0 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 f xStep.** and x
2deb0 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 Final and NULL s
2dec0 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 hould be passed
2ded0 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20 64 65 for xFunc. To de
2dee0 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 lete an existing
2def0 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e .** SQL function
2df00 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 or aggregate, p
2df10 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c ass NULL for all
2df20 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 20 three function
2df30 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a callbacks..**.**
2df40 20 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 It is permitted
2df50 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c to register mul
2df60 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 tiple implementa
2df70 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d tions of the sam
2df80 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 e.** functions w
2df90 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d ith the same nam
2dfa0 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 e but with eithe
2dfb0 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 r differing numb
2dfc0 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 ers of.** argume
2dfd0 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 nts or differing
2dfe0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 preferred text
2dff0 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51 4c 69 encodings. SQLi
2e000 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 te will use.** t
2e010 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
2e020 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d n most closely m
2e030 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 atches the way i
2e040 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 n which the.** S
2e050 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 QL function is u
2e060 73 65 64 2e 20 20 41 20 66 75 6e 63 74 69 6f 6e sed. A function
2e070 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
2e080 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 with a non-negat
2e090 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 ive.** nArg para
2e0a0 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65 meter is a bette
2e0b0 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 r match than a f
2e0c0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e unction implemen
2e0d0 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 tation with.** a
2e0e0 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 negative nArg.
2e0f0 20 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 A function wher
2e100 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 e the preferred
2e110 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a text encoding.**
2e120 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74 matches the dat
2e130 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 abase encoding i
2e140 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 s a better.** ma
2e150 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 tch than a funct
2e160 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e ion where the en
2e170 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 coding is differ
2e180 65 6e 74 2e 20 20 0a 2a 2a 20 41 20 66 75 6e 63 ent. .** A func
2e190 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 tion where the e
2e1a0 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e ncoding differen
2e1b0 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 ce is between UT
2e1c0 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 F16le and UTF16b
2e1d0 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 e.** is a closer
2e1e0 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 match than a fu
2e1f0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 nction where the
2e200 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 encoding differ
2e210 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 ence is.** betwe
2e220 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 en UTF8 and UTF1
2e230 36 2e 0a 2a 2a 0a 2a 2a 20 42 75 69 6c 74 2d 69 6..**.** Built-i
2e240 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 n functions may
2e250 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 be overloaded by
2e260 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e new application
2e270 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
2e280 6e 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 ns..** The first
2e290 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
2e2a0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 77 69 ined function wi
2e2b0 74 68 20 61 20 67 69 76 65 6e 20 6e 61 6d 65 20 th a given name
2e2c0 6f 76 65 72 72 69 64 65 73 20 61 6c 6c 0a 2a 2a overrides all.**
2e2d0 20 62 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 built-in functi
2e2e0 6f 6e 73 20 69 6e 20 74 68 65 20 73 61 6d 65 20 ons in the same
2e2f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2e300 74 69 6f 6e 5d 20 77 69 74 68 20 74 68 65 20 73 tion] with the s
2e310 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 20 53 75 62 ame name..** Sub
2e320 73 65 71 75 65 6e 74 20 61 70 70 6c 69 63 61 74 sequent applicat
2e330 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
2e340 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d tions of the sam
2e350 65 20 6e 61 6d 65 20 6f 6e 6c 79 20 6f 76 65 72 e name only over
2e360 72 69 64 65 20 0a 2a 2a 20 70 72 69 6f 72 20 61 ride .** prior a
2e370 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
2e380 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 ed functions tha
2e390 74 20 61 72 65 20 61 6e 20 65 78 61 63 74 20 6d t are an exact m
2e3a0 61 74 63 68 20 66 6f 72 20 74 68 65 0a 2a 2a 20 atch for the.**
2e3b0 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65 number of parame
2e3c0 74 65 72 73 20 61 6e 64 20 70 72 65 66 65 72 72 ters and preferr
2e3d0 65 64 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a ed encoding..**.
2e3e0 2a 2a 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f ** An applicatio
2e3f0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
2e400 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 on is permitted
2e410 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a to call other.**
2e420 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
2e430 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 es. However, su
2e440 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f ch calls must no
2e450 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 t.** close the d
2e460 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2e470 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 on nor finalize
2e480 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65 or reset the pre
2e490 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 pared.** stateme
2e4a0 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 nt in which the
2e4b0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e function is runn
2e4c0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 ing..**.** INVAR
2e4d0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 IANTS:.**.** {H1
2e4e0 36 31 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 6103} The [sqlit
2e4f0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
2e500 6f 6e 31 36 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 on16(D,X,...)] i
2e510 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 62 nterface shall b
2e520 65 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 ehave.**
2e530 20 20 61 73 20 5b 73 71 6c 69 74 65 33 5f 63 72 as [sqlite3_cr
2e540 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c eate_function(D,
2e550 58 2c 2e 2e 2e 29 5d 20 69 6e 20 65 76 65 72 79 X,...)] in every
2e560 20 77 61 79 20 65 78 63 65 70 74 20 74 68 61 74 way except that
2e570 20 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 it.**
2e580 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 58 interprets the X
2e590 20 61 72 67 75 6d 65 6e 74 20 61 73 20 7a 65 72 argument as zer
2e5a0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 o-terminated UTF
2e5b0 2d 31 36 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 -16.**
2e5c0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
2e5d0 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 73 20 r instead of as
2e5e0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
2e5f0 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 UTF-8..**.** {H1
2e600 36 31 30 36 7d 20 41 20 73 75 63 63 65 73 73 66 6106} A successf
2e610 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 ul invocation of
2e620 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
2e630 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
2e640 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c _function(D,X,N,
2e650 45 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 E,...)] interfac
2e660 65 20 73 68 61 6c 6c 20 72 65 67 69 73 74 65 72 e shall register
2e670 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 .** or
2e680 72 65 70 6c 61 63 65 73 20 63 61 6c 6c 62 61 63 replaces callbac
2e690 6b 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20 74 k functions in t
2e6a0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
2e6b0 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 nection] D.**
2e6c0 20 20 20 20 20 20 20 75 73 65 64 20 74 6f 20 69 used to i
2e6d0 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c mplement the SQL
2e6e0 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 64 20 function named
2e6f0 58 20 77 69 74 68 20 4e 20 70 61 72 61 6d 65 74 X with N paramet
2e700 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ers.**
2e710 61 6e 64 20 68 61 76 69 6e 67 20 61 20 70 72 65 and having a pre
2e720 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f ferred text enco
2e730 64 69 6e 67 20 6f 66 20 45 2e 0a 2a 2a 0a 2a 2a ding of E..**.**
2e740 20 7b 48 31 36 31 30 39 7d 20 41 20 73 75 63 63 {H16109} A succ
2e750 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b essful call to [
2e760 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
2e770 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c unction(D,X,N,E,
2e780 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 P,F,S,L)].**
2e790 20 20 20 20 20 20 73 68 61 6c 6c 20 72 65 70 6c shall repl
2e7a0 61 63 65 20 74 68 65 20 50 2c 20 46 2c 20 53 2c ace the P, F, S,
2e7b0 20 61 6e 64 20 4c 20 76 61 6c 75 65 73 20 66 72 and L values fr
2e7c0 6f 6d 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c om any prior cal
2e7d0 6c 73 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 ls with.**
2e7e0 20 20 20 20 74 68 65 20 73 61 6d 65 20 44 2c 20 the same D,
2e7f0 58 2c 20 4e 2c 20 61 6e 64 20 45 20 76 61 6c 75 X, N, and E valu
2e800 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 31 es..**.** {H1611
2e810 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 2} The [sqlite3_
2e820 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
2e830 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 D,X,...)] interf
2e840 61 63 65 20 73 68 61 6c 6c 20 66 61 69 6c 0a 2a ace shall fail.*
2e850 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 74 68 * if th
2e860 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e e SQL function n
2e870 61 6d 65 20 58 20 69 73 0a 2a 2a 20 20 20 20 20 ame X is.**
2e880 20 20 20 20 20 6c 6f 6e 67 65 72 20 74 68 61 6e longer than
2e890 20 32 35 35 20 62 79 74 65 73 20 65 78 63 6c 75 255 bytes exclu
2e8a0 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f sive of the zero
2e8b0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a terminator..**.
2e8c0 2a 2a 20 7b 48 31 36 31 31 38 7d 20 54 68 65 20 ** {H16118} The
2e8d0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
2e8e0 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 function(D,X,N,E
2e8f0 2c 50 2c 46 2c 53 2c 4c 29 5d 20 69 6e 74 65 72 ,P,F,S,L)] inter
2e900 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 face.**
2e910 20 73 68 61 6c 6c 20 66 61 69 6c 20 75 6e 6c 65 shall fail unle
2e920 73 73 20 65 69 74 68 65 72 20 46 20 69 73 20 4e ss either F is N
2e930 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c 20 ULL and S and L
2e940 61 72 65 20 6e 6f 6e 2d 4e 55 4c 4c 20 6f 72 0a are non-NULL or.
2e950 2a 2a 2a 20 20 20 20 20 20 20 20 20 46 20 69 73 *** F is
2e960 20 6e 6f 6e 2d 4e 55 4c 4c 20 61 6e 64 20 53 20 non-NULL and S
2e970 61 6e 64 20 4c 20 61 72 65 20 4e 55 4c 4c 2e 0a and L are NULL..
2e980 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 31 7d 20 54 **.** {H16121} T
2e990 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 he [sqlite3_crea
2e9a0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 2e 2e te_function(D,..
2e9b0 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 .)] interface sh
2e9c0 61 6c 6c 20 66 61 69 6c 73 20 77 69 74 68 20 61 all fails with a
2e9d0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 72 n.** er
2e9e0 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c ror code of [SQL
2e9f0 49 54 45 5f 42 55 53 59 5d 20 69 66 20 74 68 65 ITE_BUSY] if the
2ea00 72 65 20 65 78 69 73 74 20 5b 70 72 65 70 61 72 re exist [prepar
2ea10 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a 2a ed statements].*
2ea20 2a 20 20 20 20 20 20 20 20 20 20 61 73 73 6f 63 * assoc
2ea30 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b iated with the [
2ea40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2ea50 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ion] D..**.** {H
2ea60 31 36 31 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 16124} The [sqli
2ea70 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
2ea80 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 20 ion(D,X,N,...)]
2ea90 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 interface shall
2eaa0 66 61 69 6c 20 77 69 74 68 0a 2a 2a 20 20 20 20 fail with.**
2eab0 20 20 20 20 20 20 61 6e 20 65 72 72 6f 72 20 63 an error c
2eac0 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45 ode of [SQLITE_E
2ead0 52 52 4f 52 5d 20 69 66 20 70 61 72 61 6d 65 74 RROR] if paramet
2eae0 65 72 20 4e 20 69 73 20 6c 65 73 73 0a 2a 2a 20 er N is less.**
2eaf0 20 20 20 20 20 20 20 20 20 74 68 61 6e 20 2d 31 than -1
2eb00 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e or greater than
2eb10 20 31 32 37 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 127..**.** {H16
2eb20 31 32 37 7d 20 57 68 65 6e 20 4e 20 69 73 20 6e 127} When N is n
2eb30 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 on-negative, the
2eb40 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
2eb50 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c _function(D,X,N,
2eb60 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 ...)].**
2eb70 20 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c interface shal
2eb80 6c 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 l register callb
2eb90 61 63 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b acks to be invok
2eba0 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 ed for the.**
2ebb0 20 20 20 20 20 20 20 53 51 4c 20 66 75 6e 63 74 SQL funct
2ebc0 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ion.**
2ebd0 6e 61 6d 65 64 20 58 20 77 68 65 6e 20 74 68 65 named X when the
2ebe0 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d number of argum
2ebf0 65 6e 74 73 20 74 6f 20 74 68 65 20 53 51 4c 20 ents to the SQL
2ec00 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 function is.**
2ec10 20 20 20 20 20 20 20 20 65 78 61 63 74 6c 79 20 exactly
2ec20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 30 N..**.** {H16130
2ec30 7d 20 57 68 65 6e 20 4e 20 69 73 20 2d 31 2c 20 } When N is -1,
2ec40 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 the [sqlite3_cre
2ec50 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 ate_function(D,X
2ec60 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 ,N,...)].**
2ec70 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 73 interface s
2ec80 68 61 6c 6c 20 72 65 67 69 73 74 65 72 20 63 61 hall register ca
2ec90 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e llbacks to be in
2eca0 76 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 53 51 voked for the SQ
2ecb0 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 L.** fu
2ecc0 6e 63 74 69 6f 6e 20 6e 61 6d 65 64 20 58 20 77 nction named X w
2ecd0 69 74 68 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f ith any number o
2ece0 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a f arguments..**.
2ecf0 2a 2a 20 7b 48 31 36 31 33 33 7d 20 57 68 65 6e ** {H16133} When
2ed00 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 calls to [sqlit
2ed10 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
2ed20 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a on(D,X,N,...)].*
2ed30 2a 20 20 20 20 20 20 20 20 20 20 73 70 65 63 69 * speci
2ed40 66 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c fy multiple impl
2ed50 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 ementations of t
2ed60 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e he same function
2ed70 20 58 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 X.** a
2ed80 6e 64 20 77 68 65 6e 20 6f 6e 65 20 69 6d 70 6c nd when one impl
2ed90 65 6d 65 6e 74 61 74 69 6f 6e 20 68 61 73 20 4e ementation has N
2eda0 3e 3d 30 20 61 6e 64 20 74 68 65 20 6f 74 68 65 >=0 and the othe
2edb0 72 20 68 61 73 20 4e 3d 28 2d 31 29 0a 2a 2a 20 r has N=(-1).**
2edc0 20 20 20 20 20 20 20 20 20 74 68 65 20 69 6d 70 the imp
2edd0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 lementation with
2ede0 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 4e 20 73 68 a non-zero N sh
2edf0 61 6c 6c 20 62 65 20 70 72 65 66 65 72 72 65 64 all be preferred
2ee00 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 36 7d ..**.** {H16136}
2ee10 20 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b When calls to [
2ee20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
2ee30 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c unction(D,X,N,E,
2ee40 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 ...)].**
2ee50 20 20 73 70 65 63 69 66 79 20 6d 75 6c 74 69 70 specify multip
2ee60 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
2ee70 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 ns of the same f
2ee80 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 0a 2a unction X with.*
2ee90 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73 * the s
2eea0 61 6d 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 ame number of ar
2eeb0 67 75 6d 65 6e 74 73 20 4e 20 62 75 74 20 77 69 guments N but wi
2eec0 74 68 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 th different.**
2eed0 20 20 20 20 20 20 20 20 20 65 6e 63 6f 64 69 6e encodin
2eee0 67 73 20 45 2c 20 74 68 65 6e 20 74 68 65 20 69 gs E, then the i
2eef0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 mplementation wh
2ef00 65 72 65 20 45 20 6d 61 74 63 68 65 73 20 74 68 ere E matches th
2ef10 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 e.** da
2ef20 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 tabase encoding
2ef30 73 68 61 6c 6c 20 70 72 65 66 65 72 72 65 64 2e shall preferred.
2ef40 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 39 7d 20 .**.** {H16139}
2ef50 46 6f 72 20 61 6e 20 61 67 67 72 65 67 61 74 65 For an aggregate
2ef60 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 72 SQL function cr
2ef70 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 eated using.**
2ef80 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
2ef90 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
2efa0 28 44 2c 58 2c 4e 2c 45 2c 50 2c 30 2c 53 2c 4c (D,X,N,E,P,0,S,L
2efb0 29 5d 20 74 68 65 20 66 69 6e 61 6c 69 7a 65 72 )] the finalizer
2efc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e .** fun
2efd0 63 74 69 6f 6e 20 4c 20 73 68 61 6c 6c 20 61 6c ction L shall al
2efe0 77 61 79 73 20 62 65 20 69 6e 76 6f 6b 65 64 20 ways be invoked
2eff0 65 78 61 63 74 6c 79 20 6f 6e 63 65 20 69 66 20 exactly once if
2f000 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
2f010 73 74 65 70 20 66 75 6e 63 74 69 6f 6e 20 53 20 step function S
2f020 69 73 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 is called one or
2f030 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 0a more times..**.
2f040 2a 2a 20 7b 48 31 36 31 34 32 7d 20 57 68 65 6e ** {H16142} When
2f050 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 SQLite invokes
2f060 65 69 74 68 65 72 20 74 68 65 20 78 46 75 6e 63 either the xFunc
2f070 20 6f 72 20 78 53 74 65 70 20 66 75 6e 63 74 69 or xStep functi
2f080 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 on of.**
2f090 20 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e an application
2f0a0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
2f0b0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 ction or aggrega
2f0c0 74 65 20 63 72 65 61 74 65 64 0a 2a 2a 20 20 20 te created.**
2f0d0 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 by [sqlit
2f0e0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
2f0f0 6f 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 on()] or [sqlite
2f100 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
2f110 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 n16()],.**
2f120 20 20 20 20 74 68 65 6e 20 74 68 65 20 61 72 72 then the arr
2f130 61 79 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 ay of [sqlite3_v
2f140 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 20 70 61 alue] objects pa
2f150 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 20 ssed as the.**
2f160 20 20 20 20 20 20 20 20 74 68 69 72 64 20 70 61 third pa
2f170 72 61 6d 65 74 65 72 20 73 68 61 6c 6c 20 62 65 rameter shall be
2f180 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 [protected sqli
2f190 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
2f1a0 74 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ts..*/.int sqlit
2f1b0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
2f1c0 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 on(. sqlite3 *d
2f1d0 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 b,. const char
2f1e0 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a *zFunctionName,.
2f1f0 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e int nArg,. in
2f200 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f t eTextRep,. vo
2f210 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 id *pApp,. void
2f220 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 (*xFunc)(sqlite
2f230 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 3_context*,int,s
2f240 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c qlite3_value**),
2f250 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 . void (*xStep)
2f260 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
2f270 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
2f280 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
2f290 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 *xFinal)(sqlite3
2f2a0 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e _context*).);.in
2f2b0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
2f2c0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 _function16(. s
2f2d0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f qlite3 *db,. co
2f2e0 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 nst void *zFunct
2f2f0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e ionName,. int n
2f300 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 Arg,. int eText
2f310 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 Rep,. void *pAp
2f320 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e p,. void (*xFun
2f330 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 c)(sqlite3_conte
2f340 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f xt*,int,sqlite3_
2f350 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 value**),. void
2f360 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 (*xStep)(sqlite
2f370 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 3_context*,int,s
2f380 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c qlite3_value**),
2f390 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c . void (*xFinal
2f3a0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 )(sqlite3_contex
2f3b0 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 t*).);../*.** CA
2f3c0 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 PI3REF: Text Enc
2f3d0 6f 64 69 6e 67 73 20 7b 48 31 30 32 36 37 7d 20 odings {H10267}
2f3e0 3c 53 35 30 32 30 30 3e 20 3c 48 31 36 31 30 30 <S50200> <H16100
2f3f0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f >.**.** These co
2f400 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e nstant define in
2f410 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 teger codes that
2f420 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 represent the v
2f430 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 arious.** text e
2f440 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 ncodings support
2f450 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f ed by SQLite..*/
2f460 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2f470 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 UTF8 1
2f480 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2f490 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 UTF16LE 2
2f4a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2f4b0 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 UTF16BE 3
2f4c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2f4d0 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 UTF16 4
2f4e0 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 /* Use nativ
2f4f0 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a e byte order */.
2f500 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
2f510 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 NY 5
2f520 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 /* sqlite3_cr
2f530 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e eate_function on
2f540 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ly */.#define SQ
2f550 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e LITE_UTF16_ALIGN
2f560 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 ED 8 /* sqli
2f570 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
2f580 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a tion only */../*
2f590 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
2f5a0 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f precated Functio
2f5b0 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 ns.** DEPRECATED
2f5c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e .**.** These fun
2f5d0 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 ctions are [depr
2f5e0 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 ecated]. In ord
2f5f0 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a er to maintain.*
2f600 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 * backwards comp
2f610 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f atibility with o
2f620 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 lder code, these
2f630 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 functions conti
2f640 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 nue .** to be su
2f650 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 pported. Howeve
2f660 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 r, new applicati
2f670 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 ons should avoid
2f680 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 .** the use of t
2f690 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 hese functions.
2f6a0 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 To help encoura
2f6b0 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f ge people to avo
2f6c0 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 id.** using thes
2f6d0 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 e functions, we
2f6e0 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f are not going to
2f6f0 20 74 65 6c 6c 20 79 6f 75 20 77 61 6e 74 20 74 tell you want t
2f700 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 hey do..*/.#ifnd
2f710 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 ef SQLITE_OMIT_D
2f720 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 EPRECATED.SQLITE
2f730 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 _DEPRECATED int
2f740 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
2f750 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f e_count(sqlite3_
2f760 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 context*);.SQLIT
2f770 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 E_DEPRECATED int
2f780 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 sqlite3_expired
2f790 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b (sqlite3_stmt*);
2f7a0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 .SQLITE_DEPRECAT
2f7b0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 ED int sqlite3_t
2f7c0 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 ransfer_bindings
2f7d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
2f7e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a sqlite3_stmt*);.
2f7f0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 SQLITE_DEPRECATE
2f800 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c D int sqlite3_gl
2f810 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 obal_recover(voi
2f820 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 d);.SQLITE_DEPRE
2f830 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 CATED void sqlit
2f840 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 e3_thread_cleanu
2f850 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f p(void);.SQLITE_
2f860 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 DEPRECATED int s
2f870 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c qlite3_memory_al
2f880 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 arm(void(*)(void
2f890 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c *,sqlite3_int64,
2f8a0 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 int),void*,sqlit
2f8b0 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 e3_int64);.#endi
2f8c0 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 f../*.** CAPI3RE
2f8d0 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c F: Obtaining SQL
2f8e0 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 Function Parame
2f8f0 74 65 72 20 56 61 6c 75 65 73 20 7b 48 31 35 31 ter Values {H151
2f900 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 00} <S20200>.**.
2f910 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 ** The C-languag
2f920 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
2f930 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e of SQL function
2f940 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 s and aggregates
2f950 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 uses.** this se
2f960 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 t of interface r
2f970 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 outines to acces
2f980 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 s the parameter
2f990 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 values on.** the
2f9a0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 function or agg
2f9b0 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 regate..**.** Th
2f9c0 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 e xFunc (for sca
2f9d0 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f lar functions) o
2f9e0 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 r xStep (for agg
2f9f0 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 regates) paramet
2fa00 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 ers.** to [sqlit
2fa10 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
2fa20 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 on()] and [sqlit
2fa30 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
2fa40 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e on16()].** defin
2fa50 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 e callbacks that
2fa60 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 implement the S
2fa70 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 QL functions and
2fa80 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 aggregates..**
2fa90 54 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 The 4th paramete
2faa0 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 r to these callb
2fab0 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 acks is an array
2fac0 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a of pointers to.
2fad0 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 ** [protected sq
2fae0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
2faf0 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 ects. There is
2fb00 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c one [sqlite3_val
2fb10 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a ue] object for.*
2fb20 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 * each parameter
2fb30 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 to the SQL func
2fb40 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 tion. These rou
2fb50 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 tines are used t
2fb60 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c o.** extract val
2fb70 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 ues from the [sq
2fb80 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
2fb90 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ects..**.** Thes
2fba0 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 e routines work
2fbb0 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 only with [prote
2fbc0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
2fbd0 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 ue] objects..**
2fbe0 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 Any attempt to u
2fbf0 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 se these routine
2fc00 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 s on an [unprote
2fc10 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
2fc20 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 ue].** object re
2fc30 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e sults in undefin
2fc40 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a ed behavior..**.
2fc50 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
2fc60 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 s work just like
2fc70 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 the correspondi
2fc80 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 ng [column acces
2fc90 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 s functions].**
2fca0 65 78 63 65 70 74 20 74 68 61 74 20 20 74 68 65 except that the
2fcb0 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 se routines take
2fcc0 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 a single [prote
2fcd0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
2fce0 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f ue] object.** po
2fcf0 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 inter instead of
2fd00 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 a [sqlite3_stmt
2fd10 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 *] pointer and a
2fd20 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e n integer column
2fd30 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 number..**.** T
2fd40 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 he sqlite3_value
2fd50 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 _text16() interf
2fd60 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55 ace extracts a U
2fd70 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 TF-16 string.**
2fd80 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 in the native by
2fd90 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 te-order of the
2fda0 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 54 host machine. T
2fdb0 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 he.** sqlite3_va
2fdc0 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 lue_text16be() a
2fdd0 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nd sqlite3_value
2fde0 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 _text16le() inte
2fdf0 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 rfaces.** extrac
2fe00 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 t UTF-16 strings
2fe10 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 as big-endian a
2fe20 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e nd little-endian
2fe30 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a respectively..*
2fe40 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
2fe50 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 _value_numeric_t
2fe60 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 ype() interface
2fe70 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c attempts to appl
2fe80 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 y.** numeric aff
2fe90 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c inity to the val
2fea0 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 ue. This means
2feb0 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 that an attempt
2fec0 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f is.** made to co
2fed0 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 nvert the value
2fee0 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 to an integer or
2fef0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e floating point.
2ff00 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 If.** such a c
2ff10 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 onversion is pos
2ff20 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f sible without lo
2ff30 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f ss of informatio
2ff40 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 n (in other.** w
2ff50 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c ords, if the val
2ff60 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 ue is a string t
2ff70 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 hat looks like a
2ff80 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e number).** then
2ff90 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 the conversion
2ffa0 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f is performed. O
2ffb0 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 therwise no conv
2ffc0 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a ersion occurs..*
2ffd0 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e * The [SQLITE_IN
2ffe0 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 TEGER | datatype
2fff0 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 ] after conversi
30000 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a on is returned..
30010 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 **.** Please pay
30020 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 particular atte
30030 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 ntion to the fac
30040 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 t that the point
30050 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 er returned.** f
30060 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c rom [sqlite3_val
30070 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c ue_blob()], [sql
30080 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 ite3_value_text(
30090 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 )], or.** [sqlit
300a0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 e3_value_text16(
300b0 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 )] can be invali
300c0 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65 dated by a subse
300d0 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a quent call to.**
300e0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
300f0 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 bytes()], [sqlit
30100 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 e3_value_bytes16
30110 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 ()], [sqlite3_va
30120 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 lue_text()],.**
30130 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 or [sqlite3_valu
30140 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a e_text16()]..**.
30150 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
30160 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 s must be called
30170 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 from the same t
30180 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 hread as.** the
30190 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 SQL function tha
301a0 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b t supplied the [
301b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 sqlite3_value*]
301c0 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a parameters..**.*
301d0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
301e0 0a 2a 2a 20 7b 48 31 35 31 30 33 7d 20 54 68 65 .** {H15103} The
301f0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
30200 62 6c 6f 62 28 56 29 5d 20 69 6e 74 65 72 66 61 blob(V)] interfa
30210 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a ce converts the.
30220 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f ** [pro
30230 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
30240 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 alue] object V i
30250 6e 74 6f 20 61 20 42 4c 4f 42 20 61 6e 64 20 74 nto a BLOB and t
30260 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 hen.**
30270 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
30280 72 20 74 6f 20 74 68 65 20 63 6f 6e 76 65 72 74 r to the convert
30290 65 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 ed value..**.**
302a0 7b 48 31 35 31 30 36 7d 20 54 68 65 20 5b 73 71 {H15106} The [sq
302b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 lite3_value_byte
302c0 73 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 s(V)] interface
302d0 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 returns the.**
302e0 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f number o
302f0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 42 f bytes in the B
30300 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 28 65 LOB or string (e
30310 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a xclusive of the.
30320 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f ** zero
30330 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 terminator on t
30340 68 65 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 he string) that
30350 77 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 was returned by
30360 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
30370 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c most recent call
30380 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c to [sqlite3_val
30390 75 65 5f 62 6c 6f 62 28 56 29 5d 20 6f 72 0a 2a ue_blob(V)] or.*
303a0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
303b0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 56 te3_value_text(V
303c0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 )]..**.** {H1510
303d0 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 9} The [sqlite3_
303e0 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 56 29 value_bytes16(V)
303f0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ] interface retu
30400 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 rns the.**
30410 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 number of by
30420 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e tes in the strin
30430 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 g (exclusive of
30440 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
30450 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 zero terminator
30460 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 on the string) t
30470 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 hat was returned
30480 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 by the.**
30490 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 most recent
304a0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
304b0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 56 29 _value_text16(V)
304c0 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b ],.** [
304d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
304e0 78 74 31 36 62 65 28 56 29 5d 2c 20 6f 72 20 5b xt16be(V)], or [
304f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
30500 78 74 31 36 6c 65 28 56 29 5d 2e 0a 2a 2a 0a 2a xt16le(V)]..**.*
30510 2a 20 7b 48 31 35 31 31 32 7d 20 54 68 65 20 5b * {H15112} The [
30520 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f sqlite3_value_do
30530 75 62 6c 65 28 56 29 5d 20 69 6e 74 65 72 66 61 uble(V)] interfa
30540 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a ce converts the.
30550 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f ** [pro
30560 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
30570 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 alue] object V i
30580 6e 74 6f 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 nto a floating p
30590 6f 69 6e 74 20 76 61 6c 75 65 20 61 6e 64 0a 2a oint value and.*
305a0 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 * retur
305b0 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 ns a copy of tha
305c0 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b t value..**.** {
305d0 48 31 35 31 31 35 7d 20 54 68 65 20 5b 73 71 6c H15115} The [sql
305e0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 56 ite3_value_int(V
305f0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e )] interface con
30600 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 verts the.**
30610 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 [protected
30620 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
30630 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 object V into a
30640 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 64-bit signed in
30650 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 teger and.**
30660 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 74 68 returns th
30670 65 20 6c 6f 77 65 72 20 33 32 20 62 69 74 73 20 e lower 32 bits
30680 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e of that integer.
30690 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31 38 7d 20 .**.** {H15118}
306a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c The [sqlite3_val
306b0 75 65 5f 69 6e 74 36 34 28 56 29 5d 20 69 6e 74 ue_int64(V)] int
306c0 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 erface converts
306d0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
306e0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 [protected sqlit
306f0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
30700 20 56 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 V into a 64-bit
30710 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 signed integer
30720 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 and.**
30730 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f returns a copy o
30740 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a f that integer..
30750 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32 31 7d 20 54 **.** {H15121} T
30760 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 he [sqlite3_valu
30770 65 5f 74 65 78 74 28 56 29 5d 20 69 6e 74 65 72 e_text(V)] inter
30780 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 face converts th
30790 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 e.** [p
307a0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
307b0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 _value] object V
307c0 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 into a zero-ter
307d0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a minated UTF-8.**
307e0 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 string
307f0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 and returns a p
30800 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 ointer to that s
30810 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 tring..**.** {H1
30820 35 31 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 5124} The [sqlit
30830 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 e3_value_text16(
30840 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f V)] interface co
30850 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 nverts the.**
30860 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 [protecte
30870 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
30880 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 object V into a
30890 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
308a0 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 2-byte.**
308b0 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d aligned UTF-
308c0 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 16 native byte o
308d0 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 rder.**
308e0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 string and retu
308f0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
30900 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a that string..**
30910 0a 2a 2a 20 7b 48 31 35 31 32 37 7d 20 54 68 65 .** {H15127} The
30920 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
30930 74 65 78 74 31 36 62 65 28 56 29 5d 20 69 6e 74 text16be(V)] int
30940 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 erface converts
30950 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
30960 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 [protected sqlit
30970 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
30980 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 V into a zero-t
30990 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 erminated 2-byte
309a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 .** ali
309b0 67 6e 65 64 20 55 54 46 2d 31 36 20 62 69 67 2d gned UTF-16 big-
309c0 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 endian.**
309d0 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 string and re
309e0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
309f0 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a to that string..
30a00 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33 30 7d 20 54 **.** {H15130} T
30a10 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 he [sqlite3_valu
30a20 65 5f 74 65 78 74 31 36 6c 65 28 56 29 5d 20 69 e_text16le(V)] i
30a30 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 nterface convert
30a40 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 s the.**
30a50 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c [protected sql
30a60 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
30a70 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f ct V into a zero
30a80 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 -terminated 2-by
30a90 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 te.** a
30aa0 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6c 69 ligned UTF-16 li
30ab0 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 ttle-endian.**
30ac0 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 string a
30ad0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 nd returns a poi
30ae0 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 nter to that str
30af0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 ing..**.** {H151
30b00 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 33} The [sqlite3
30b10 5f 76 61 6c 75 65 5f 74 79 70 65 28 56 29 5d 20 _value_type(V)]
30b20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
30b30 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e s.** on
30b40 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c e of [SQLITE_NUL
30b50 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 L], [SQLITE_INTE
30b60 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c GER], [SQLITE_FL
30b70 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 OAT],.**
30b80 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c [SQLITE_TEXT],
30b90 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 or [SQLITE_BLOB
30ba0 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61 74 65 ] as appropriate
30bb0 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 for.**
30bc0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 the [sqlite3_va
30bd0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 2e 0a 2a lue] object V..*
30be0 2a 0a 2a 2a 20 7b 48 31 35 31 33 36 7d 20 54 68 *.** {H15136} Th
30bf0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 e [sqlite3_value
30c00 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 56 29 _numeric_type(V)
30c10 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 ] interface conv
30c20 65 72 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 erts.**
30c30 20 74 68 65 20 5b 70 72 6f 74 65 63 74 65 64 20 the [protected
30c40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
30c50 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 65 69 74 bject V into eit
30c60 68 65 72 20 61 6e 20 69 6e 74 65 67 65 72 20 6f her an integer o
30c70 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 r.** a
30c80 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 floating point v
30c90 61 6c 75 65 20 69 66 20 69 74 20 63 61 6e 20 64 alue if it can d
30ca0 6f 20 73 6f 20 77 69 74 68 6f 75 74 20 6c 6f 73 o so without los
30cb0 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 s of.**
30cc0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20 61 6e information, an
30cd0 64 20 72 65 74 75 72 6e 73 20 6f 6e 65 20 6f 66 d returns one of
30ce0 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 0a [SQLITE_NULL],.
30cf0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c ** [SQL
30d00 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 ITE_INTEGER], [S
30d10 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 QLITE_FLOAT], [S
30d20 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 0a QLITE_TEXT], or.
30d30 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c ** [SQL
30d40 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 ITE_BLOB] as app
30d50 72 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 ropriate for the
30d60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 .** [pr
30d70 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
30d80 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 value] object V
30d90 61 66 74 65 72 20 74 68 65 20 63 6f 6e 76 65 72 after the conver
30da0 73 69 6f 6e 20 61 74 74 65 6d 70 74 2e 0a 2a 2f sion attempt..*/
30db0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
30dc0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 ite3_value_blob(
30dd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
30de0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c .int sqlite3_val
30df0 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 ue_bytes(sqlite3
30e00 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 _value*);.int sq
30e10 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 lite3_value_byte
30e20 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 s16(sqlite3_valu
30e30 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 e*);.double sqli
30e40 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 te3_value_double
30e50 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
30e60 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 ;.int sqlite3_va
30e70 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f lue_int(sqlite3_
30e80 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 value*);.sqlite3
30e90 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 _int64 sqlite3_v
30ea0 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 alue_int64(sqlit
30eb0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 e3_value*);.cons
30ec0 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 t unsigned char
30ed0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 *sqlite3_value_t
30ee0 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 ext(sqlite3_valu
30ef0 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 e*);.const void
30f00 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 *sqlite3_value_t
30f10 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 ext16(sqlite3_va
30f20 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 lue*);.const voi
30f30 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 d *sqlite3_value
30f40 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 _text16le(sqlite
30f50 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 3_value*);.const
30f60 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 void *sqlite3_v
30f70 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 alue_text16be(sq
30f80 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 lite3_value*);.i
30f90 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt sqlite3_value
30fa0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 _type(sqlite3_va
30fb0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 lue*);.int sqlit
30fc0 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 e3_value_numeric
30fd0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 _type(sqlite3_va
30fe0 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 lue*);../*.** CA
30ff0 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 PI3REF: Obtain A
31000 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f ggregate Functio
31010 6e 20 43 6f 6e 74 65 78 74 20 7b 48 31 36 32 31 n Context {H1621
31020 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 0} <S20200>.**.*
31030 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 * The implementa
31040 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 67 61 74 tion of aggregat
31050 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 e SQL functions
31060 75 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 use this routine
31070 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20 to allocate.**
31080 61 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 a structure for
31090 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 storing their st
310a0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 ate..**.** The f
310b0 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 irst time the sq
310c0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
310d0 63 6f 6e 74 65 78 74 28 29 20 72 6f 75 74 69 6e context() routin
310e0 65 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 e is called for
310f0 61 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 a.** particular
31100 61 67 67 72 65 67 61 74 65 2c 20 53 51 4c 69 74 aggregate, SQLit
31110 65 20 61 6c 6c 6f 63 61 74 65 73 20 6e 42 79 74 e allocates nByt
31120 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 es of memory, ze
31130 72 6f 65 73 20 6f 75 74 20 74 68 61 74 0a 2a 2a roes out that.**
31140 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 memory, and ret
31150 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
31160 6f 20 69 74 2e 20 4f 6e 20 73 65 63 6f 6e 64 20 o it. On second
31170 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 and subsequent c
31180 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 alls to.** sqlit
31190 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
311a0 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 text() for the s
311b0 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 ame aggregate fu
311c0 6e 63 74 69 6f 6e 20 69 6e 64 65 78 2c 0a 2a 2a nction index,.**
311d0 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 the same buffer
311e0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 54 68 is returned. Th
311f0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
31200 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 of the aggregat
31210 65 20 63 61 6e 20 75 73 65 0a 2a 2a 20 74 68 65 e can use.** the
31220 20 72 65 74 75 72 6e 65 64 20 62 75 66 66 65 72 returned buffer
31230 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 65 20 64 to accumulate d
31240 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 ata..**.** SQLit
31250 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 e automatically
31260 66 72 65 65 73 20 74 68 65 20 61 6c 6c 6f 63 61 frees the alloca
31270 74 65 64 20 62 75 66 66 65 72 20 77 68 65 6e 20 ted buffer when
31280 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a the aggregate.**
31290 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 query concludes
312a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 ..**.** The firs
312b0 74 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 t parameter shou
312c0 6c 64 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 ld be a copy of
312d0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
312e0 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 context | SQL fu
312f0 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 nction context]
31300 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73 that is the firs
31310 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 t parameter.** t
31320 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 o the callback r
31330 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c outine that impl
31340 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 ements the aggre
31350 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a gate function..*
31360 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
31370 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 e must be called
31380 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 from the same t
31390 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a hread in which.*
313a0 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 * the aggregate
313b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 SQL function is
313c0 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 running..**.** I
313d0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
313e0 20 7b 48 31 36 32 31 31 7d 20 54 68 65 20 66 69 {H16211} The fi
313f0 72 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f rst invocation o
31400 66 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 f [sqlite3_aggre
31410 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e gate_context(C,N
31420 29 5d 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 )] for.**
31430 20 20 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 a particular
31440 69 6e 73 74 61 6e 63 65 20 6f 66 20 61 6e 20 61 instance of an a
31450 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f ggregate functio
31460 6e 20 28 66 6f 72 20 61 20 70 61 72 74 69 63 75 n (for a particu
31470 6c 61 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 lar.**
31480 63 6f 6e 74 65 78 74 20 43 29 20 63 61 75 73 65 context C) cause
31490 73 20 53 51 4c 69 74 65 20 74 6f 20 61 6c 6c 6f s SQLite to allo
314a0 63 61 74 65 20 4e 20 62 79 74 65 73 20 6f 66 20 cate N bytes of
314b0 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 20 20 20 20 20 memory,.**
314c0 20 20 20 20 7a 65 72 6f 20 74 68 61 74 20 6d 65 zero that me
314d0 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e mory, and return
314e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
314f0 65 20 61 6c 6c 6f 63 61 74 65 64 20 6d 65 6d 6f e allocated memo
31500 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 ry..**.** {H1621
31510 33 7d 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 3} If a memory a
31520 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 llocation error
31530 6f 63 63 75 72 73 20 64 75 72 69 6e 67 0a 2a 2a occurs during.**
31540 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
31550 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
31560 74 65 78 74 28 43 2c 4e 29 5d 20 74 68 65 6e 20 text(C,N)] then
31570 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 the function ret
31580 75 72 6e 73 20 30 2e 0a 2a 2a 0a 2a 2a 20 7b 48 urns 0..**.** {H
31590 31 36 32 31 35 7d 20 53 65 63 6f 6e 64 20 61 6e 16215} Second an
315a0 64 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 d subsequent inv
315b0 6f 63 61 74 69 6f 6e 73 20 6f 66 0a 2a 2a 20 20 ocations of.**
315c0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
315d0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
315e0 78 74 28 43 2c 4e 29 5d 20 66 6f 72 20 74 68 65 xt(C,N)] for the
315f0 20 73 61 6d 65 20 63 6f 6e 74 65 78 74 20 70 6f same context po
31600 69 6e 74 65 72 20 43 0a 2a 2a 20 20 20 20 20 20 inter C.**
31610 20 20 20 20 69 67 6e 6f 72 65 20 74 68 65 20 4e ignore the N
31620 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 parameter and r
31630 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 eturn a pointer
31640 74 6f 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 to the same.**
31650 20 20 20 20 20 20 20 20 62 6c 6f 63 6b 20 6f 66 block of
31660 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 memory returned
31670 20 62 79 20 74 68 65 20 66 69 72 73 74 20 69 6e by the first in
31680 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 vocation..**.**
31690 7b 48 31 36 32 31 37 7d 20 54 68 65 20 6d 65 6d {H16217} The mem
316a0 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 ory allocated by
316b0 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 [sqlite3_aggreg
316c0 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 ate_context(C,N)
316d0 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 ] is.**
316e0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 automatically f
316f0 72 65 65 64 20 6f 6e 20 74 68 65 20 6e 65 78 74 reed on the next
31700 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
31710 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 20 20 3_reset()].**
31720 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 or [sqlit
31730 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 66 e3_finalize()] f
31740 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 or the [prepared
31750 20 73 74 61 74 65 6d 65 6e 74 5d 20 63 6f 6e 74 statement] cont
31760 61 69 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 aining.**
31770 20 20 20 74 68 65 20 61 67 67 72 65 67 61 74 65 the aggregate
31780 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 function associ
31790 61 74 65 64 20 77 69 74 68 20 63 6f 6e 74 65 78 ated with contex
317a0 74 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 t C..*/.void *sq
317b0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
317c0 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f context(sqlite3_
317d0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 context*, int nB
317e0 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ytes);../*.** CA
317f0 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 PI3REF: User Dat
31800 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 a For Functions
31810 7b 48 31 36 32 34 30 7d 20 3c 53 32 30 32 30 30 {H16240} <S20200
31820 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 >.**.** The sqli
31830 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 te3_user_data()
31840 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
31850 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 s a copy of.** t
31860 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 he pointer that
31870 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74 was the pUserDat
31880 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 a parameter (the
31890 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 5th parameter).
318a0 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ** of the [sqlit
318b0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
318c0 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 on()].** and [sq
318d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
318e0 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 ction16()] routi
318f0 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 nes that origina
31900 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 lly.** registere
31910 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f d the applicatio
31920 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n defined functi
31930 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 on. {END}.**.**
31940 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 This routine mus
31950 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d t be called from
31960 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 the same thread
31970 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 in which.** the
31980 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
31990 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 ined function is
319a0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 running..**.**
319b0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
319c0 2a 20 7b 48 31 36 32 34 33 7d 20 54 68 65 20 5b * {H16243} The [
319d0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 sqlite3_user_dat
319e0 61 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 a(C)] interface
319f0 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f returns a copy o
31a00 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 f the.**
31a10 20 20 50 20 70 6f 69 6e 74 65 72 20 66 72 6f 6d P pointer from
31a20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 the [sqlite3_cr
31a30 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c eate_function(D,
31a40 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a X,N,E,P,F,S,L)].
31a50 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b ** or [
31a60 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
31a70 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c unction16(D,X,N,
31a80 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c E,P,F,S,L)] call
31a90 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 that.**
31aa0 20 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 registered the
31ab0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73 SQL function as
31ac0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 5b 73 sociated with [s
31ad0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 qlite3_context]
31ae0 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 C..*/.void *sqli
31af0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 te3_user_data(sq
31b00 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b lite3_context*);
31b10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
31b20 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 : Database Conne
31b30 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 ction For Functi
31b40 6f 6e 73 20 7b 48 31 36 32 35 30 7d 20 3c 53 36 ons {H16250} <S6
31b50 30 36 30 30 3e 3c 53 32 30 32 30 30 3e 0a 2a 2a 0600><S20200>.**
31b60 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
31b70 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c context_db_handl
31b80 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 e() interface re
31b90 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a turns a copy of.
31ba0 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 ** the pointer t
31bb0 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 o the [database
31bc0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 connection] (the
31bd0 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 1st parameter).
31be0 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ** of the [sqlit
31bf0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
31c00 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 on()].** and [sq
31c10 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
31c20 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 ction16()] routi
31c30 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 nes that origina
31c40 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 lly.** registere
31c50 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f d the applicatio
31c60 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n defined functi
31c70 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 on..**.** INVARI
31c80 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 ANTS:.**.** {H16
31c90 32 35 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 253} The [sqlite
31ca0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 3_context_db_han
31cb0 64 6c 65 28 43 29 5d 20 69 6e 74 65 72 66 61 63 dle(C)] interfac
31cc0 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 e returns a copy
31cd0 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 of the.**
31ce0 20 20 20 20 44 20 70 6f 69 6e 74 65 72 20 66 72 D pointer fr
31cf0 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f om the [sqlite3_
31d00 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
31d10 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 D,X,N,E,P,F,S,L)
31d20 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 ].** or
31d30 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
31d40 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c _function16(D,X,
31d50 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 N,E,P,F,S,L)] ca
31d60 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 ll that.**
31d70 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20 74 registered t
31d80 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 he SQL function
31d90 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
31da0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 [sqlite3_context
31db0 5d 20 43 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 ] C..*/.sqlite3
31dc0 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 *sqlite3_context
31dd0 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 _db_handle(sqlit
31de0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f e3_context*);../
31df0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
31e00 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 unction Auxiliar
31e10 79 20 44 61 74 61 20 7b 48 31 36 32 37 30 7d 20 y Data {H16270}
31e20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S20200>.**.** T
31e30 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f he following two
31e40 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 functions may b
31e50 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61 72 e used by scalar
31e60 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 SQL functions t
31e70 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d o.** associate m
31e80 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67 etadata with arg
31e90 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 ument values. If
31ea0 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 the same value
31eb0 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 is passed to.**
31ec0 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 multiple invocat
31ed0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 ions of the same
31ee0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 SQL function du
31ef0 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 ring query execu
31f00 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 tion, under.** s
31f10 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 ome circumstance
31f20 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 s the associated
31f30 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 metadata may be
31f40 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 73 preserved. This
31f50 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c may.** be used,
31f60 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f for example, to
31f70 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65 add a regular-e
31f80 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 xpression matchi
31f90 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e ng scalar.** fun
31fa0 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 ction. The compi
31fb0 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 led version of t
31fc0 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 he regular expre
31fd0 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 ssion is stored
31fe0 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 as.** metadata a
31ff0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
32000 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73 he SQL value pas
32010 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75 6c sed as the regul
32020 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a ar expression.**
32030 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63 pattern. The c
32040 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 ompiled regular
32050 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 expression can b
32060 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 e reused on mult
32070 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 iple.** invocati
32080 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 ons of the same
32090 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 function so that
320a0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 the original pa
320b0 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 ttern string.**
320c0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f does not need to
320d0 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f be recompiled o
320e0 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f n each invocatio
320f0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c n..**.** The sql
32100 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 ite3_get_auxdata
32110 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 () interface ret
32120 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
32130 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a o the metadata.*
32140 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 * associated by
32150 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f the sqlite3_set_
32160 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 auxdata() functi
32170 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 on with the Nth
32180 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 argument.** valu
32190 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 e to the applica
321a0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
321b0 63 74 69 6f 6e 2e 20 49 66 20 6e 6f 20 6d 65 74 ction. If no met
321c0 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 65 adata has been e
321d0 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20 ver.** been set
321e0 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67 75 for the Nth argu
321f0 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63 ment of the func
32200 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 tion, or if the
32210 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a corresponding.**
32220 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 function parame
32230 74 65 72 20 68 61 73 20 63 68 61 6e 67 65 64 20 ter has changed
32240 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64 since the meta-d
32250 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20 ata was set,.**
32260 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 then sqlite3_get
32270 5f 61 75 78 64 61 74 61 28 29 20 72 65 74 75 72 _auxdata() retur
32280 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ns a NULL pointe
32290 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c r..**.** The sql
322a0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 ite3_set_auxdata
322b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 () interface sav
322c0 65 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a es the metadata.
322d0 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 ** pointed to by
322e0 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 its 3rd paramet
322f0 65 72 20 61 73 20 74 68 65 20 6d 65 74 61 64 61 er as the metada
32300 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a ta for the N-th.
32310 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 ** argument of t
32320 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
32330 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e efined function.
32340 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 Subsequent.**
32350 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
32360 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d _get_auxdata() m
32370 69 67 68 74 20 72 65 74 75 72 6e 20 74 68 69 73 ight return this
32380 20 64 61 74 61 2c 20 69 66 20 69 74 20 68 61 73 data, if it has
32390 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 .** not been des
323a0 74 72 6f 79 65 64 2e 0a 2a 2a 20 49 66 20 69 74 troyed..** If it
323b0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 is not NULL, SQ
323c0 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 Lite will invoke
323d0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a the destructor.
323e0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 ** function give
323f0 6e 20 62 79 20 74 68 65 20 34 74 68 20 70 61 72 n by the 4th par
32400 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
32410 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 3_set_auxdata()
32420 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 on.** the metada
32430 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 ta when the corr
32440 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 esponding functi
32450 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 on parameter cha
32460 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 nges.** or when
32470 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
32480 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 t completes, whi
32490 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 chever comes fir
324a0 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 st..**.** SQLite
324b0 20 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c is free to call
324c0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 the destructor
324d0 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74 and drop metadat
324e0 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 a on any.** para
324f0 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e meter of any fun
32500 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d ction at any tim
32510 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20 67 75 61 e. The only gua
32520 72 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a rantee is that.*
32530 2a 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 * the destructor
32540 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 will be called
32550 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64 before the metad
32560 61 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a ata is dropped..
32570 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 74 69 63 **.** In practic
32580 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 e, metadata is p
32590 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e reserved between
325a0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 function calls
325b0 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f for.** expressio
325c0 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 ns that are cons
325d0 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 tant at compile
325e0 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 time. This inclu
325f0 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 des literal.** v
32600 61 6c 75 65 73 20 61 6e 64 20 53 51 4c 20 76 61 alues and SQL va
32610 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 riables..**.** T
32620 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 hese routines mu
32630 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f st be called fro
32640 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 m the same threa
32650 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 d in which.** th
32660 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 e SQL function i
32670 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a s running..**.**
32680 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
32690 2a 2a 20 7b 48 31 36 32 37 32 7d 20 54 68 65 20 ** {H16272} The
326a0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 [sqlite3_get_aux
326b0 64 61 74 61 28 43 2c 4e 29 5d 20 69 6e 74 65 72 data(C,N)] inter
326c0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 face returns a p
326d0 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 ointer.**
326e0 20 20 20 74 6f 20 6d 65 74 61 64 61 74 61 20 61 to metadata a
326f0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
32700 68 65 20 4e 74 68 20 70 61 72 61 6d 65 74 65 72 he Nth parameter
32710 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 of the SQL func
32720 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 tion.**
32730 20 77 68 6f 73 65 20 63 6f 6e 74 65 78 74 20 69 whose context i
32740 73 20 43 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 s C, or NULL if
32750 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 there is no meta
32760 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 0a data associated.
32770 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68 ** with
32780 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 2e that parameter.
32790 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 34 7d 20 .**.** {H16274}
327a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 The [sqlite3_set
327b0 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 _auxdata(C,N,P,D
327c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 73 73 )] interface ass
327d0 69 67 6e 73 20 61 20 6d 65 74 61 64 61 74 61 0a igns a metadata.
327e0 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e ** poin
327f0 74 65 72 20 50 20 74 6f 20 74 68 65 20 4e 74 68 ter P to the Nth
32800 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 parameter of th
32810 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 77 e SQL function w
32820 69 74 68 20 63 6f 6e 74 65 78 74 20 43 2e 0a 2a ith context C..*
32830 2a 0a 2a 2a 20 7b 48 31 36 32 37 36 7d 20 53 51 *.** {H16276} SQ
32840 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 Lite will invoke
32850 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 the destructor
32860 44 20 77 69 74 68 20 61 20 73 69 6e 67 6c 65 20 D with a single
32870 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 argument.**
32880 20 20 20 20 20 77 68 69 63 68 20 69 73 20 74 68 which is th
32890 65 20 6d 65 74 61 64 61 74 61 20 70 6f 69 6e 74 e metadata point
328a0 65 72 20 50 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 er P following a
328b0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 call to.**
328c0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 [sqlite3_se
328d0 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c t_auxdata(C,N,P,
328e0 44 29 5d 20 77 68 65 6e 20 53 51 4c 69 74 65 20 D)] when SQLite
328f0 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64 0a 2a ceases to hold.*
32900 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6d * the m
32910 65 74 61 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b etadata..**.** {
32920 48 31 36 32 37 37 7d 20 53 51 4c 69 74 65 20 63 H16277} SQLite c
32930 65 61 73 65 73 20 74 6f 20 68 6f 6c 64 20 6d 65 eases to hold me
32940 74 61 64 61 74 61 20 66 6f 72 20 61 6e 20 53 51 tadata for an SQ
32950 4c 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d L function param
32960 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 eter.**
32970 20 77 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 when the value
32980 6f 66 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 of that paramete
32990 72 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a r changes..**.**
329a0 20 7b 48 31 36 32 37 38 7d 20 57 68 65 6e 20 5b {H16278} When [
329b0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 sqlite3_set_auxd
329c0 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 69 73 ata(C,N,P,D)] is
329d0 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 64 65 invoked, the de
329e0 73 74 72 75 63 74 6f 72 0a 2a 2a 20 20 20 20 20 structor.**
329f0 20 20 20 20 20 69 73 20 63 61 6c 6c 65 64 20 66 is called f
32a00 6f 72 20 61 6e 79 20 70 72 69 6f 72 20 6d 65 74 or any prior met
32a10 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 adata associated
32a20 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 with the same f
32a30 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 unction.**
32a40 20 20 20 20 63 6f 6e 74 65 78 74 20 43 20 61 6e context C an
32a50 64 20 70 61 72 61 6d 65 74 65 72 20 4e 2e 0a 2a d parameter N..*
32a60 2a 0a 2a 2a 20 7b 48 31 36 32 37 39 7d 20 53 51 *.** {H16279} SQ
32a70 4c 69 74 65 20 77 69 6c 6c 20 63 61 6c 6c 20 64 Lite will call d
32a80 65 73 74 72 75 63 74 6f 72 73 20 66 6f 72 20 61 estructors for a
32a90 6e 79 20 6d 65 74 61 64 61 74 61 20 69 74 20 69 ny metadata it i
32aa0 73 20 68 6f 6c 64 69 6e 67 0a 2a 2a 20 20 20 20 s holding.**
32ab0 20 20 20 20 20 20 69 6e 20 61 20 70 61 72 74 69 in a parti
32ac0 63 75 6c 61 72 20 5b 70 72 65 70 61 72 65 64 20 cular [prepared
32ad0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 77 68 65 statement] S whe
32ae0 6e 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 n either.**
32af0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 [sqlite3_re
32b00 73 65 74 28 53 29 5d 20 6f 72 20 5b 73 71 6c 69 set(S)] or [sqli
32b10 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d te3_finalize(S)]
32b20 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a 2f 0a 76 is called..*/.v
32b30 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 oid *sqlite3_get
32b40 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 _auxdata(sqlite3
32b50 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e _context*, int N
32b60 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
32b70 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 set_auxdata(sqli
32b80 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
32b90 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 t N, void*, void
32ba0 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a (*)(void*));...
32bb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
32bc0 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 Constants Defini
32bd0 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 ng Special Destr
32be0 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 20 7b uctor Behavior {
32bf0 48 31 30 32 38 30 7d 20 3c 53 33 30 31 30 30 3e H10280} <S30100>
32c00 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 .**.** These are
32c10 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 special values
32c20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74 for the destruct
32c30 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 or that is passe
32c40 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 d in as the.** f
32c50 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f inal argument to
32c60 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b routines like [
32c70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 sqlite3_result_b
32c80 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74 68 65 20 lob()]. If the
32c90 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 destructor.** ar
32ca0 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 gument is SQLITE
32cb0 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e _STATIC, it mean
32cc0 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 s that the conte
32cd0 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f nt pointer is co
32ce0 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 nstant.** and wi
32cf0 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e ll never change.
32d00 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 It does not ne
32d10 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 ed to be destroy
32d20 65 64 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 ed. The.** SQLI
32d30 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c TE_TRANSIENT val
32d40 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 ue means that th
32d50 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c e content will l
32d60 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a ikely change in.
32d70 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 ** the near futu
32d80 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 re and that SQLi
32d90 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 te should make i
32da0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 ts own private c
32db0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f opy of.** the co
32dc0 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 ntent before ret
32dd0 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 urning..**.** Th
32de0 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 e typedef is nec
32df0 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 essary to work a
32e00 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 round problems i
32e10 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b n certain.** C++
32e20 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 compilers. See
32e30 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a ticket #2191..*
32e40 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 /.typedef void (
32e50 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 *sqlite3_destruc
32e60 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 tor_type)(void*)
32e70 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ;.#define SQLITE
32e80 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73 _STATIC ((s
32e90 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f qlite3_destructo
32ea0 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e r_type)0).#defin
32eb0 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 e SQLITE_TRANSIE
32ec0 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 NT ((sqlite3_d
32ed0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d estructor_type)-
32ee0 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 1)../*.** CAPI3R
32ef0 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 EF: Setting The
32f00 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c Result Of An SQL
32f10 20 46 75 6e 63 74 69 6f 6e 20 7b 48 31 36 34 30 Function {H1640
32f20 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 0} <S20200>.**.*
32f30 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
32f40 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 are used by the
32f50 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c xFunc or xFinal
32f60 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a callbacks that.
32f70 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c ** implement SQL
32f80 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 functions and a
32f90 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a ggregates. See.
32fa0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 ** [sqlite3_crea
32fb0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 te_function()] a
32fc0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 nd [sqlite3_crea
32fd0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d te_function16()]
32fe0 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e .** for addition
32ff0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a al information..
33000 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 **.** These func
33010 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 tions work very
33020 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 much like the [p
33030 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 arameter binding
33040 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 ] family of.** f
33050 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f unctions used to
33060 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 bind values to
33070 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 host parameters
33080 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74 in prepared stat
33090 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 ements..** Refer
330a0 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 to the [SQL par
330b0 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 ameter] document
330c0 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 ation for additi
330d0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
330e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
330f0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 te3_result_blob(
33100 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 ) interface sets
33110 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d the result from
33120 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 .** an applicati
33130 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
33140 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c ion to be the BL
33150 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 OB whose content
33160 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 is pointed.** t
33170 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 o by the second
33180 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 parameter and wh
33190 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c ich is N bytes l
331a0 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 ong where N is t
331b0 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 he.** third para
331c0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 meter..**.** The
331d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
331e0 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 zeroblob() inter
331f0 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 faces set the re
33200 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 sult of.** the a
33210 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
33220 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ed function to b
33230 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e e a BLOB contain
33240 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 ing all zero.**
33250 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 bytes and N byte
33260 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 s in size, where
33270 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 N is the value
33280 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d of the 2nd param
33290 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 eter..**.** The
332a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 sqlite3_result_d
332b0 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 ouble() interfac
332c0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c e sets the resul
332d0 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 t from.** an app
332e0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
332f0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
33300 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 a floating point
33310 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 value specified
33320 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 .** by its 2nd a
33330 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 rgument..**.** T
33340 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
33350 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 t_error() and sq
33360 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
33370 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 or16() functions
33380 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d .** cause the im
33390 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 plemented SQL fu
333a0 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 nction to throw
333b0 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a an exception..**
333c0 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 SQLite uses the
333d0 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 string pointed
333e0 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 to by the.** 2nd
333f0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 parameter of sq
33400 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
33410 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f or() or sqlite3_
33420 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 result_error16()
33430 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 .** as the text
33440 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 of an error mess
33450 61 67 65 2e 20 20 53 51 4c 69 74 65 20 69 6e 74 age. SQLite int
33460 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f erprets the erro
33470 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 r.** message str
33480 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 ing from sqlite3
33490 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 _result_error()
334a0 61 73 20 55 54 46 2d 38 2e 20 53 51 4c 69 74 65 as UTF-8. SQLite
334b0 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 .** interprets t
334c0 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 he string from s
334d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
334e0 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 ror16() as UTF-1
334f0 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 6 in native.** b
33500 79 74 65 20 6f 72 64 65 72 2e 20 20 49 66 20 74 yte order. If t
33510 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
33520 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 er to sqlite3_re
33530 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 sult_error().**
33540 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c or sqlite3_resul
33550 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e t_error16() is n
33560 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c egative then SQL
33570 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 ite takes as the
33580 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 error.** messag
33590 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 e all text up th
335a0 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 rough the first
335b0 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a zero character..
335c0 2a 2a 20 49 66 20 74 68 65 20 74 68 69 72 64 20 ** If the third
335d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
335e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
335f0 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 r() or.** sqlite
33600 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 3_result_error16
33610 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 () is non-negati
33620 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 ve then SQLite t
33630 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a akes that many.*
33640 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 * bytes (not cha
33650 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 racters) from th
33660 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 e 2nd parameter
33670 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 as the error mes
33680 73 61 67 65 2e 0a 2a 2a 20 54 68 65 20 73 71 6c sage..** The sql
33690 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
336a0 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f r() and sqlite3_
336b0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 result_error16()
336c0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b .** routines mak
336d0 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 e a private copy
336e0 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 of the error me
336f0 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 ssage text befor
33700 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e e.** they return
33710 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 . Hence, the ca
33720 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 lling function c
33730 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 an deallocate or
33740 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 .** modify the t
33750 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72 ext after they r
33760 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 eturn without ha
33770 72 6d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 rm..** The sqlit
33780 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f e3_result_error_
33790 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 code() function
337a0 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f changes the erro
337b0 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e r code.** return
337c0 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 ed by SQLite as
337d0 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 a result of an e
337e0 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 rror in a functi
337f0 6f 6e 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c on. By default,
33800 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f .** the error co
33810 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 de is SQLITE_ERR
33820 4f 52 2e 20 20 41 20 73 75 62 73 65 71 75 65 6e OR. A subsequen
33830 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 t call to sqlite
33840 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 3_result_error()
33850 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 .** or sqlite3_r
33860 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 esult_error16()
33870 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 resets the error
33880 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f code to SQLITE_
33890 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ERROR..**.** The
338a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
338b0 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 toobig() interfa
338c0 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 ce causes SQLite
338d0 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 to throw an err
338e0 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 or.** indicating
338f0 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f that a string o
33900 72 20 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e r BLOB is to lon
33910 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a g to represent..
33920 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
33930 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 3_result_nomem()
33940 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 interface cause
33950 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f s SQLite to thro
33960 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e w an error.** in
33970 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 dicating that a
33980 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
33990 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 n failed..**.**
339a0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
339b0 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 lt_int() interfa
339c0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 ce sets the retu
339d0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 rn value.** of t
339e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
339f0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
33a00 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 to be the 32-bit
33a10 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a signed integer.
33a20 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 ** value given i
33a30 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 n the 2nd argume
33a40 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 nt..** The sqlit
33a50 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 e3_result_int64(
33a60 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 ) interface sets
33a70 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
33a80 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c e.** of the appl
33a90 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
33aa0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 function to be t
33ab0 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 he 64-bit signed
33ac0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 integer.** valu
33ad0 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 e given in the 2
33ae0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a nd argument..**.
33af0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 ** The sqlite3_r
33b00 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 esult_null() int
33b10 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 erface sets the
33b20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 return value.**
33b30 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 of the applicati
33b40 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
33b50 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a ion to be NULL..
33b60 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
33b70 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 3_result_text(),
33b80 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
33b90 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c text16(),.** sql
33ba0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
33bb0 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 16le(), and sqli
33bc0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 te3_result_text1
33bd0 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 6be() interfaces
33be0 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 .** set the retu
33bf0 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 rn value of the
33c00 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
33c10 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 ned function to
33c20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 be.** a text str
33c30 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 ing which is rep
33c40 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d resented as UTF-
33c50 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 8, UTF-16 native
33c60 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 byte order,.**
33c70 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e UTF-16 little en
33c80 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 dian, or UTF-16
33c90 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 big endian, resp
33ca0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 53 51 4c ectively..** SQL
33cb0 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 ite takes the te
33cc0 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 xt result from t
33cd0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 he application f
33ce0 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 rom.** the 2nd p
33cf0 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 arameter of the
33d00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
33d10 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e ext* interfaces.
33d20 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 .** If the 3rd p
33d30 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
33d40 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
33d50 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a ext* interfaces.
33d60 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 ** is negative,
33d70 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 then SQLite take
33d80 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 s result text fr
33d90 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d om the 2nd param
33da0 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 eter.** through
33db0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 the first zero c
33dc0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 haracter..** If
33dd0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 the 3rd paramete
33de0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 r to the sqlite3
33df0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e _result_text* in
33e00 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e terfaces.** is n
33e10 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 on-negative, the
33e20 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 n as many bytes
33e30 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 (not characters)
33e40 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 of the text.**
33e50 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 pointed to by th
33e60 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 e 2nd parameter
33e70 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 are taken as the
33e80 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
33e90 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e ined.** function
33ea0 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 result..** If t
33eb0 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 he 4th parameter
33ec0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
33ed0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 result_text* int
33ee0 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 erfaces.** or sq
33ef0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f lite3_result_blo
33f00 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 b is a non-NULL
33f10 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 pointer, then SQ
33f20 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a Lite calls that.
33f30 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 ** function as t
33f40 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e he destructor on
33f50 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f the text or BLO
33f60 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 B result when it
33f70 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 has.** finished
33f80 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 using that resu
33f90 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 lt..** If the 4t
33fa0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
33fb0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
33fc0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 t_text* interfac
33fd0 65 73 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 es or.** sqlite3
33fe0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 _result_blob is
33ff0 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 the special cons
34000 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 tant SQLITE_STAT
34010 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a IC, then SQLite.
34020 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 ** assumes that
34030 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 the text or BLOB
34040 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f result is in co
34050 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 nstant space and
34060 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 does not.** cop
34070 79 20 74 68 65 20 69 74 20 6f 72 20 63 61 6c 6c y the it or call
34080 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 77 68 a destructor wh
34090 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 en it has finish
340a0 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 ed using that re
340b0 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 sult..** If the
340c0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 4th parameter to
340d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 the sqlite3_res
340e0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 ult_text* interf
340f0 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 aces.** or sqlit
34100 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 e3_result_blob i
34110 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f s the special co
34120 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 nstant SQLITE_TR
34130 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 ANSIENT.** then
34140 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 SQLite makes a c
34150 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c opy of the resul
34160 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 t into space obt
34170 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 ained from.** fr
34180 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
34190 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 oc()] before it
341a0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 returns..**.** T
341b0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
341c0 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 t_value() interf
341d0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 ace sets the res
341e0 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 ult of.** the ap
341f0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
34200 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 d function to be
34210 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b a copy the.** [
34220 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
34230 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
34240 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 t specified by t
34250 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 he 2nd parameter
34260 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 . The.** sqlite
34270 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 3_result_value()
34280 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 interface makes
34290 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b a copy of the [
342a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a sqlite3_value].*
342b0 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 * so that the [s
342c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 qlite3_value] sp
342d0 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 ecified in the p
342e0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 arameter may cha
342f0 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 nge or.** be dea
34300 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 llocated after s
34310 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 qlite3_result_va
34320 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 lue() returns wi
34330 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 41 thout harm..** A
34340 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 [protected sqli
34350 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
34360 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 t may always be
34370 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a used where an.**
34380 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 [unprotected sq
34390 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
343a0 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c ect is required,
343b0 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 so either.** ki
343c0 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 nd of [sqlite3_v
343d0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e alue] object can
343e0 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 be used with th
343f0 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a is interface..**
34400 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 .** If these rou
34410 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 tines are called
34420 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 from within the
34430 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 different threa
34440 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e d.** than the on
34450 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 e containing the
34460 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
34470 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 ined function th
34480 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 at received.** t
34490 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 he [sqlite3_cont
344a0 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 ext] pointer, th
344b0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e e results are un
344c0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 defined..**.** I
344d0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
344e0 20 7b 48 31 36 34 30 33 7d 20 54 68 65 20 64 65 {H16403} The de
344f0 66 61 75 6c 74 20 72 65 74 75 72 6e 20 76 61 6c fault return val
34500 75 65 20 66 72 6f 6d 20 61 6e 79 20 53 51 4c 20 ue from any SQL
34510 66 75 6e 63 74 69 6f 6e 20 69 73 20 4e 55 4c 4c function is NULL
34520 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 36 7d ..**.** {H16406}
34530 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 The [sqlite3_re
34540 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c sult_blob(C,V,N,
34550 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 D)] interface ch
34560 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 anges the.**
34570 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c return val
34580 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 ue of function C
34590 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 74 68 to be a BLOB th
345a0 61 74 20 69 73 20 4e 20 62 79 74 65 73 0a 2a 2a at is N bytes.**
345b0 20 20 20 20 20 20 20 20 20 20 69 6e 20 6c 65 6e in len
345c0 67 74 68 20 61 6e 64 20 77 69 74 68 20 63 6f 6e gth and with con
345d0 74 65 6e 74 20 70 6f 69 6e 74 65 64 20 74 6f 20 tent pointed to
345e0 62 79 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 by V..**.** {H16
345f0 34 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 409} The [sqlite
34600 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 3_result_double(
34610 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 C,V)] interface
34620 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 changes the.**
34630 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 return v
34640 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e alue of function
34650 20 43 20 74 6f 20 62 65 20 74 68 65 20 66 6c 6f C to be the flo
34660 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 ating point valu
34670 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 e V..**.** {H164
34680 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 12} The [sqlite3
34690 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 43 2c _result_error(C,
346a0 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 V,N)] interface
346b0 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 changes the retu
346c0 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 rn.** v
346d0 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e alue of function
346e0 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 C to be an exce
346f0 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 ption with error
34700 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 code.**
34710 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d [SQLITE_ERROR]
34720 20 61 6e 64 20 61 20 55 54 46 2d 38 20 65 72 72 and a UTF-8 err
34730 6f 72 20 6d 65 73 73 61 67 65 20 63 6f 70 69 65 or message copie
34740 64 20 66 72 6f 6d 20 56 20 75 70 20 74 6f 20 74 d from V up to t
34750 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 he.** f
34760 69 72 73 74 20 7a 65 72 6f 20 62 79 74 65 20 6f irst zero byte o
34770 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65 73 20 r until N bytes
34780 61 72 65 20 72 65 61 64 20 69 66 20 4e 20 69 73 are read if N is
34790 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a positive..**.**
347a0 20 7b 48 31 36 34 31 35 7d 20 54 68 65 20 5b 73 {H16415} The [s
347b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
347c0 72 6f 72 31 36 28 43 2c 56 2c 4e 29 5d 20 69 6e ror16(C,V,N)] in
347d0 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 terface changes
347e0 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 the return.**
347f0 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 value of
34800 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 function C to be
34810 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 an exception wi
34820 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a th error code.**
34830 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 [SQLIT
34840 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20 61 20 55 E_ERROR] and a U
34850 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 TF-16 native byt
34860 65 20 6f 72 64 65 72 20 65 72 72 6f 72 20 6d 65 e order error me
34870 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 ssage.**
34880 20 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 56 20 copied from V
34890 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 up to the first
348a0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 zero terminator
348b0 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65 73 or until N bytes
348c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 .** are
348d0 20 72 65 61 64 20 69 66 20 4e 20 69 73 20 70 6f read if N is po
348e0 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 sitive..**.** {H
348f0 31 36 34 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 16418} The [sqli
34900 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
34910 5f 74 6f 6f 62 69 67 28 43 29 5d 20 69 6e 74 65 _toobig(C)] inte
34920 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 rface changes th
34930 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 e return.**
34940 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 value of th
34950 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 e function C to
34960 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 be an exception
34970 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a with error code.
34980 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c ** [SQL
34990 49 54 45 5f 54 4f 4f 42 49 47 5d 20 61 6e 64 20 ITE_TOOBIG] and
349a0 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 an appropriate e
349b0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a rror message..**
349c0 0a 2a 2a 20 7b 48 31 36 34 32 31 7d 20 54 68 65 .** {H16421} The
349d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
349e0 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 43 29 5d _error_nomem(C)]
349f0 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 interface chang
34a00 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a es the return.**
34a10 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 value
34a20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 of the function
34a30 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 C to be an excep
34a40 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 tion with error
34a50 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 code.**
34a60 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 [SQLITE_NOMEM]
34a70 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 and an appropria
34a80 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 te error message
34a90 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32 34 7d ..**.** {H16424}
34aa0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 The [sqlite3_re
34ab0 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 sult_error_code(
34ac0 43 2c 45 29 5d 20 69 6e 74 65 72 66 61 63 65 20 C,E)] interface
34ad0 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 changes the retu
34ae0 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 rn.** v
34af0 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63 alue of the func
34b00 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 tion C to be an
34b10 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 exception with e
34b20 72 72 6f 72 20 63 6f 64 65 20 45 2e 0a 2a 2a 20 rror code E..**
34b30 20 20 20 20 20 20 20 20 20 54 68 65 20 65 72 72 The err
34b40 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 or message text
34b50 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a is unchanged..**
34b60 0a 2a 2a 20 7b 48 31 36 34 32 37 7d 20 54 68 65 .** {H16427} The
34b70 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
34b80 5f 69 6e 74 28 43 2c 56 29 5d 20 69 6e 74 65 72 _int(C,V)] inter
34b90 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 face changes the
34ba0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 .** ret
34bb0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e urn value of fun
34bc0 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 ction C to be th
34bd0 65 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72 e 32-bit integer
34be0 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 value V..**.**
34bf0 7b 48 31 36 34 33 30 7d 20 54 68 65 20 5b 73 71 {H16430} The [sq
34c00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 lite3_result_int
34c10 36 34 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 64(C,V)] interfa
34c20 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a ce changes the.*
34c30 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 * retur
34c40 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 n value of funct
34c50 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 ion C to be the
34c60 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 76 64-bit integer v
34c70 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 alue V..**.** {H
34c80 31 36 34 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 16433} The [sqli
34c90 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 te3_result_null(
34ca0 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 C)] interface ch
34cb0 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 anges the.**
34cc0 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c return val
34cd0 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 ue of function C
34ce0 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a to be NULL..**.
34cf0 2a 2a 20 7b 48 31 36 34 33 36 7d 20 54 68 65 20 ** {H16436} The
34d00 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
34d10 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 text(C,V,N,D)] i
34d20 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 nterface changes
34d30 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
34d40 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 return value of
34d50 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 function C to b
34d60 65 20 74 68 65 20 55 54 46 2d 38 20 73 74 72 69 e the UTF-8 stri
34d70 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 56 ng.** V
34d80 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 up to the first
34d90 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 zero if N is ne
34da0 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 gative.**
34db0 20 20 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 or the first
34dc0 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66 20 N bytes of V if
34dd0 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 N is non-negativ
34de0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 39 e..**.** {H16439
34df0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 } The [sqlite3_r
34e00 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 esult_text16(C,V
34e10 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 ,N,D)] interface
34e20 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 changes the.**
34e30 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 return
34e40 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f value of functio
34e50 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 n C to be the UT
34e60 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 F-16 native byte
34e70 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 order.**
34e80 20 20 20 73 74 72 69 6e 67 20 56 20 75 70 20 74 string V up t
34e90 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f o the first zero
34ea0 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 if N is negativ
34eb0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 e.** or
34ec0 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 the first N byt
34ed0 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20 es of V if N is
34ee0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a non-negative..**
34ef0 0a 2a 2a 20 7b 48 31 36 34 34 32 7d 20 54 68 65 .** {H16442} The
34f00 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
34f10 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c _text16be(C,V,N,
34f20 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 D)] interface ch
34f30 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 anges the.**
34f40 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c return val
34f50 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 ue of function C
34f60 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d 31 to be the UTF-1
34f70 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20 6 big-endian.**
34f80 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 string
34f90 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 V up to the firs
34fa0 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e t zero if N is n
34fb0 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 egative.**
34fc0 20 20 20 20 6f 72 20 74 68 65 20 66 69 72 73 74 or the first
34fd0 20 4e 20 62 79 74 65 73 20 6f 72 20 56 20 69 66 N bytes or V if
34fe0 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 N is non-negati
34ff0 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 ve..**.** {H1644
35000 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 5} The [sqlite3_
35010 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 result_text16le(
35020 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 C,V,N,D)] interf
35030 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a ace changes the.
35040 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 ** retu
35050 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 rn value of func
35060 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 tion C to be the
35070 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 UTF-16 little-e
35080 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 ndian.**
35090 20 20 73 74 72 69 6e 67 20 56 20 75 70 20 74 6f string V up to
350a0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 the first zero
350b0 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 if N is negative
350c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 .** or
350d0 74 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 the first N byte
350e0 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e s of V if N is n
350f0 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a on-negative..**.
35100 2a 2a 20 7b 48 31 36 34 34 38 7d 20 54 68 65 20 ** {H16448} The
35110 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
35120 76 61 6c 75 65 28 43 2c 56 29 5d 20 69 6e 74 65 value(C,V)] inte
35130 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 rface changes th
35140 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 e.** re
35150 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 turn value of fu
35160 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 nction C to be t
35170 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 he [unprotected
35180 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a sqlite3_value].*
35190 2a 20 20 20 20 20 20 20 20 20 20 6f 62 6a 65 63 * objec
351a0 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 t V..**.** {H164
351b0 35 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 51} The [sqlite3
351c0 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 _result_zeroblob
351d0 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 (C,N)] interface
351e0 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 changes the.**
351f0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 return
35200 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f value of functio
35210 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 4e 2d 62 n C to be an N-b
35220 79 74 65 20 42 4c 4f 42 20 6f 66 20 61 6c 6c 20 yte BLOB of all
35230 7a 65 72 6f 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 zeros..**.** {H1
35240 36 34 35 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 6454} The [sqlit
35250 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
35260 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
35270 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 result_error16()
35280 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e ].** in
35290 74 65 72 66 61 63 65 73 20 6d 61 6b 65 20 61 20 terfaces make a
352a0 63 6f 70 79 20 6f 66 20 74 68 65 69 72 20 65 72 copy of their er
352b0 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 ror message stri
352c0 6e 67 73 20 62 65 66 6f 72 65 0a 2a 2a 20 20 20 ngs before.**
352d0 20 20 20 20 20 20 20 72 65 74 75 72 6e 69 6e 67 returning
352e0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 35 37 7d ..**.** {H16457}
352f0 20 49 66 20 74 68 65 20 44 20 64 65 73 74 72 75 If the D destru
35300 63 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 ctor parameter t
35310 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c o [sqlite3_resul
35320 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d t_blob(C,V,N,D)]
35330 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 ,.** [s
35340 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
35350 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 xt(C,V,N,D)], [s
35360 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
35370 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a xt16(C,V,N,D)],.
35380 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
35390 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
353a0 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 16be(C,V,N,D)],
353b0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b or.** [
353c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
353d0 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 ext16le(C,V,N,D)
353e0 5d 20 69 73 20 74 68 65 20 63 6f 6e 73 74 61 6e ] is the constan
353f0 74 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 t [SQLITE_STATIC
35400 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 ].** th
35410 65 6e 20 6e 6f 20 64 65 73 74 72 75 63 74 6f 72 en no destructor
35420 20 69 73 20 65 76 65 72 20 63 61 6c 6c 65 64 20 is ever called
35430 6f 6e 20 74 68 65 20 70 6f 69 6e 74 65 72 20 56 on the pointer V
35440 20 61 6e 64 20 53 51 4c 69 74 65 0a 2a 2a 20 20 and SQLite.**
35450 20 20 20 20 20 20 20 20 61 73 73 75 6d 65 73 20 assumes
35460 74 68 61 74 20 56 20 69 73 20 69 6d 6d 75 74 61 that V is immuta
35470 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 ble..**.** {H164
35480 36 30 7d 20 49 66 20 74 68 65 20 44 20 64 65 73 60} If the D des
35490 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65 tructor paramete
354a0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 r to [sqlite3_re
354b0 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c sult_blob(C,V,N,
354c0 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 D)],.**
354d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
354e0 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c _text(C,V,N,D)],
354f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
35500 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 _text16(C,V,N,D)
35510 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b ],.** [
35520 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
35530 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 ext16be(C,V,N,D)
35540 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 ], or.**
35550 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c [sqlite3_resul
35560 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e t_text16le(C,V,N
35570 2c 44 29 5d 20 69 73 20 74 68 65 20 63 6f 6e 73 ,D)] is the cons
35580 74 61 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 tant.**
35590 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 [SQLITE_TRANSIE
355a0 4e 54 5d 20 74 68 65 6e 20 74 68 65 20 69 6e 74 NT] then the int
355b0 65 72 66 61 63 65 73 20 6d 61 6b 65 73 20 61 20 erfaces makes a
355c0 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 copy of the.**
355d0 20 20 20 20 20 20 20 20 63 6f 6e 74 65 6e 74 20 content
355e0 6f 66 20 56 20 61 6e 64 20 72 65 74 61 69 6e 73 of V and retains
355f0 20 74 68 65 20 63 6f 70 79 2e 0a 2a 2a 0a 2a 2a the copy..**.**
35600 20 7b 48 31 36 34 36 33 7d 20 49 66 20 74 68 65 {H16463} If the
35610 20 44 20 64 65 73 74 72 75 63 74 6f 72 20 70 61 D destructor pa
35620 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
35630 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 te3_result_blob(
35640 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 C,V,N,D)],.**
35650 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
35660 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c result_text(C,V,
35670 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f N,D)], [sqlite3_
35680 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c result_text16(C,
35690 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 V,N,D)],.**
356a0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 [sqlite3_re
356b0 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c sult_text16be(C,
356c0 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 V,N,D)], or.**
356d0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
356e0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 _result_text16le
356f0 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 73 6f (C,V,N,D)] is so
35700 6d 65 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 me value other t
35710 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 han.**
35720 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 the constants [S
35730 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 20 61 6e QLITE_STATIC] an
35740 64 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 d [SQLITE_TRANSI
35750 45 4e 54 5d 20 74 68 65 6e 0a 2a 2a 20 20 20 20 ENT] then.**
35760 20 20 20 20 20 20 53 51 4c 69 74 65 20 77 69 6c SQLite wil
35770 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 l invoke the des
35780 74 72 75 63 74 6f 72 20 44 20 77 69 74 68 20 56 tructor D with V
35790 20 61 73 20 69 74 73 20 6f 6e 6c 79 20 61 72 67 as its only arg
357a0 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 ument.**
357b0 20 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 when it has fi
357c0 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20 nished with the
357d0 56 20 76 61 6c 75 65 2e 0a 2a 2f 0a 76 6f 69 64 V value..*/.void
357e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
357f0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e blob(sqlite3_con
35800 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 text*, const voi
35810 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 d*, int, void(*)
35820 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 (void*));.void s
35830 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f qlite3_result_do
35840 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e uble(sqlite3_con
35850 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a text*, double);.
35860 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
35870 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 ult_error(sqlite
35880 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 3_context*, cons
35890 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 t char*, int);.v
358a0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
358b0 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 lt_error16(sqlit
358c0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e e3_context*, con
358d0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a st void*, int);.
358e0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
358f0 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 ult_error_toobig
35900 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
35910 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 *);.void sqlite3
35920 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f _result_error_no
35930 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 mem(sqlite3_cont
35940 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 ext*);.void sqli
35950 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
35960 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f _code(sqlite3_co
35970 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f ntext*, int);.vo
35980 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
35990 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f t_int(sqlite3_co
359a0 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f ntext*, int);.vo
359b0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
359c0 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f t_int64(sqlite3_
359d0 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 context*, sqlite
359e0 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 3_int64);.void s
359f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 qlite3_result_nu
35a00 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ll(sqlite3_conte
35a10 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 xt*);.void sqlit
35a20 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 e3_result_text(s
35a30 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
35a40 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e const char*, in
35a50 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a t, void(*)(void*
35a60 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 ));.void sqlite3
35a70 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 _result_text16(s
35a80 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
35a90 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
35aa0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a t, void(*)(void*
35ab0 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 ));.void sqlite3
35ac0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 _result_text16le
35ad0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
35ae0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 *, const void*,
35af0 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 int,void(*)(void
35b00 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 *));.void sqlite
35b10 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 3_result_text16b
35b20 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 e(sqlite3_contex
35b30 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c t*, const void*,
35b40 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 int,void(*)(voi
35b50 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 d*));.void sqlit
35b60 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 e3_result_value(
35b70 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
35b80 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a , sqlite3_value*
35b90 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
35ba0 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 result_zeroblob(
35bb0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
35bc0 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a , int n);../*.**
35bd0 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e CAPI3REF: Defin
35be0 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 e New Collating
35bf0 53 65 71 75 65 6e 63 65 73 20 7b 48 31 36 36 30 Sequences {H1660
35c00 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 0} <S20300>.**.*
35c10 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e * These function
35c20 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 s are used to ad
35c30 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 d new collation
35c40 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74 68 65 sequences to the
35c50 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
35c60 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 nnection] specif
35c70 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 ied as the first
35c80 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a argument..**.**
35c90 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 The name of the
35ca0 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 new collation s
35cb0 65 71 75 65 6e 63 65 20 69 73 20 73 70 65 63 69 equence is speci
35cc0 66 69 65 64 20 61 73 20 61 20 55 54 46 2d 38 20 fied as a UTF-8
35cd0 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 string.** for sq
35ce0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
35cf0 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c lation() and sql
35d00 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
35d10 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e ation_v2().** an
35d20 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e d a UTF-16 strin
35d30 67 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 g for sqlite3_cr
35d40 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 eate_collation16
35d50 28 29 2e 20 49 6e 20 61 6c 6c 20 63 61 73 65 73 (). In all cases
35d60 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20 .** the name is
35d70 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 passed as the se
35d80 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 cond function ar
35d90 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 gument..**.** Th
35da0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 e third argument
35db0 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 74 may be one of t
35dc0 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 he constants [SQ
35dd0 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b LITE_UTF8],.** [
35de0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 SQLITE_UTF16LE]
35df0 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 or [SQLITE_UTF16
35e00 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 BE], indicating
35e10 74 68 61 74 20 74 68 65 20 75 73 65 72 2d 73 75 that the user-su
35e20 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e pplied.** routin
35e30 65 20 65 78 70 65 63 74 73 20 74 6f 20 62 65 20 e expects to be
35e40 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73 20 passed pointers
35e50 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f 64 to strings encod
35e60 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a ed using UTF-8,.
35e70 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 ** UTF-16 little
35e80 2d 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d -endian, or UTF-
35e90 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 2c 20 72 16 big-endian, r
35ea0 65 73 70 65 63 74 69 76 65 6c 79 2e 20 54 68 65 espectively. The
35eb0 0a 2a 2a 20 74 68 69 72 64 20 61 72 67 75 6d 65 .** third argume
35ec0 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 nt might also be
35ed0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 [SQLITE_UTF16_A
35ee0 4c 49 47 4e 45 44 5d 20 74 6f 20 69 6e 64 69 63 LIGNED] to indic
35ef0 61 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 ate that.** the
35f00 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 routine expects
35f10 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 36 2d 62 pointers to 16-b
35f20 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 65 64 20 it word aligned
35f30 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 strings.** of UT
35f40 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 F-16 in the nati
35f50 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 6f 66 ve byte order of
35f60 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 the host comput
35f70 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e er..**.** A poin
35f80 74 65 72 20 74 6f 20 74 68 65 20 75 73 65 72 20 ter to the user
35f90 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 supplied routine
35fa0 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 must be passed
35fb0 61 73 20 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 as the fifth.**
35fc0 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 69 74 argument. If it
35fd0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69 is NULL, this i
35fe0 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 64 65 s the same as de
35ff0 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61 leting the colla
36000 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 tion.** sequence
36010 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 (so that SQLite
36020 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 cannot call it
36030 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20 45 61 63 anymore)..** Eac
36040 68 20 74 69 6d 65 20 74 68 65 20 61 70 70 6c 69 h time the appli
36050 63 61 74 69 6f 6e 20 73 75 70 70 6c 69 65 64 20 cation supplied
36060 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f function is invo
36070 6b 65 64 2c 20 69 74 20 69 73 20 70 61 73 73 65 ked, it is passe
36080 64 0a 2a 2a 20 61 73 20 69 74 73 20 66 69 72 73 d.** as its firs
36090 74 20 70 61 72 61 6d 65 74 65 72 20 61 20 63 6f t parameter a co
360a0 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 py of the void*
360b0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f passed as the fo
360c0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a urth argument.**
360d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 to sqlite3_crea
360e0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f te_collation() o
360f0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 r sqlite3_create
36100 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a _collation16()..
36110 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e **.** The remain
36120 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74 6f ing arguments to
36130 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
36140 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e -supplied routin
36150 65 20 61 72 65 20 74 77 6f 20 73 74 72 69 6e 67 e are two string
36160 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70 72 65 s,.** each repre
36170 73 65 6e 74 65 64 20 62 79 20 61 20 28 6c 65 6e sented by a (len
36180 67 74 68 2c 20 64 61 74 61 29 20 70 61 69 72 20 gth, data) pair
36190 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e 20 74 and encoded in t
361a0 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 he encoding.** t
361b0 68 61 74 20 77 61 73 20 70 61 73 73 65 64 20 61 hat was passed a
361c0 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 s the third argu
361d0 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 20 63 6f ment when the co
361e0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 llation sequence
361f0 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 74 65 72 was.** register
36200 65 64 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20 61 ed. {END} The a
36210 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e pplication defin
36220 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 ed collation rou
36230 74 69 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 tine should.** r
36240 65 74 75 72 6e 20 6e 65 67 61 74 69 76 65 2c 20 eturn negative,
36250 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74 69 76 65 zero or positive
36260 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73 74 if the first st
36270 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 ring is less tha
36280 6e 2c 0a 2a 2a 20 65 71 75 61 6c 20 74 6f 2c 20 n,.** equal to,
36290 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 or greater than
362a0 74 68 65 20 73 65 63 6f 6e 64 20 73 74 72 69 6e the second strin
362b0 67 2e 20 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 g. i.e. (STRING1
362c0 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a - STRING2)..**.
362d0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 ** The sqlite3_c
362e0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f reate_collation_
362f0 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 v2() works like
36300 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
36310 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 ollation().** ex
36320 63 65 70 74 20 74 68 61 74 20 69 74 20 74 61 6b cept that it tak
36330 65 73 20 61 6e 20 65 78 74 72 61 20 61 72 67 75 es an extra argu
36340 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 ment which is a
36350 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a destructor for.*
36360 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e * the collation.
36370 20 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 The destructor
36380 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 is called when
36390 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 the collation is
363a0 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64 20 61 6e .** destroyed an
363b0 64 20 69 73 20 70 61 73 73 65 64 20 61 20 63 6f d is passed a co
363c0 70 79 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 py of the fourth
363d0 20 70 61 72 61 6d 65 74 65 72 20 76 6f 69 64 2a parameter void*
363e0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 pointer.** of t
363f0 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 he sqlite3_creat
36400 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 e_collation_v2()
36410 2e 0a 2a 2a 20 43 6f 6c 6c 61 74 69 6f 6e 73 20 ..** Collations
36420 61 72 65 20 64 65 73 74 72 6f 79 65 64 20 77 68 are destroyed wh
36430 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 en they are over
36440 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 20 ridden by later
36450 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 calls to the.**
36460 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 collation creati
36470 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 on functions or
36480 77 68 65 6e 20 74 68 65 20 5b 64 61 74 61 62 61 when the [databa
36490 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 se connection] i
364a0 73 20 63 6c 6f 73 65 64 0a 2a 2a 20 75 73 69 6e s closed.** usin
364b0 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 g [sqlite3_close
364c0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 ()]..**.** INVAR
364d0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 IANTS:.**.** {H1
364e0 36 36 30 33 7d 20 41 20 73 75 63 63 65 73 73 66 6603} A successf
364f0 75 6c 20 63 61 6c 6c 20 74 6f 20 74 68 65 0a 2a ul call to the.*
36500 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
36510 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
36520 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c tion_v2(B,X,E,P,
36530 46 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 0a F,D)] interface.
36540 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69 ** regi
36550 73 74 65 72 73 20 66 75 6e 63 74 69 6f 6e 20 46 sters function F
36560 20 61 73 20 74 68 65 20 63 6f 6d 70 61 72 69 73 as the comparis
36570 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 75 73 65 64 on function used
36580 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 to.**
36590 69 6d 70 6c 65 6d 65 6e 74 20 63 6f 6c 6c 61 74 implement collat
365a0 69 6f 6e 20 58 20 6f 6e 20 74 68 65 20 5b 64 61 ion X on the [da
365b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
365c0 6e 5d 20 42 20 66 6f 72 0a 2a 2a 20 20 20 20 20 n] B for.**
365d0 20 20 20 20 20 64 61 74 61 62 61 73 65 73 20 68 databases h
365e0 61 76 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20 45 aving encoding E
365f0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 34 7d ..**.** {H16604}
36600 20 53 51 4c 69 74 65 20 75 6e 64 65 72 73 74 61 SQLite understa
36610 6e 64 73 20 74 68 65 20 58 20 70 61 72 61 6d 65 nds the X parame
36620 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 ter to.**
36630 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 [sqlite3_crea
36640 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 te_collation_v2(
36650 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 61 73 B,X,E,P,F,D)] as
36660 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 a zero-terminat
36670 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 55 ed.** U
36680 54 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 20 77 TF-8 string in w
36690 68 69 63 68 20 63 61 73 65 20 69 73 20 69 67 6e hich case is ign
366a0 6f 72 65 64 20 66 6f 72 20 41 53 43 49 49 20 63 ored for ASCII c
366b0 68 61 72 61 63 74 65 72 73 20 61 6e 64 0a 2a 2a haracters and.**
366c0 20 20 20 20 20 20 20 20 20 20 69 73 20 73 69 67 is sig
366d0 6e 69 66 69 63 61 6e 74 20 66 6f 72 20 6e 6f 6e nificant for non
366e0 2d 41 53 43 49 49 20 63 68 61 72 61 63 74 65 72 -ASCII character
366f0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 36 s..**.** {H16606
36700 7d 20 53 75 63 63 65 73 73 69 76 65 20 63 61 6c } Successive cal
36710 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ls to [sqlite3_c
36720 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f reate_collation_
36730 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d v2(B,X,E,P,F,D)]
36740 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 .** wit
36750 68 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 h the same value
36760 73 20 66 6f 72 20 42 2c 20 58 2c 20 61 6e 64 20 s for B, X, and
36770 45 2c 20 6f 76 65 72 72 69 64 65 20 70 72 69 6f E, override prio
36780 72 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 r values.**
36790 20 20 20 20 20 6f 66 20 50 2c 20 46 2c 20 61 6e of P, F, an
367a0 64 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 d D..**.** {H166
367b0 30 39 7d 20 49 66 20 74 68 65 20 64 65 73 74 72 09} If the destr
367c0 75 63 74 6f 72 20 44 20 69 6e 20 5b 73 71 6c 69 uctor D in [sqli
367d0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
367e0 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c tion_v2(B,X,E,P,
367f0 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 F,D)].**
36800 20 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 is not NULL th
36810 65 6e 20 69 74 20 69 73 20 63 61 6c 6c 65 64 20 en it is called
36820 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 with argument P
36830 77 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 when the.**
36840 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 66 collating f
36850 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 unction is dropp
36860 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a ed by SQLite..**
36870 0a 2a 2a 20 7b 48 31 36 36 31 32 7d 20 41 20 63 .** {H16612} A c
36880 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f ollating functio
36890 6e 20 69 73 20 64 72 6f 70 70 65 64 20 77 68 65 n is dropped whe
368a0 6e 20 69 74 20 69 73 20 6f 76 65 72 6c 6f 61 64 n it is overload
368b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31 ed..**.** {H1661
368c0 35 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 5} A collating f
368d0 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 unction is dropp
368e0 65 64 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 ed when the data
368f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a base connection.
36900 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 63 ** is c
36910 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c losed using [sql
36920 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a ite3_close()]..*
36930 2a 0a 2a 2a 20 7b 48 31 36 36 31 38 7d 20 54 68 *.** {H16618} Th
36940 65 20 70 6f 69 6e 74 65 72 20 50 20 69 6e 20 5b e pointer P in [
36950 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
36960 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c ollation_v2(B,X,
36970 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 E,P,F,D)].**
36980 20 20 20 20 20 20 69 73 20 70 61 73 73 65 64 20 is passed
36990 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 through as the f
369a0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 irst parameter t
369b0 6f 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e o the comparison
369c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e .** fun
369d0 63 74 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c 20 ction F for all
369e0 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 subsequent invoc
369f0 61 74 69 6f 6e 73 20 6f 66 20 46 2e 0a 2a 2a 0a ations of F..**.
36a00 2a 2a 20 7b 48 31 36 36 32 31 7d 20 41 20 63 61 ** {H16621} A ca
36a10 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ll to [sqlite3_c
36a20 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 reate_collation(
36a30 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 69 73 20 65 B,X,E,P,F)] is e
36a40 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 xactly.**
36a50 20 20 20 74 68 65 20 73 61 6d 65 20 61 73 20 61 the same as a
36a60 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
36a70 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
36a80 6f 6e 5f 76 32 28 29 5d 20 77 69 74 68 0a 2a 2a on_v2()] with.**
36a90 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61 the sa
36aa0 6d 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e me parameters an
36ab0 64 20 61 20 4e 55 4c 4c 20 64 65 73 74 72 75 63 d a NULL destruc
36ac0 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 tor..**.** {H166
36ad0 32 34 7d 20 46 6f 6c 6c 6f 77 69 6e 67 20 61 20 24} Following a
36ae0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
36af0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 collation_v2(B,X
36b00 2c 45 2c 50 2c 46 2c 44 29 5d 2c 0a 2a 2a 20 20 ,E,P,F,D)],.**
36b10 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 75 SQLite u
36b20 73 65 73 20 74 68 65 20 63 6f 6d 70 61 72 69 73 ses the comparis
36b30 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f on function F fo
36b40 72 20 61 6c 6c 20 74 65 78 74 20 63 6f 6d 70 61 r all text compa
36b50 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 rison.**
36b60 20 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 operations on
36b70 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
36b80 6e 6e 65 63 74 69 6f 6e 5d 20 42 20 6f 6e 20 74 nnection] B on t
36b90 65 78 74 20 76 61 6c 75 65 73 20 74 68 61 74 0a ext values that.
36ba0 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73 65 20 ** use
36bb0 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 the collating se
36bc0 71 75 65 6e 63 65 20 6e 61 6d 65 64 20 58 2e 0a quence named X..
36bd0 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 37 7d 20 54 **.** {H16627} T
36be0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 he [sqlite3_crea
36bf0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 42 te_collation16(B
36c00 2c 58 2c 45 2c 50 2c 46 29 5d 20 77 6f 72 6b 73 ,X,E,P,F)] works
36c10 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 the same.**
36c20 20 20 20 20 20 20 61 73 20 5b 73 71 6c 69 74 65 as [sqlite
36c30 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
36c40 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 65 on(B,X,E,P,F)] e
36c50 78 63 65 70 74 20 74 68 61 74 20 74 68 65 0a 2a xcept that the.*
36c60 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 * colla
36c70 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69 73 20 75 tion name X is u
36c80 6e 64 65 72 73 74 6f 6f 64 20 61 73 20 55 54 46 nderstood as UTF
36c90 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 -16 in native by
36ca0 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 te order.**
36cb0 20 20 20 20 20 69 6e 73 74 65 61 64 20 6f 66 20 instead of
36cc0 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 UTF-8..**.** {H1
36cd0 36 36 33 30 7d 20 57 68 65 6e 20 6d 75 6c 74 69 6630} When multi
36ce0 70 6c 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 ple comparison f
36cf0 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 61 76 61 unctions are ava
36d00 69 6c 61 62 6c 65 20 66 6f 72 20 74 68 65 20 73 ilable for the s
36d10 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ame.**
36d20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e collating sequen
36d30 63 65 2c 20 53 51 4c 69 74 65 20 63 68 6f 6f 73 ce, SQLite choos
36d40 65 73 20 74 68 65 20 6f 6e 65 20 77 68 6f 73 65 es the one whose
36d50 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a text encoding.*
36d60 2a 20 20 20 20 20 20 20 20 20 20 72 65 71 75 69 * requi
36d70 72 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d res the least am
36d80 6f 75 6e 74 20 6f 66 20 63 6f 6e 76 65 72 73 69 ount of conversi
36d90 6f 6e 20 66 72 6f 6d 20 74 68 65 20 64 65 66 61 on from the defa
36da0 75 6c 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ult.**
36db0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66 text encoding of
36dc0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a 2a the database..*
36dd0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 /.int sqlite3_cr
36de0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a eate_collation(.
36df0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 sqlite3*, . c
36e00 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
36e10 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 , . int eTextRe
36e20 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 p, . void*,. i
36e30 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f nt(*xCompare)(vo
36e40 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f id*,int,const vo
36e50 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f id*,int,const vo
36e60 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 id*).);.int sqli
36e70 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
36e80 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 tion_v2(. sqlit
36e90 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 e3*, . const ch
36ea0 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e ar *zName, . in
36eb0 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 t eTextRep, . v
36ec0 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f oid*,. int(*xCo
36ed0 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 mpare)(void*,int
36ee0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 ,const void*,int
36ef0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 ,const void*),.
36f00 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 void(*xDestroy)
36f10 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 (void*).);.int s
36f20 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
36f30 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c llation16(. sql
36f40 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 ite3*, . const
36f50 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 void *zName,. i
36f60 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 nt eTextRep, .
36f70 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 void*,. int(*xC
36f80 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e ompare)(void*,in
36f90 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e t,const void*,in
36fa0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 t,const void*).)
36fb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
36fc0 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 F: Collation Nee
36fd0 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 ded Callbacks {H
36fe0 31 36 37 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a 16700} <S20300>.
36ff0 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 68 **.** To avoid h
37000 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 aving to registe
37010 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 r all collation
37020 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 sequences before
37030 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 a database.** c
37040 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 an be used, a si
37050 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 ngle callback fu
37060 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 nction may be re
37070 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68 gistered with th
37080 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 e.** [database c
37090 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 onnection] to be
370a0 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76 65 72 called whenever
370b0 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f an undefined co
370c0 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 llation.** seque
370d0 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e nce is required.
370e0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 75 .**.** If the fu
370f0 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 nction is regist
37100 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 ered using the s
37110 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
37120 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a _needed() API,.*
37130 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 * then it is pas
37140 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 sed the names of
37150 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 undefined colla
37160 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 tion sequences a
37170 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 s strings.** enc
37180 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 7b oded in UTF-8. {
37190 48 31 36 37 30 33 7d 20 49 66 20 73 71 6c 69 74 H16703} If sqlit
371a0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 e3_collation_nee
371b0 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c ded16() is used,
371c0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 .** the names ar
371d0 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d e passed as UTF-
371e0 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 16 in machine na
371f0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e tive byte order.
37200 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 65 69 .** A call to ei
37210 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 ther function re
37220 70 6c 61 63 65 73 20 61 6e 79 20 65 78 69 73 74 places any exist
37230 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a ing callback..**
37240 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c .** When the cal
37250 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
37260 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 , the first argu
37270 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 ment passed is a
37280 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 copy.** of the
37290 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
372a0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 to sqlite3_colla
372b0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 tion_needed() or
372c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c .** sqlite3_coll
372d0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 ation_needed16()
372e0 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 . The second ar
372f0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 gument is the da
37300 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 tabase.** connec
37310 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 tion. The third
37320 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 argument is one
37330 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 of [SQLITE_UTF8
37340 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 ], [SQLITE_UTF16
37350 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 BE],.** or [SQLI
37360 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 TE_UTF16LE], ind
37370 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 icating the most
37380 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 desirable form
37390 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e of the collation
373a0 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e .** sequence fun
373b0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 ction required.
373c0 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 The fourth para
373d0 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d meter is the nam
373e0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 e of the.** requ
373f0 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 ired collation s
37400 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 equence..**.** T
37410 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 he callback func
37420 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 tion should regi
37430 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64 ster the desired
37440 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 collation using
37450 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 .** [sqlite3_cre
37460 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d ate_collation()]
37470 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 , [sqlite3_creat
37480 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d e_collation16()]
37490 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 , or.** [sqlite3
374a0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
374b0 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 n_v2()]..**.** I
374c0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
374d0 20 7b 48 31 36 37 30 32 7d 20 41 20 73 75 63 63 {H16702} A succ
374e0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b essful call to [
374f0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f sqlite3_collatio
37500 6e 5f 6e 65 65 64 65 64 28 44 2c 50 2c 46 29 5d n_needed(D,P,F)]
37510 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 .** or
37520 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 [sqlite3_collati
37530 6f 6e 5f 6e 65 65 64 65 64 31 36 28 44 2c 50 2c on_needed16(D,P,
37540 46 29 5d 20 63 61 75 73 65 73 0a 2a 2a 20 20 20 F)] causes.**
37550 20 20 20 20 20 20 20 74 68 65 20 5b 64 61 74 61 the [data
37560 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
37570 20 44 20 74 6f 20 69 6e 76 6f 6b 65 20 63 61 6c D to invoke cal
37580 6c 62 61 63 6b 20 46 20 77 69 74 68 20 66 69 72 lback F with fir
37590 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 st.** p
375a0 61 72 61 6d 65 74 65 72 20 50 20 77 68 65 6e 65 arameter P whene
375b0 76 65 72 20 69 74 20 6e 65 65 64 73 20 61 20 63 ver it needs a c
375c0 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 omparison functi
375d0 6f 6e 20 66 6f 72 20 61 0a 2a 2a 20 20 20 20 20 on for a.**
375e0 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 73 collating s
375f0 65 71 75 65 6e 63 65 20 74 68 61 74 20 69 74 20 equence that it
37600 64 6f 65 73 20 6e 6f 74 20 6b 6e 6f 77 20 61 62 does not know ab
37610 6f 75 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 out..**.** {H167
37620 30 34 7d 20 45 61 63 68 20 73 75 63 63 65 73 73 04} Each success
37630 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ful call to [sql
37640 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
37650 65 65 64 65 64 28 29 5d 20 6f 72 0a 2a 2a 20 20 eeded()] or.**
37660 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
37670 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 _collation_neede
37680 64 31 36 28 29 5d 20 6f 76 65 72 72 69 64 65 73 d16()] overrides
37690 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 the callback re
376a0 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 20 20 20 gistered.**
376b0 20 20 20 20 20 6f 6e 20 74 68 65 20 73 61 6d 65 on the same
376c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
376d0 63 74 69 6f 6e 5d 20 62 79 20 70 72 69 6f 72 20 ction] by prior
376e0 63 61 6c 6c 73 20 74 6f 20 65 69 74 68 65 72 0a calls to either.
376f0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 ** inte
37700 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 rface..**.** {H1
37710 36 37 30 36 7d 20 54 68 65 20 6e 61 6d 65 20 6f 6706} The name o
37720 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 f the requested
37730 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 collating functi
37740 6f 6e 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 on passed in the
37750 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 34 74 68 .** 4th
37760 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
37770 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e e callback is in
37780 20 55 54 46 2d 38 20 69 66 20 74 68 65 20 63 61 UTF-8 if the ca
37790 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 llback.**
377a0 20 20 20 77 61 73 20 72 65 67 69 73 74 65 72 65 was registere
377b0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
377c0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 _collation_neede
377d0 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 d()] and.**
377e0 20 20 20 20 20 69 73 20 69 6e 20 55 54 46 2d 31 is in UTF-1
377f0 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 6 native byte or
37800 64 65 72 20 69 66 20 74 68 65 20 63 61 6c 6c 62 der if the callb
37810 61 63 6b 20 77 61 73 0a 2a 2a 20 20 20 20 20 20 ack was.**
37820 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20 75 registered u
37830 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f sing [sqlite3_co
37840 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 llation_needed16
37850 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ()]..*/.int sqli
37860 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 te3_collation_ne
37870 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a eded(. sqlite3*
37880 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 , . void*, . v
37890 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c oid(*)(void*,sql
378a0 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 ite3*,int eTextR
378b0 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a ep,const char*).
378c0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 );.int sqlite3_c
378d0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 ollation_needed1
378e0 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 6(. sqlite3*, .
378f0 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 void*,. void(
37900 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 *)(void*,sqlite3
37910 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 *,int eTextRep,c
37920 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a onst void*).);..
37930 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 /*.** Specify th
37940 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 e key for an enc
37950 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e rypted database.
37960 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 This routine s
37970 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c hould be.** call
37980 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73 ed right after s
37990 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a qlite3_open()..*
379a0 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f *.** The code to
379b0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 implement this
379c0 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c API is not avail
379d0 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c able in the publ
379e0 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 ic release.** of
379f0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 SQLite..*/.int
37a00 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 sqlite3_key(. s
37a10 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
37a20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
37a30 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 Database to be
37a40 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e rekeyed */. con
37a50 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 st void *pKey, i
37a60 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 nt nKey /* T
37a70 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a he key */.);../*
37a80 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b .** Change the k
37a90 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 ey on an open da
37aa0 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 tabase. If the
37ab0 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 current database
37ac0 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 is not.** encry
37ad0 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 pted, this routi
37ae0 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 ne will encrypt
37af0 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 it. If pNew==0
37b00 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a or nNew==0, the.
37b10 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64 ** database is d
37b20 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 ecrypted..**.**
37b30 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c The code to impl
37b40 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 ement this API i
37b50 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 s not available
37b60 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 in the public re
37b70 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 lease.** of SQLi
37b80 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 te..*/.int sqlit
37b90 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 e3_rekey(. sqli
37ba0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
37bb0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 /* Da
37bc0 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b tabase to be rek
37bd0 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 eyed */. const
37be0 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 void *pKey, int
37bf0 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 nKey /* The
37c00 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f new key */.);../
37c10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
37c20 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e uspend Execution
37c30 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d For A Short Tim
37c40 65 20 7b 48 31 30 35 33 30 7d 20 3c 53 34 30 34 e {H10530} <S404
37c50 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 10>.**.** The sq
37c60 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 lite3_sleep() fu
37c70 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 nction causes th
37c80 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 e current thread
37c90 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 to suspend exec
37ca0 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 ution.** for at
37cb0 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f least a number o
37cc0 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 f milliseconds s
37cd0 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 pecified in its
37ce0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a parameter..**.**
37cf0 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e If the operatin
37d00 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f g system does no
37d10 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 t support sleep
37d20 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a requests with.**
37d30 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d millisecond tim
37d40 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 e resolution, th
37d50 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c en the time will
37d60 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 be rounded up t
37d70 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 o.** the nearest
37d80 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d second. The num
37d90 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f ber of milliseco
37da0 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 nds of sleep act
37db0 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 ually.** request
37dc0 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 ed from the oper
37dd0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 ating system is
37de0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
37df0 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 SQLite implement
37e00 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 s this interface
37e10 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 by calling the
37e20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 xSleep().** meth
37e30 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c od of the defaul
37e40 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 t [sqlite3_vfs]
37e50 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e object..**.** IN
37e60 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
37e70 7b 48 31 30 35 33 33 7d 20 54 68 65 20 5b 73 71 {H10533} The [sq
37e80 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d 20 lite3_sleep(M)]
37e90 69 6e 74 65 72 66 61 63 65 20 69 6e 76 6f 6b 65 interface invoke
37ea0 73 20 74 68 65 20 78 53 6c 65 65 70 0a 2a 2a 20 s the xSleep.**
37eb0 20 20 20 20 20 20 20 20 20 6d 65 74 68 6f 64 20 method
37ec0 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b of the default [
37ed0 73 71 6c 69 74 65 33 5f 76 66 73 7c 56 46 53 5d sqlite3_vfs|VFS]
37ee0 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 in order to.**
37ef0 20 20 20 20 20 20 20 20 20 73 75 73 70 65 6e 64 suspend
37f00 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 execution of th
37f10 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 e current thread
37f20 20 66 6f 72 20 61 74 20 6c 65 61 73 74 0a 2a 2a for at least.**
37f30 20 20 20 20 20 20 20 20 20 20 4d 20 6d 69 6c 6c M mill
37f40 69 73 65 63 6f 6e 64 73 2e 0a 2a 2a 0a 2a 2a 20 iseconds..**.**
37f50 7b 48 31 30 35 33 36 7d 20 54 68 65 20 5b 73 71 {H10536} The [sq
37f60 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d 20 lite3_sleep(M)]
37f70 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
37f80 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a s the number of.
37f90 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 69 6c 6c ** mill
37fa0 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 iseconds of slee
37fb0 70 20 61 63 74 75 61 6c 6c 79 20 72 65 71 75 65 p actually reque
37fc0 73 74 65 64 20 6f 66 20 74 68 65 20 6f 70 65 72 sted of the oper
37fd0 61 74 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 ating.**
37fe0 20 20 73 79 73 74 65 6d 2c 20 77 68 69 63 68 20 system, which
37ff0 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 might be larger
38000 74 68 61 6e 20 74 68 65 20 70 61 72 61 6d 65 74 than the paramet
38010 65 72 20 4d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c er M..*/.int sql
38020 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b ite3_sleep(int);
38030 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
38040 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f : Name Of The Fo
38050 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d lder Holding Tem
38060 70 6f 72 61 72 79 20 46 69 6c 65 73 20 7b 48 31 porary Files {H1
38070 30 33 31 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 0310} <S20000>.*
38080 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20 67 6c 6f *.** If this glo
38090 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 bal variable is
380a0 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f made to point to
380b0 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 a string which
380c0 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f is.** the name o
380d0 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e f a folder (a.k.
380e0 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 a. directory), t
380f0 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 hen all temporar
38100 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 y files.** creat
38110 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 69 6c ed by SQLite wil
38120 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 l be placed in t
38130 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 20 20 hat directory.
38140 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 If this variable
38150 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f .** is a NULL po
38160 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 inter, then SQLi
38170 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 te performs a se
38180 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 arch for an appr
38190 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f opriate.** tempo
381a0 72 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 rary file direct
381b0 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 ory..**.** It is
381c0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 6d 6f 64 not safe to mod
381d0 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c ify this variabl
381e0 65 20 6f 6e 63 65 20 61 20 5b 64 61 74 61 62 61 e once a [databa
381f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a se connection].*
38200 2a 20 68 61 73 20 62 65 65 6e 20 6f 70 65 6e 65 * has been opene
38210 64 2e 20 20 49 74 20 69 73 20 69 6e 74 65 6e 64 d. It is intend
38220 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 ed that this var
38230 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 iable be set onc
38240 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 e.** as part of
38250 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 process initiali
38260 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 zation and befor
38270 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 e any SQLite int
38280 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e erface.** routin
38290 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c es have been cal
382a0 6c 20 61 6e 64 20 72 65 6d 61 69 6e 20 75 6e 63 l and remain unc
382b0 68 61 6e 67 65 64 20 74 68 65 72 65 61 66 74 65 hanged thereafte
382c0 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 r..*/.SQLITE_EXT
382d0 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 ERN char *sqlite
382e0 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3_temp_directory
382f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
38300 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f F: Test For Auto
38310 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 20 7b 48 31 -Commit Mode {H1
38320 32 39 33 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2930} <S60200>.*
38330 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 * KEYWORDS: {aut
38340 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a ocommit mode}.**
38350 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
38360 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 get_autocommit()
38370 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
38380 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a ns non-zero or.*
38390 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 * zero if the gi
383a0 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e ven database con
383b0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 nection is or is
383c0 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d not in autocomm
383d0 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 it mode,.** resp
383e0 65 63 74 69 76 65 6c 79 2e 20 20 41 75 74 6f 63 ectively. Autoc
383f0 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e ommit mode is on
38400 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 by default..**
38410 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 Autocommit mode
38420 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 is disabled by a
38430 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 [BEGIN] stateme
38440 6e 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 nt..** Autocommi
38450 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 t mode is re-ena
38460 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 bled by a [COMMI
38470 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d T] or [ROLLBACK]
38480 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 ..**.** If certa
38490 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f in kinds of erro
384a0 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 rs occur on a st
384b0 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 atement within a
384c0 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 multi-statement
384d0 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 .** transaction
384e0 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e (errors includin
384f0 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c g [SQLITE_FULL],
38500 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c [SQLITE_IOERR],
38510 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 .** [SQLITE_NOME
38520 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 M], [SQLITE_BUSY
38530 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 ], and [SQLITE_I
38540 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 NTERRUPT]) then
38550 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 the.** transacti
38560 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c on might be roll
38570 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 ed back automati
38580 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 cally. The only
38590 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 way to.** find
385a0 6f 75 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 out whether SQLi
385b0 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 te automatically
385c0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 rolled back the
385d0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 transaction aft
385e0 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 er.** an error i
385f0 73 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 s to use this fu
38600 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e nction..**.** IN
38610 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
38620 7b 48 31 32 39 33 31 7d 20 54 68 65 20 5b 73 71 {H12931} The [sq
38630 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f lite3_get_autoco
38640 6d 6d 69 74 28 44 29 5d 20 69 6e 74 65 72 66 61 mmit(D)] interfa
38650 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a ce returns non-z
38660 65 72 6f 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 ero or.**
38670 20 20 20 7a 65 72 6f 20 69 66 20 74 68 65 20 5b zero if the [
38680 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
38690 69 6f 6e 5d 20 44 20 69 73 20 6f 72 20 69 73 20 ion] D is or is
386a0 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 not in autocommi
386b0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f t.** mo
386c0 64 65 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 de, respectively
386d0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33 32 7d ..**.** {H12932}
386e0 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 Autocommit mode
386f0 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c is on by defaul
38700 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33 33 t..**.** {H12933
38710 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 } Autocommit mod
38720 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 e is disabled by
38730 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 5b 42 a successful [B
38740 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e EGIN] statement.
38750 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33 34 7d 20 .**.** {H12934}
38760 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 Autocommit mode
38770 69 73 20 65 6e 61 62 6c 65 64 20 62 79 20 61 20 is enabled by a
38780 73 75 63 63 65 73 73 66 75 6c 20 5b 43 4f 4d 4d successful [COMM
38790 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b IT] or [ROLLBACK
387a0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 ].** st
387b0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 41 atement..**.** A
387c0 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a SSUMPTIONS:.**.*
387d0 2a 20 7b 41 31 32 39 33 36 7d 20 49 66 20 61 6e * {A12936} If an
387e0 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 68 61 other thread cha
387f0 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d nges the autocom
38800 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 mit status of th
38810 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 20 20 e database.**
38820 20 20 20 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f connectio
38830 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 n while this rou
38840 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c tine is running,
38850 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e then the return
38860 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 value.**
38870 20 20 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e is undefined.
38880 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
38890 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 get_autocommit(s
388a0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
388b0 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 CAPI3REF: Find
388c0 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e The Database Han
388d0 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 dle Of A Prepare
388e0 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 d Statement {H13
388f0 31 32 30 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a 120} <S60600>.**
38900 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
38910 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 db_handle interf
38920 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ace returns the
38930 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
38940 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 tion] handle.**
38950 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 to which a [prep
38960 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
38970 62 65 6c 6f 6e 67 73 2e 20 20 54 68 65 20 64 61 belongs. The da
38980 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 72 65 tabase handle re
38990 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 73 71 6c turned by.** sql
389a0 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 ite3_db_handle i
389b0 73 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 s the same datab
389c0 61 73 65 20 68 61 6e 64 6c 65 20 74 68 61 74 20 ase handle that
389d0 77 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 was the first ar
389e0 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 gument.** to the
389f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
38a00 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 e_v2()] call (or
38a10 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 its variants) t
38a20 68 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a hat was used to.
38a30 2a 2a 20 63 72 65 61 74 65 20 74 68 65 20 73 74 ** create the st
38a40 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 atement in the f
38a50 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a irst place..**.*
38a60 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
38a70 0a 2a 2a 20 7b 48 31 33 31 32 33 7d 20 54 68 65 .** {H13123} The
38a80 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e [sqlite3_db_han
38a90 64 6c 65 28 53 29 5d 20 69 6e 74 65 72 66 61 63 dle(S)] interfac
38aa0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e e returns a poin
38ab0 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ter.**
38ac0 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 to the [database
38ad0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73 connection] ass
38ae0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 ociated with the
38af0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 .** [pr
38b00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
38b10 5d 20 53 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 ] S..*/.sqlite3
38b20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 *sqlite3_db_hand
38b30 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a le(sqlite3_stmt*
38b40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
38b50 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 EF: Find the nex
38b60 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 t prepared state
38b70 6d 65 6e 74 20 7b 48 31 33 31 34 30 7d 20 3c 53 ment {H13140} <S
38b80 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 60600>.**.** Thi
38b90 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 s interface retu
38ba0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
38bb0 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 the next [prepa
38bc0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 red statement] a
38bd0 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 fter.** pStmt as
38be0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 sociated with th
38bf0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
38c00 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 49 66 ection] pDb. If
38c10 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a pStmt is NULL.*
38c20 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 * then this inte
38c30 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
38c40 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 pointer to the f
38c50 69 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74 irst prepared st
38c60 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 atement.** assoc
38c70 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64 iated with the d
38c80 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
38c90 6f 6e 20 70 44 62 2e 20 20 49 66 20 6e 6f 20 70 on pDb. If no p
38ca0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
38cb0 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 t.** satisfies t
38cc0 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 he conditions of
38cd0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 this routine, i
38ce0 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a t returns NULL..
38cf0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
38d00 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 34 33 7d :.**.** {H13143}
38d10 20 49 66 20 44 20 69 73 20 61 20 5b 64 61 74 61 If D is a [data
38d20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
38d30 20 74 68 61 74 20 68 6f 6c 64 73 20 6f 6e 65 20 that holds one
38d40 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20 or more.**
38d50 20 20 20 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 unfinalized
38d60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
38d70 65 6e 74 73 5d 20 61 6e 64 20 53 20 69 73 20 61 ents] and S is a
38d80 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 0a 2a NULL pointer,.*
38d90 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 * then
38da0 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 [sqlite3_next_st
38db0 6d 74 28 44 2c 20 53 29 5d 20 72 6f 75 74 69 6e mt(D, S)] routin
38dc0 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 61 e shall return a
38dd0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 pointer.**
38de0 20 20 20 20 20 74 6f 20 6f 6e 65 20 6f 66 20 74 to one of t
38df0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 he prepared stat
38e00 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 ements associate
38e10 64 20 77 69 74 68 20 44 2e 0a 2a 2a 0a 2a 2a 20 d with D..**.**
38e20 7b 48 31 33 31 34 36 7d 20 49 66 20 44 20 69 73 {H13146} If D is
38e30 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e a [database con
38e40 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 68 6f nection] that ho
38e50 6c 64 73 20 6e 6f 20 75 6e 66 69 6e 61 6c 69 7a lds no unfinaliz
38e60 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b ed.** [
38e70 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
38e80 6e 74 73 5d 20 61 6e 64 20 53 20 69 73 20 61 20 nts] and S is a
38e90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 NULL pointer, th
38ea0 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b en.** [
38eb0 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d sqlite3_next_stm
38ec0 74 28 44 2c 20 53 29 5d 20 72 6f 75 74 69 6e 65 t(D, S)] routine
38ed0 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 61 20 shall return a
38ee0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
38ef0 0a 2a 2a 20 7b 48 31 33 31 34 39 7d 20 49 66 20 .** {H13149} If
38f00 53 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 S is a [prepared
38f10 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 74 statement] in t
38f20 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
38f30 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 nection] D.**
38f40 20 20 20 20 20 20 20 61 6e 64 20 53 20 69 73 20 and S is
38f50 6e 6f 74 20 74 68 65 20 6c 61 73 74 20 70 72 65 not the last pre
38f60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
38f70 69 6e 20 44 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 in D, then.**
38f80 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
38f90 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d next_stmt(D, S)]
38fa0 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 routine shall r
38fb0 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 0a eturn a pointer.
38fc0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 ** to t
38fd0 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65 64 he next prepared
38fe0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 44 20 statement in D
38ff0 61 66 74 65 72 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b after S..**.** {
39000 48 31 33 31 35 32 7d 20 49 66 20 53 20 69 73 20 H13152} If S is
39010 74 68 65 20 6c 61 73 74 20 5b 70 72 65 70 61 72 the last [prepar
39020 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e ed statement] in
39030 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
39040 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
39050 63 74 69 6f 6e 5d 20 44 20 74 68 65 6e 20 74 68 ction] D then th
39060 65 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f e [sqlite3_next_
39070 73 74 6d 74 28 44 2c 20 53 29 5d 0a 2a 2a 20 20 stmt(D, S)].**
39080 20 20 20 20 20 20 20 20 72 6f 75 74 69 6e 65 20 routine
39090 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 61 20 4e shall return a N
390a0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a ULL pointer..**.
390b0 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a ** ASSUMPTIONS:.
390c0 2a 2a 0a 2a 2a 20 7b 41 31 33 31 35 34 7d 20 54 **.** {A13154} T
390d0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
390e0 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 nection] pointer
390f0 20 44 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a D in a call to.
39100 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
39110 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 ite3_next_stmt(D
39120 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 ,S)] must refer
39130 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 to an open datab
39140 61 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ase.**
39150 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 connection and i
39160 6e 20 70 61 72 74 69 63 75 6c 61 72 20 6d 75 73 n particular mus
39170 74 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 t not be a NULL
39180 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 pointer..*/.sqli
39190 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 te3_stmt *sqlite
391a0 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 3_next_stmt(sqli
391b0 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 te3 *pDb, sqlite
391c0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 3_stmt *pStmt);.
391d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
391e0 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c Commit And Roll
391f0 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f back Notificatio
39200 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 n Callbacks {H12
39210 39 35 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 950} <S60400>.**
39220 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
39230 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e commit_hook() in
39240 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 terface register
39250 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 s a callback.**
39260 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 function to be i
39270 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 nvoked whenever
39280 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 a transaction is
39290 20 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 committed..** A
392a0 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 ny callback set
392b0 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 by a previous ca
392c0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ll to sqlite3_co
392d0 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 mmit_hook().** f
392e0 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 or the same data
392f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
39300 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a is overridden..*
39310 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f * The sqlite3_ro
39320 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e llback_hook() in
39330 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 terface register
39340 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 s a callback.**
39350 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 function to be i
39360 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 nvoked whenever
39370 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 a transaction is
39380 20 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 committed..** A
39390 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 ny callback set
393a0 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 by a previous ca
393b0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ll to sqlite3_co
393c0 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 mmit_hook().** f
393d0 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 or the same data
393e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
393f0 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a is overridden..*
39400 2a 20 54 68 65 20 70 41 72 67 20 61 72 67 75 6d * The pArg argum
39410 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 68 ent is passed th
39420 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c rough to the cal
39430 6c 62 61 63 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 lback..** If the
39440 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 callback on a c
39450 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 ommit hook funct
39460 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d ion returns non-
39470 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 zero,.** then th
39480 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 e commit is conv
39490 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c erted into a rol
394a0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 lback..**.** If
394b0 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e another function
394c0 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 was previously
394d0 72 65 67 69 73 74 65 72 65 64 2c 20 69 74 73 0a registered, its.
394e0 2a 2a 20 70 41 72 67 20 76 61 6c 75 65 20 69 73 ** pArg value is
394f0 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 returned. Othe
39500 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 rwise NULL is re
39510 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 turned..**.** Th
39520 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 e callback imple
39530 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e mentation must n
39540 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 ot do anything t
39550 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a hat will modify.
39560 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ** the database
39570 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 connection that
39580 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c invoked the call
39590 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f back. Any actio
395a0 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 ns.** to modify
395b0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
395c0 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 nection must be
395d0 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 deferred until a
395e0 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 fter the.** comp
395f0 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 letion of the [s
39600 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 qlite3_step()] c
39610 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 all that trigger
39620 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a ed the commit.**
39630 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f or rollback hoo
39640 6b 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 k in the first p
39650 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 lace..** Note th
39660 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 at [sqlite3_prep
39670 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 are_v2()] and [s
39680 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 qlite3_step()] b
39690 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 oth modify their
396a0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
396b0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 nections for the
396c0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 meaning of "mod
396d0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 ify" in this par
396e0 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 agraph..**.** Re
396f0 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c gistering a NULL
39700 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c function disabl
39710 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e es the callback.
39720 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 .**.** For the p
39730 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 urposes of this
39740 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 API, a transacti
39750 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 on is said to ha
39760 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 ve been.** rolle
39770 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 d back if an exp
39780 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 licit "ROLLBACK"
39790 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 statement is ex
397a0 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e ecuted, or.** an
397b0 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 error or constr
397c0 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 aint causes an i
397d0 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b mplicit rollback
397e0 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 54 68 to occur..** Th
397f0 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 e rollback callb
39800 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b ack is not invok
39810 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 ed if a transact
39820 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 ion is.** automa
39830 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 tically rolled b
39840 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 ack because the
39850 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
39860 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a ion is closed..*
39870 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 * The rollback c
39880 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 allback is not i
39890 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e nvoked if a tran
398a0 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f saction is.** ro
398b0 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 lled back becaus
398c0 65 20 61 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 e a commit callb
398d0 61 63 6b 20 72 65 74 75 72 6e 65 64 20 6e 6f 6e ack returned non
398e0 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e -zero..** <todo>
398f0 20 43 68 65 63 6b 20 6f 6e 20 74 68 69 73 20 3c Check on this <
39900 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 /todo>.**.** INV
39910 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
39920 48 31 32 39 35 31 7d 20 54 68 65 20 5b 73 71 6c H12951} The [sql
39930 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b ite3_commit_hook
39940 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 (D,F,P)] interfa
39950 63 65 20 72 65 67 69 73 74 65 72 73 20 74 68 65 ce registers the
39960 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c .** cal
39970 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 46 lback function F
39980 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 to be invoked w
39990 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 ith argument P w
399a0 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 henever.**
399b0 20 20 20 20 61 20 74 72 61 6e 73 61 63 74 69 6f a transactio
399c0 6e 20 63 6f 6d 6d 69 74 73 20 6f 6e 20 74 68 65 n commits on the
399d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
399e0 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 ction] D..**.**
399f0 7b 48 31 32 39 35 32 7d 20 54 68 65 20 5b 73 71 {H12952} The [sq
39a00 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f lite3_commit_hoo
39a10 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 k(D,F,P)] interf
39a20 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ace returns the
39a30 50 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 P argument.**
39a40 20 20 20 20 20 20 20 66 72 6f 6d 20 74 68 65 20 from the
39a50 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 77 69 previous call wi
39a60 74 68 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 th the same [dat
39a70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
39a80 5d 20 44 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 ] D,.**
39a90 20 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 or NULL on the
39aa0 66 69 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 61 first call for a
39ab0 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 particular data
39ac0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
39ad0 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 33 D..**.** {H12953
39ae0 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b } Each call to [
39af0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 sqlite3_commit_h
39b00 6f 6f 6b 28 29 5d 20 6f 76 65 72 77 72 69 74 65 ook()] overwrite
39b10 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a s the callback.*
39b20 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 * regis
39b30 74 65 72 65 64 20 62 79 20 70 72 69 6f 72 20 63 tered by prior c
39b40 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 alls..**.** {H12
39b50 39 35 34 7d 20 49 66 20 74 68 65 20 46 20 61 72 954} If the F ar
39b60 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 gument to [sqlit
39b70 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 e3_commit_hook(D
39b80 2c 46 2c 50 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a ,F,P)] is NULL.*
39b90 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 * then
39ba0 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 the commit hook
39bb0 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e 63 callback is canc
39bc0 65 6c 65 64 20 61 6e 64 20 6e 6f 20 63 61 6c 6c eled and no call
39bd0 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 back.**
39be0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e is invoked when
39bf0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 a transaction c
39c00 6f 6d 6d 69 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ommits..**.** {H
39c10 31 32 39 35 35 7d 20 49 66 20 74 68 65 20 63 6f 12955} If the co
39c20 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 mmit callback re
39c30 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 74 turns non-zero t
39c40 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 hen the commit i
39c50 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f s.** co
39c60 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 nverted into a r
39c70 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b ollback..**.** {
39c80 48 31 32 39 36 31 7d 20 54 68 65 20 5b 73 71 6c H12961} The [sql
39c90 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f ite3_rollback_ho
39ca0 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 ok(D,F,P)] inter
39cb0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 74 face registers t
39cc0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 he.** c
39cd0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
39ce0 20 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 F to be invoked
39cf0 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 with argument P
39d00 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 whenever.**
39d10 20 20 20 20 20 20 61 20 74 72 61 6e 73 61 63 74 a transact
39d20 69 6f 6e 20 72 6f 6c 6c 73 20 62 61 63 6b 20 6f ion rolls back o
39d30 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 n the [database
39d40 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a connection] D..*
39d50 2a 0a 2a 2a 20 7b 48 31 32 39 36 32 7d 20 54 68 *.** {H12962} Th
39d60 65 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 e [sqlite3_rollb
39d70 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d ack_hook(D,F,P)]
39d80 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
39d90 6e 73 20 74 68 65 20 50 0a 2a 2a 20 20 20 20 20 ns the P.**
39da0 20 20 20 20 20 61 72 67 75 6d 65 6e 74 20 66 72 argument fr
39db0 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 om the previous
39dc0 63 61 6c 6c 20 77 69 74 68 20 74 68 65 20 73 61 call with the sa
39dd0 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b me.** [
39de0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
39df0 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 ion] D, or NULL
39e00 6f 6e 20 74 68 65 20 66 69 72 73 74 20 63 61 6c on the first cal
39e10 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f l.** fo
39e20 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 r a particular d
39e30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
39e40 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 on D..**.** {H12
39e50 39 36 33 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 963} Each call t
39e60 6f 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 o [sqlite3_rollb
39e70 61 63 6b 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 ack_hook()] over
39e80 77 72 69 74 65 73 20 74 68 65 20 63 61 6c 6c 62 writes the callb
39e90 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ack.**
39ea0 72 65 67 69 73 74 65 72 65 64 20 62 79 20 70 72 registered by pr
39eb0 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a ior calls..**.**
39ec0 20 7b 48 31 32 39 36 34 7d 20 49 66 20 74 68 65 {H12964} If the
39ed0 20 46 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b F argument to [
39ee0 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b sqlite3_rollback
39ef0 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 73 _hook(D,F,P)] is
39f00 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 NULL.**
39f10 20 20 74 68 65 6e 20 74 68 65 20 72 6f 6c 6c 62 then the rollb
39f20 61 63 6b 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 ack hook callbac
39f30 6b 20 69 73 20 63 61 6e 63 65 6c 65 64 20 61 6e k is canceled an
39f40 64 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a d no callback.**
39f50 20 20 20 20 20 20 20 20 20 20 69 73 20 69 6e 76 is inv
39f60 6f 6b 65 64 20 77 68 65 6e 20 61 20 74 72 61 6e oked when a tran
39f70 73 61 63 74 69 6f 6e 20 72 6f 6c 6c 73 20 62 61 saction rolls ba
39f80 63 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c ck..*/.void *sql
39f90 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b ite3_commit_hook
39fa0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a (sqlite3*, int(*
39fb0 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 )(void*), void*)
39fc0 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f ;.void *sqlite3_
39fd0 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 rollback_hook(sq
39fe0 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 lite3*, void(*)(
39ff0 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b void *), void*);
3a000 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
3a010 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f : Data Change No
3a020 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 tification Callb
3a030 61 63 6b 73 20 7b 48 31 32 39 37 30 7d 20 3c 53 acks {H12970} <S
3a040 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 60400>.**.** The
3a050 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f sqlite3_update_
3a060 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 hook() interface
3a070 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c registers a cal
3a080 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a lback function.*
3a090 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 * with the [data
3a0a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
3a0b0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 identified by t
3a0c0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
3a0d0 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b t.** to be invok
3a0e0 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f ed whenever a ro
3a0f0 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e w is updated, in
3a100 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 serted or delete
3a110 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 d..** Any callba
3a120 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 ck set by a prev
3a130 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 ious call to thi
3a140 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f s function.** fo
3a150 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 r the same datab
3a160 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
3a170 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a s overridden..**
3a180 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 .** The second a
3a190 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 rgument is a poi
3a1a0 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 nter to the func
3a1b0 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 tion to invoke w
3a1c0 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 hen a.** row is
3a1d0 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 updated, inserte
3a1e0 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a d or deleted..**
3a1f0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
3a200 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 ent to the callb
3a210 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 ack is a copy of
3a220 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d the third argum
3a230 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 ent.** to sqlite
3a240 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 3_update_hook().
3a250 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 .** The second c
3a260 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 allback argument
3a270 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 is one of [SQLI
3a280 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c TE_INSERT], [SQL
3a290 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 ITE_DELETE],.**
3a2a0 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 or [SQLITE_UPDAT
3a2b0 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e E], depending on
3a2c0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 the operation t
3a2d0 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63 hat caused the c
3a2e0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 allback.** to be
3a2f0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 54 68 65 invoked..** The
3a300 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 third and fourt
3a310 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 h arguments to t
3a320 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 he callback cont
3a330 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 ain pointers to
3a340 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 the.** database
3a350 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 and table name c
3a360 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66 ontaining the af
3a370 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 54 fected row..** T
3a380 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 he final callbac
3a390 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 k parameter is t
3a3a0 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 he rowid of the
3a3b0 72 6f 77 2e 20 49 6e 20 74 68 65 20 63 61 73 65 row. In the case
3a3c0 20 6f 66 0a 2a 2a 20 61 6e 20 75 70 64 61 74 65 of.** an update
3a3d0 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 72 6f , this is the ro
3a3e0 77 69 64 20 61 66 74 65 72 20 74 68 65 20 75 70 wid after the up
3a3f0 64 61 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65 date takes place
3a400 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 ..**.** The upda
3a410 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 te hook is not i
3a420 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 nvoked when inte
3a430 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c rnal system tabl
3a440 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 es are.** modifi
3a450 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f ed (i.e. sqlite_
3a460 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 master and sqlit
3a470 65 5f 73 65 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a e_sequence)..**.
3a480 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 6f ** The update ho
3a490 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ok implementatio
3a4a0 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e n must not do an
3a4b0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c ything that will
3a4c0 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 modify.** the d
3a4d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
3a4e0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 on that invoked
3a4f0 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e the update hook.
3a500 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a Any actions.**
3a510 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 to modify the d
3a520 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
3a530 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 on must be defer
3a540 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 red until after
3a550 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f the.** completio
3a560 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 n of the [sqlite
3a570 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 3_step()] call t
3a580 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 hat triggered th
3a590 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a e update hook..*
3a5a0 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c * Note that [sql
3a5b0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
3a5c0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
3a5d0 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 step()] both mod
3a5e0 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 ify their.** dat
3a5f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
3a600 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e s for the meanin
3a610 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e g of "modify" in
3a620 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e this paragraph.
3a630 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 .**.** If anothe
3a640 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 r function was p
3a650 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 reviously regist
3a660 65 72 65 64 2c 20 69 74 73 20 70 41 72 67 20 76 ered, its pArg v
3a670 61 6c 75 65 0a 2a 2a 20 69 73 20 72 65 74 75 72 alue.** is retur
3a680 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 ned. Otherwise
3a690 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 NULL is returned
3a6a0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
3a6b0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 37 TS:.**.** {H1297
3a6c0 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 1} The [sqlite3_
3a6d0 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c update_hook(D,F,
3a6e0 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 P)] interface ca
3a6f0 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 uses the callbac
3a700 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 k.** fu
3a710 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 nction F to be i
3a720 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 69 72 73 nvoked with firs
3a730 74 20 70 61 72 61 6d 65 74 65 72 20 50 20 77 68 t parameter P wh
3a740 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 enever.**
3a750 20 20 20 61 20 74 61 62 6c 65 20 72 6f 77 20 69 a table row i
3a760 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 s modified, inse
3a770 72 74 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 rted, or deleted
3a780 20 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 on.**
3a790 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
3a7a0 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a nnection] D..**.
3a7b0 2a 2a 20 7b 48 31 32 39 37 33 7d 20 54 68 65 20 ** {H12973} The
3a7c0 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f [sqlite3_update_
3a7d0 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 hook(D,F,P)] int
3a7e0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 erface returns t
3a7f0 68 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 he value.**
3a800 20 20 20 20 20 6f 66 20 50 20 66 6f 72 20 74 68 of P for th
3a810 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 e previous call
3a820 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 on the same [dat
3a830 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
3a840 5d 20 44 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 ] D,.**
3a850 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 20 74 68 65 or NULL for the
3a860 20 66 69 72 73 74 20 63 61 6c 6c 2e 0a 2a 2a 0a first call..**.
3a870 2a 2a 20 7b 48 31 32 39 37 35 7d 20 49 66 20 74 ** {H12975} If t
3a880 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 63 he update hook c
3a890 61 6c 6c 62 61 63 6b 20 46 20 69 6e 20 5b 73 71 allback F in [sq
3a8a0 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f lite3_update_hoo
3a8b0 6b 28 44 2c 46 2c 50 29 5d 0a 2a 2a 20 20 20 20 k(D,F,P)].**
3a8c0 20 20 20 20 20 20 69 73 20 4e 55 4c 4c 20 74 68 is NULL th
3a8d0 65 6e 20 74 68 65 20 6e 6f 20 75 70 64 61 74 65 en the no update
3a8e0 20 63 61 6c 6c 62 61 63 6b 73 20 61 72 65 20 6d callbacks are m
3a8f0 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 ade..**.** {H129
3a900 37 37 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 77} Each call to
3a910 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 [sqlite3_update
3a920 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 6f 76 _hook(D,F,P)] ov
3a930 65 72 72 69 64 65 73 20 70 72 69 6f 72 20 63 61 errides prior ca
3a940 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 lls.**
3a950 74 6f 20 74 68 65 20 73 61 6d 65 20 69 6e 74 65 to the same inte
3a960 72 66 61 63 65 20 6f 6e 20 74 68 65 20 73 61 6d rface on the sam
3a970 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
3a980 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a ection] D..**.**
3a990 20 7b 48 31 32 39 37 39 7d 20 54 68 65 20 75 70 {H12979} The up
3a9a0 64 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 date hook callba
3a9b0 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 ck is not invoke
3a9c0 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 d when internal
3a9d0 73 79 73 74 65 6d 0a 2a 2a 20 20 20 20 20 20 20 system.**
3a9e0 20 20 20 74 61 62 6c 65 73 20 73 75 63 68 20 61 tables such a
3a9f0 73 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 s sqlite_master
3aa00 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 and sqlite_seque
3aa10 6e 63 65 20 61 72 65 20 6d 6f 64 69 66 69 65 64 nce are modified
3aa20 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 38 31 7d ..**.** {H12981}
3aa30 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 The second para
3aa40 6d 65 74 65 72 20 74 6f 20 74 68 65 20 75 70 64 meter to the upd
3aa50 61 74 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 ate callback.**
3aa60 20 20 20 20 20 20 20 20 20 69 73 20 6f 6e 65 20 is one
3aa70 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 of [SQLITE_INSER
3aa80 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 T], [SQLITE_DELE
3aa90 54 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 TE] or [SQLITE_U
3aaa0 50 44 41 54 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 PDATE],.**
3aab0 20 20 20 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e depending on
3aac0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 the operation t
3aad0 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63 hat caused the c
3aae0 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 69 6e allback to be in
3aaf0 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 voked..**.** {H1
3ab00 32 39 38 33 7d 20 54 68 65 20 74 68 69 72 64 20 2983} The third
3ab10 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d and fourth argum
3ab20 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c ents to the call
3ab30 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 back contain poi
3ab40 6e 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 nters.**
3ab50 20 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e to zero-termin
3ab60 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e ated UTF-8 strin
3ab70 67 73 20 77 68 69 63 68 20 61 72 65 20 74 68 65 gs which are the
3ab80 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a names of the.**
3ab90 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61 databa
3aba0 73 65 20 61 6e 64 20 74 61 62 6c 65 20 74 68 61 se and table tha
3abb0 74 20 69 73 20 62 65 69 6e 67 20 75 70 64 61 74 t is being updat
3abc0 65 64 2e 0a 0a 2a 2a 20 7b 48 31 32 39 38 35 7d ed...** {H12985}
3abd0 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 The final callb
3abe0 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 ack parameter is
3abf0 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 the rowid of th
3ac00 65 20 72 6f 77 20 61 66 74 65 72 0a 2a 2a 20 20 e row after.**
3ac10 20 20 20 20 20 20 20 20 74 68 65 20 63 68 61 6e the chan
3ac20 67 65 20 6f 63 63 75 72 73 2e 0a 2a 2f 0a 76 6f ge occurs..*/.vo
3ac30 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64 61 id *sqlite3_upda
3ac40 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 te_hook(. sqlit
3ac50 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 e3*, . void(*)(
3ac60 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72 void *,int ,char
3ac70 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f const *,char co
3ac80 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e nst *,sqlite3_in
3ac90 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b t64),. void*.);
3aca0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
3acb0 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 : Enable Or Disa
3acc0 62 6c 65 20 53 68 61 72 65 64 20 50 61 67 65 72 ble Shared Pager
3acd0 20 43 61 63 68 65 20 7b 48 31 30 33 33 30 7d 20 Cache {H10330}
3ace0 3c 53 33 30 39 30 30 3e 0a 2a 2a 20 4b 45 59 57 <S30900>.** KEYW
3acf0 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 20 63 61 ORDS: {shared ca
3ad00 63 68 65 7d 20 7b 73 68 61 72 65 64 20 63 61 63 che} {shared cac
3ad10 68 65 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 he mode}.**.** T
3ad20 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 his routine enab
3ad30 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 les or disables
3ad40 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74 the sharing of t
3ad50 68 65 20 64 61 74 61 62 61 73 65 20 63 61 63 68 he database cach
3ad60 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20 e.** and schema
3ad70 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 data structures
3ad80 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62 61 73 between [databas
3ad90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 63 e connection | c
3ada0 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74 onnections].** t
3adb0 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 o the same datab
3adc0 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69 73 20 ase. Sharing is
3add0 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 enabled if the a
3ade0 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 0a rgument is true.
3adf0 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 ** and disabled
3ae00 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 if the argument
3ae10 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 is false..**.**
3ae20 43 61 63 68 65 20 73 68 61 72 69 6e 67 20 69 73 Cache sharing is
3ae30 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 73 enabled and dis
3ae40 61 62 6c 65 64 20 66 6f 72 20 61 6e 20 65 6e 74 abled for an ent
3ae50 69 72 65 20 70 72 6f 63 65 73 73 2e 20 7b 45 4e ire process. {EN
3ae60 44 7d 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 D}.** This is a
3ae70 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c change as of SQL
3ae80 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e ite version 3.5.
3ae90 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 0. In prior vers
3aea0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a ions of SQLite,.
3aeb0 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20 65 ** sharing was e
3aec0 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c nabled or disabl
3aed0 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 ed for each thre
3aee0 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a ad separately..*
3aef0 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68 65 20 73 *.** The cache s
3af00 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 haring mode set
3af10 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 by this interfac
3af20 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75 e effects all su
3af30 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c bsequent.** call
3af40 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 s to [sqlite3_op
3af50 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f en()], [sqlite3_
3af60 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 open_v2()], and
3af70 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 [sqlite3_open16(
3af80 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 )]..** Existing
3af90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
3afa0 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 ions continue us
3afb0 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f e the sharing mo
3afc0 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69 de.** that was i
3afd0 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65 20 n effect at the
3afe0 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f time they were o
3aff0 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 pened..**.** Vir
3b000 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e tual tables cann
3b010 6f 74 20 62 65 20 75 73 65 64 20 77 69 74 68 20 ot be used with
3b020 61 20 73 68 61 72 65 64 20 63 61 63 68 65 2e 20 a shared cache.
3b030 20 57 68 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20 When shared.**
3b040 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 cache is enabled
3b050 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 , the [sqlite3_c
3b060 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 reate_module()]
3b070 41 50 49 20 75 73 65 64 20 74 6f 20 72 65 67 69 API used to regi
3b080 73 74 65 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20 ster.** virtual
3b090 74 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61 tables will alwa
3b0a0 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 ys return an err
3b0b0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 or..**.** This r
3b0c0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b outine returns [
3b0d0 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 SQLITE_OK] if sh
3b0e0 61 72 65 64 20 63 61 63 68 65 20 77 61 73 20 65 ared cache was e
3b0f0 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c nabled or disabl
3b100 65 64 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c ed.** successful
3b110 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 ly. An [error c
3b120 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 ode] is returned
3b130 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a otherwise..**.*
3b140 2a 20 53 68 61 72 65 64 20 63 61 63 68 65 20 69 * Shared cache i
3b150 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 s disabled by de
3b160 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69 73 20 fault. But this
3b170 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a might change in.
3b180 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 ** future releas
3b190 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 es of SQLite. A
3b1a0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 pplications that
3b1b0 20 63 61 72 65 20 61 62 6f 75 74 20 73 68 61 72 care about shar
3b1c0 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74 ed.** cache sett
3b1d0 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69 ing should set i
3b1e0 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a t explicitly..**
3b1f0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
3b200 2a 2a 0a 2a 2a 20 7b 48 31 30 33 33 31 7d 20 41 **.** {H10331} A
3b210 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f successful invo
3b220 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 cation of [sqlit
3b230 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 e3_enable_shared
3b240 5f 63 61 63 68 65 28 42 29 5d 0a 2a 2a 20 20 20 _cache(B)].**
3b250 20 20 20 20 20 20 20 77 69 6c 6c 20 65 6e 61 62 will enab
3b260 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 73 68 le or disable sh
3b270 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 20 ared cache mode
3b280 66 6f 72 20 61 6e 79 20 73 75 62 73 65 71 75 65 for any subseque
3b290 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 ntly.**
3b2a0 20 63 72 65 61 74 65 64 20 5b 64 61 74 61 62 61 created [databa
3b2b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 se connection] i
3b2c0 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 n the same proce
3b2d0 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 33 33 ss..**.** {H1033
3b2e0 36 7d 20 57 68 65 6e 20 73 68 61 72 65 64 20 63 6} When shared c
3b2f0 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 2c ache is enabled,
3b300 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 the [sqlite3_cr
3b310 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 0a 2a eate_module()].*
3b320 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 * inter
3b330 66 61 63 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 face will always
3b340 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 return an error
3b350 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 33 33 37 7d ..**.** {H10337}
3b360 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e The [sqlite3_en
3b370 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 able_shared_cach
3b380 65 28 42 29 5d 20 69 6e 74 65 72 66 61 63 65 20 e(B)] interface
3b390 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 returns.**
3b3a0 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 [SQLITE_OK]
3b3b0 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65 20 if shared cache
3b3c0 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 was enabled or d
3b3d0 69 73 61 62 6c 65 64 20 73 75 63 63 65 73 73 66 isabled successf
3b3e0 75 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 ully..**.** {H10
3b3f0 33 33 39 7d 20 53 68 61 72 65 64 20 63 61 63 68 339} Shared cach
3b400 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 e is disabled by
3b410 20 64 65 66 61 75 6c 74 2e 0a 2a 2f 0a 69 6e 74 default..*/.int
3b420 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f sqlite3_enable_
3b430 73 68 61 72 65 64 5f 63 61 63 68 65 28 69 6e 74 shared_cache(int
3b440 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
3b450 45 46 3a 20 41 74 74 65 6d 70 74 20 54 6f 20 46 EF: Attempt To F
3b460 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72 79 20 ree Heap Memory
3b470 7b 48 31 37 33 34 30 7d 20 3c 53 33 30 32 32 30 {H17340} <S30220
3b480 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 >.**.** The sqli
3b490 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f te3_release_memo
3b4a0 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 ry() interface a
3b4b0 74 74 65 6d 70 74 73 20 74 6f 20 66 72 65 65 20 ttempts to free
3b4c0 4e 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 68 65 N bytes.** of he
3b4d0 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 ap memory by dea
3b4e0 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 llocating non-es
3b4f0 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 20 61 sential memory a
3b500 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 llocations.** he
3b510 6c 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61 ld by the databa
3b520 73 65 20 6c 69 62 72 61 72 79 2e 20 7b 45 4e 44 se library. {END
3b530 7d 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 20 74 } Memory used t
3b540 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73 65 o cache database
3b550 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 69 6d 70 .** pages to imp
3b560 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 rove performance
3b570 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f is an example o
3b580 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 f non-essential
3b590 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 73 71 6c 69 74 memory..** sqlit
3b5a0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 e3_release_memor
3b5b0 79 28 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 y() returns the
3b5c0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
3b5d0 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 0a actually freed,.
3b5e0 2a 2a 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 ** which might b
3b5f0 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 20 74 e more or less t
3b600 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 han the amount r
3b610 65 71 75 65 73 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 equested..**.**
3b620 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
3b630 2a 20 7b 48 31 37 33 34 31 7d 20 54 68 65 20 5b * {H17341} The [
3b640 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f sqlite3_release_
3b650 6d 65 6d 6f 72 79 28 4e 29 5d 20 69 6e 74 65 72 memory(N)] inter
3b660 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f face attempts to
3b670 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 65 .** fre
3b680 65 20 4e 20 62 79 74 65 73 20 6f 66 20 68 65 61 e N bytes of hea
3b690 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c p memory by deal
3b6a0 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 locating non-ess
3b6b0 65 6e 74 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 ential.**
3b6c0 20 20 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 memory alloca
3b6d0 74 69 6f 6e 73 20 68 65 6c 64 20 62 79 20 74 68 tions held by th
3b6e0 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 61 e database libra
3b6f0 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 33 34 ry..**.** {H1634
3b700 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 2} The [sqlite3_
3b710 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 4e release_memory(N
3b720 29 5d 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e )] returns the n
3b730 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 umber.**
3b740 20 20 6f 66 20 62 79 74 65 73 20 61 63 74 75 61 of bytes actua
3b750 6c 6c 79 20 66 72 65 65 64 2c 20 77 68 69 63 68 lly freed, which
3b760 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f might be more o
3b770 72 20 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 r less.**
3b780 20 20 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 than the amou
3b790 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2f nt requested..*/
3b7a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c .int sqlite3_rel
3b7b0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 ease_memory(int)
3b7c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
3b7d0 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 F: Impose A Limi
3b7e0 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 20 7b t On Heap Size {
3b7f0 48 31 37 33 35 30 7d 20 3c 53 33 30 32 32 30 3e H17350} <S30220>
3b800 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
3b810 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d e3_soft_heap_lim
3b820 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 70 it() interface p
3b830 6c 61 63 65 73 20 61 20 22 73 6f 66 74 22 20 6c laces a "soft" l
3b840 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 61 imit.** on the a
3b850 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 mount of heap me
3b860 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 mory that may be
3b870 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 allocated by SQ
3b880 4c 69 74 65 2e 0a 2a 2a 20 49 66 20 61 6e 20 69 Lite..** If an i
3b890 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 nternal allocati
3b8a0 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 20 on is requested
3b8b0 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65 65 that would excee
3b8c0 64 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 68 65 d the.** soft he
3b8d0 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74 ap limit, [sqlit
3b8e0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 e3_release_memor
3b8f0 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20 y()] is invoked
3b900 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 one or.** more t
3b910 69 6d 65 73 20 74 6f 20 66 72 65 65 20 75 70 20 imes to free up
3b920 73 6f 6d 65 20 73 70 61 63 65 20 62 65 66 6f 72 some space befor
3b930 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e e the allocation
3b940 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a is performed..*
3b950 2a 0a 2a 2a 20 54 68 65 20 6c 69 6d 69 74 20 69 *.** The limit i
3b960 73 20 63 61 6c 6c 65 64 20 22 73 6f 66 74 22 2c s called "soft",
3b970 20 62 65 63 61 75 73 65 20 69 66 20 5b 73 71 6c because if [sql
3b980 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d ite3_release_mem
3b990 6f 72 79 28 29 5d 0a 2a 2a 20 63 61 6e 6e 6f 74 ory()].** cannot
3b9a0 20 66 72 65 65 20 73 75 66 66 69 63 69 65 6e 74 free sufficient
3b9b0 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65 76 65 memory to preve
3b9c0 6e 74 20 74 68 65 20 6c 69 6d 69 74 20 66 72 6f nt the limit fro
3b9d0 6d 20 62 65 69 6e 67 20 65 78 63 65 65 64 65 64 m being exceeded
3b9e0 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 ,.** the memory
3b9f0 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 79 is allocated any
3ba00 77 61 79 20 61 6e 64 20 74 68 65 20 63 75 72 72 way and the curr
3ba10 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 ent operation pr
3ba20 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 oceeds..**.** A
3ba30 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f negative or zero
3ba40 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61 value for N mea
3ba50 6e 73 20 74 68 61 74 20 74 68 65 72 65 20 69 73 ns that there is
3ba60 20 6e 6f 20 73 6f 66 74 20 68 65 61 70 20 6c 69 no soft heap li
3ba70 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 mit and.** [sqli
3ba80 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f te3_release_memo
3ba90 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 ry()] will only
3baa0 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d be called when m
3bab0 65 6d 6f 72 79 20 69 73 20 65 78 68 61 75 73 74 emory is exhaust
3bac0 65 64 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 ed..** The defau
3bad0 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 lt value for the
3bae0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 soft heap limit
3baf0 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 is zero..**.**
3bb00 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 62 SQLite makes a b
3bb10 65 73 74 20 65 66 66 6f 72 74 20 74 6f 20 68 6f est effort to ho
3bb20 6e 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 nor the soft hea
3bb30 70 20 6c 69 6d 69 74 2e 0a 2a 2a 20 42 75 74 20 p limit..** But
3bb40 69 66 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 if the soft heap
3bb50 20 6c 69 6d 69 74 20 63 61 6e 6e 6f 74 20 62 65 limit cannot be
3bb60 20 68 6f 6e 6f 72 65 64 2c 20 65 78 65 63 75 74 honored, execut
3bb70 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 ion will.** cont
3bb80 69 6e 75 65 20 77 69 74 68 6f 75 74 20 65 72 72 inue without err
3bb90 6f 72 20 6f 72 20 6e 6f 74 69 66 69 63 61 74 69 or or notificati
3bba0 6f 6e 2e 20 20 54 68 69 73 20 69 73 20 77 68 79 on. This is why
3bbb0 20 74 68 65 20 6c 69 6d 69 74 20 69 73 0a 2a 2a the limit is.**
3bbc0 20 63 61 6c 6c 65 64 20 61 20 22 73 6f 66 74 22 called a "soft"
3bbd0 20 6c 69 6d 69 74 2e 20 20 49 74 20 69 73 20 61 limit. It is a
3bbe0 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a dvisory only..**
3bbf0 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c .** Prior to SQL
3bc00 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e ite version 3.5.
3bc10 30 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 0, this routine
3bc20 6f 6e 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65 64 only constrained
3bc30 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 the memory.** a
3bc40 6c 6c 6f 63 61 74 65 64 20 62 79 20 61 20 73 69 llocated by a si
3bc50 6e 67 6c 65 20 74 68 72 65 61 64 20 2d 20 74 68 ngle thread - th
3bc60 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e e same thread in
3bc70 20 77 68 69 63 68 20 74 68 69 73 20 72 6f 75 74 which this rout
3bc80 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42 65 ine.** runs. Be
3bc90 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c ginning with SQL
3bca0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e ite version 3.5.
3bcb0 30 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 0, the soft heap
3bcc0 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70 70 limit is.** app
3bcd0 6c 69 65 64 20 74 6f 20 61 6c 6c 20 74 68 72 65 lied to all thre
3bce0 61 64 73 2e 20 54 68 65 20 76 61 6c 75 65 20 73 ads. The value s
3bcf0 70 65 63 69 66 69 65 64 20 66 6f 72 20 74 68 65 pecified for the
3bd00 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 soft heap limit
3bd10 0a 2a 2a 20 69 73 20 61 6e 20 75 70 70 65 72 20 .** is an upper
3bd20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 74 6f 74 bound on the tot
3bd30 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 al memory alloca
3bd40 74 69 6f 6e 20 66 6f 72 20 61 6c 6c 20 74 68 72 tion for all thr
3bd50 65 61 64 73 2e 20 49 6e 0a 2a 2a 20 76 65 72 73 eads. In.** vers
3bd60 69 6f 6e 20 33 2e 35 2e 30 20 74 68 65 72 65 20 ion 3.5.0 there
3bd70 69 73 20 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20 is no mechanism
3bd80 66 6f 72 20 6c 69 6d 69 74 69 6e 67 20 74 68 65 for limiting the
3bd90 20 68 65 61 70 20 75 73 61 67 65 20 66 6f 72 0a heap usage for.
3bda0 2a 2a 20 69 6e 64 69 76 69 64 75 61 6c 20 74 68 ** individual th
3bdb0 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 reads..**.** INV
3bdc0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
3bdd0 48 31 36 33 35 31 7d 20 54 68 65 20 5b 73 71 6c H16351} The [sql
3bde0 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c ite3_soft_heap_l
3bdf0 69 6d 69 74 28 4e 29 5d 20 69 6e 74 65 72 66 61 imit(N)] interfa
3be00 63 65 20 70 6c 61 63 65 73 20 61 20 73 6f 66 74 ce places a soft
3be10 20 6c 69 6d 69 74 0a 2a 2a 20 20 20 20 20 20 20 limit.**
3be20 20 20 20 6f 66 20 4e 20 62 79 74 65 73 20 6f 6e of N bytes on
3be30 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 the amount of h
3be40 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 eap memory that
3be50 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 may be allocated
3be60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73 69 .** usi
3be70 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c ng [sqlite3_mall
3be80 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 oc()] or [sqlite
3be90 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 61 74 20 3_realloc()] at
3bea0 61 6e 79 20 70 6f 69 6e 74 0a 2a 2a 20 20 20 20 any point.**
3beb0 20 20 20 20 20 20 69 6e 20 74 69 6d 65 2e 0a 2a in time..*
3bec0 2a 0a 2a 2a 20 7b 48 31 36 33 35 32 7d 20 49 66 *.** {H16352} If
3bed0 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 a call to [sqli
3bee0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 te3_malloc()] or
3bef0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f [sqlite3_reallo
3bf00 63 28 29 5d 20 77 6f 75 6c 64 0a 2a 2a 20 20 20 c()] would.**
3bf10 20 20 20 20 20 20 20 63 61 75 73 65 20 74 68 65 cause the
3bf20 20 74 6f 74 61 6c 20 61 6d 6f 75 6e 74 20 6f 66 total amount of
3bf30 20 61 6c 6c 6f 63 61 74 65 64 20 6d 65 6d 6f 72 allocated memor
3bf40 79 20 74 6f 20 65 78 63 65 65 64 20 74 68 65 0a y to exceed the.
3bf50 2a 2a 20 20 20 20 20 20 20 20 20 20 73 6f 66 74 ** soft
3bf60 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 74 68 65 heap limit, the
3bf70 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 n [sqlite3_relea
3bf80 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20 se_memory()] is
3bf90 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20 20 20 invoked.**
3bfa0 20 20 20 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 in an attemp
3bfb0 74 20 74 6f 20 72 65 64 75 63 65 20 74 68 65 20 t to reduce the
3bfc0 6d 65 6d 6f 72 79 20 75 73 61 67 65 20 70 72 69 memory usage pri
3bfd0 6f 72 20 74 6f 20 70 72 6f 63 65 65 64 69 6e 67 or to proceeding
3bfe0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 .** wit
3bff0 68 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c h the memory all
3c000 6f 63 61 74 69 6f 6e 20 61 74 74 65 6d 70 74 2e ocation attempt.
3c010 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 33 35 33 7d 20 .**.** {H16353}
3c020 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 Calls to [sqlite
3c030 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 3_malloc()] or [
3c040 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
3c050 29 5d 20 74 68 61 74 20 74 72 69 67 67 65 72 0a )] that trigger.
3c060 2a 2a 20 20 20 20 20 20 20 20 20 20 61 74 74 65 ** atte
3c070 6d 70 74 73 20 74 6f 20 72 65 64 75 63 65 20 6d mpts to reduce m
3c080 65 6d 6f 72 79 20 75 73 61 67 65 20 74 68 72 6f emory usage thro
3c090 75 67 68 20 74 68 65 20 73 6f 66 74 20 68 65 61 ugh the soft hea
3c0a0 70 20 6c 69 6d 69 74 0a 2a 2a 20 20 20 20 20 20 p limit.**
3c0b0 20 20 20 20 6d 65 63 68 61 6e 69 73 6d 20 63 6f mechanism co
3c0c0 6e 74 69 6e 75 65 20 65 76 65 6e 20 69 66 20 74 ntinue even if t
3c0d0 68 65 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 he attempt to re
3c0e0 64 75 63 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 duce memory.**
3c0f0 20 20 20 20 20 20 20 20 75 73 61 67 65 20 69 73 usage is
3c100 20 75 6e 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a unsuccessful..*
3c110 2a 0a 2a 2a 20 7b 48 31 36 33 35 34 7d 20 41 20 *.** {H16354} A
3c120 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f negative or zero
3c130 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 69 6e 20 value for N in
3c140 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 a call to.**
3c150 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 [sqlite3_s
3c160 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 4e oft_heap_limit(N
3c170 29 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 )] means that th
3c180 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 0a 2a ere is no soft.*
3c190 2a 20 20 20 20 20 20 20 20 20 20 68 65 61 70 20 * heap
3c1a0 6c 69 6d 69 74 20 61 6e 64 20 5b 73 71 6c 69 74 limit and [sqlit
3c1b0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 e3_release_memor
3c1c0 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 y()] will only b
3c1d0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 e.** ca
3c1e0 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79 lled when memory
3c1f0 20 69 73 20 63 6f 6d 70 6c 65 74 65 6c 79 20 65 is completely e
3c200 78 68 61 75 73 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 xhausted..**.**
3c210 7b 48 31 36 33 35 35 7d 20 54 68 65 20 64 65 66 {H16355} The def
3c220 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 ault value for t
3c230 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d he soft heap lim
3c240 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a it is zero..**.*
3c250 2a 20 7b 48 31 36 33 35 38 7d 20 45 61 63 68 20 * {H16358} Each
3c260 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
3c270 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 _soft_heap_limit
3c280 28 4e 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74 (N)] overrides t
3c290 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 he.** v
3c2a0 61 6c 75 65 73 20 73 65 74 20 62 79 20 61 6c 6c alues set by all
3c2b0 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2f prior calls..*/
3c2c0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f .void sqlite3_so
3c2d0 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e ft_heap_limit(in
3c2e0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
3c2f0 52 45 46 3a 20 45 78 74 72 61 63 74 20 4d 65 74 REF: Extract Met
3c300 61 64 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f adata About A Co
3c310 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 20 lumn Of A Table
3c320 7b 48 31 32 38 35 30 7d 20 3c 53 36 30 33 30 30 {H12850} <S60300
3c330 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 >.**.** This rou
3c340 74 69 6e 65 20 72 65 74 75 72 6e 73 20 6d 65 74 tine returns met
3c350 61 64 61 74 61 20 61 62 6f 75 74 20 61 20 73 70 adata about a sp
3c360 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 ecific column of
3c370 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 a specific.** d
3c380 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 63 atabase table ac
3c390 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74 cessible using t
3c3a0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
3c3b0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a nection] handle.
3c3c0 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65 ** passed as the
3c3d0 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 first function
3c3e0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 argument..**.**
3c3f0 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 The column is id
3c400 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 entified by the
3c410 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e second, third an
3c420 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 d fourth paramet
3c430 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 ers to.** this f
3c440 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 73 65 63 unction. The sec
3c450 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ond parameter is
3c460 20 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65 either the name
3c470 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
3c480 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 .** (i.e. "main"
3c490 2c 20 22 74 65 6d 70 22 20 6f 72 20 61 6e 20 61 , "temp" or an a
3c4a0 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 ttached database
3c4b0 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 ) containing the
3c4c0 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 specified.** ta
3c4d0 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 49 66 20 ble or NULL. If
3c4e0 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e it is NULL, then
3c4f0 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64 61 all attached da
3c500 74 61 62 61 73 65 73 20 61 72 65 20 73 65 61 72 tabases are sear
3c510 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 ched.** for the
3c520 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 table using the
3c530 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 75 same algorithm u
3c540 73 65 64 20 62 79 20 74 68 65 20 64 61 74 61 62 sed by the datab
3c550 61 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a ase engine to.**
3c560 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 resolve unquali
3c570 66 69 65 64 20 74 61 62 6c 65 20 72 65 66 65 72 fied table refer
3c580 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ences..**.** The
3c590 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 third and fourt
3c5a0 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 h parameters to
3c5b0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 this function ar
3c5c0 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e 64 20 e the table and
3c5d0 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f column.** name o
3c5e0 66 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f f the desired co
3c5f0 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 76 65 lumn, respective
3c600 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 20 74 ly. Neither of t
3c610 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 0a hese parameters.
3c620 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a ** may be NULL..
3c630 2a 2a 0a 2a 2a 20 4d 65 74 61 64 61 74 61 20 69 **.** Metadata i
3c640 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 77 72 s returned by wr
3c650 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d iting to the mem
3c660 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 ory locations pa
3c670 73 73 65 64 20 61 73 20 74 68 65 20 35 74 68 0a ssed as the 5th.
3c680 2a 2a 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e ** and subsequen
3c690 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 t parameters to
3c6a0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 41 this function. A
3c6b0 6e 79 20 6f 66 20 74 68 65 73 65 20 61 72 67 75 ny of these argu
3c6c0 6d 65 6e 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20 ments may be.**
3c6d0 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 NULL, in which c
3c6e0 61 73 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f ase the correspo
3c6f0 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 nding element of
3c700 20 6d 65 74 61 64 61 74 61 20 69 73 20 6f 6d 69 metadata is omi
3c710 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f tted..**.** <blo
3c720 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 ckquote>.** <tab
3c730 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a le border="1">.*
3c740 2a 20 3c 74 72 3e 3c 74 68 3e 20 50 61 72 61 6d * <tr><th> Param
3c750 65 74 65 72 20 3c 74 68 3e 20 4f 75 74 70 75 74 eter <th> Output
3c760 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 44 <br>Type <th> D
3c770 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a escription.**.**
3c780 20 3c 74 72 3e 3c 74 64 3e 20 35 74 68 20 3c 74 <tr><td> 5th <t
3c790 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c d> const char* <
3c7a0 74 64 3e 20 44 61 74 61 20 74 79 70 65 0a 2a 2a td> Data type.**
3c7b0 20 3c 74 72 3e 3c 74 64 3e 20 36 74 68 20 3c 74 <tr><td> 6th <t
3c7c0 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c d> const char* <
3c7d0 74 64 3e 20 4e 61 6d 65 20 6f 66 20 64 65 66 61 td> Name of defa
3c7e0 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 ult collation se
3c7f0 71 75 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 quence.** <tr><t
3c800 64 3e 20 37 74 68 20 3c 74 64 3e 20 69 6e 74 20 d> 7th <td> int
3c810 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 <td> Tru
3c820 65 20 69 66 20 63 6f 6c 75 6d 6e 20 68 61 73 20 e if column has
3c830 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 a NOT NULL const
3c840 72 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 raint.** <tr><td
3c850 3e 20 38 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 > 8th <td> int
3c860 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 <td> True
3c870 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 if column is pa
3c880 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41 52 rt of the PRIMAR
3c890 59 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 Y KEY.** <tr><td
3c8a0 3e 20 39 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 > 9th <td> int
3c8b0 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 <td> True
3c8c0 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 41 55 if column is AU
3c8d0 54 4f 49 4e 43 52 45 4d 45 4e 54 0a 2a 2a 20 3c TOINCREMENT.** <
3c8e0 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f /table>.** </blo
3c8f0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 ckquote>.**.** T
3c900 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 he memory pointe
3c910 64 20 74 6f 20 62 79 20 74 68 65 20 63 68 61 72 d to by the char
3c920 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72 acter pointers r
3c930 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a eturned for the.
3c940 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 ** declaration t
3c950 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f ype and collatio
3c960 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 n sequence is va
3c970 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 lid only until t
3c980 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 he next.** call
3c990 74 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50 to any SQLite AP
3c9a0 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a I function..**.*
3c9b0 2a 20 49 66 20 74 68 65 20 73 70 65 63 69 66 69 * If the specifi
3c9c0 65 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 75 ed table is actu
3c9d0 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 6e 20 ally a view, an
3c9e0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 [error code] is
3c9f0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
3ca00 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64 If the specified
3ca10 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 column is "rowi
3ca20 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 d", "oid" or "_r
3ca30 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a owid_" and an.**
3ca40 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 INTEGER PRIMARY
3ca50 20 4b 45 59 20 63 6f 6c 75 6d 6e 20 68 61 73 20 KEY column has
3ca60 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 been explicitly
3ca70 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 declared, then t
3ca80 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 he output.** par
3ca90 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 ameters are set
3caa0 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 74 for the explicit
3cab0 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 ly declared colu
3cac0 6d 6e 2e 20 49 66 20 74 68 65 72 65 20 69 73 20 mn. If there is
3cad0 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79 no.** explicitly
3cae0 20 64 65 63 6c 61 72 65 64 20 49 4e 54 45 47 45 declared INTEGE
3caf0 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20 63 6f R PRIMARY KEY co
3cb00 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f lumn, then the o
3cb10 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 utput.** paramet
3cb20 65 72 73 20 61 72 65 20 73 65 74 20 61 73 20 66 ers are set as f
3cb30 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 ollows:.**.** <p
3cb40 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61 20 re>.** data
3cb50 74 79 70 65 3a 20 22 49 4e 54 45 47 45 52 22 0a type: "INTEGER".
3cb60 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e ** collation
3cb70 20 73 65 71 75 65 6e 63 65 3a 20 22 42 49 4e 41 sequence: "BINA
3cb80 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e RY".** not n
3cb90 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72 ull: 0.** pr
3cba0 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 imary key: 1.**
3cbb0 20 20 20 20 61 75 74 6f 20 69 6e 63 72 65 6d 65 auto increme
3cbc0 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 0a nt: 0.** </pre>.
3cbd0 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 **.** This funct
3cbe0 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 ion may load one
3cbf0 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d 61 73 or more schemas
3cc00 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20 66 from database f
3cc10 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 iles. If an.** e
3cc20 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 rror occurs duri
3cc30 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73 73 2c ng this process,
3cc40 20 6f 72 20 69 66 20 74 68 65 20 72 65 71 75 65 or if the reque
3cc50 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20 63 6f sted table or co
3cc60 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 lumn.** cannot b
3cc70 65 20 66 6f 75 6e 64 2c 20 61 6e 20 5b 65 72 72 e found, an [err
3cc80 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 or code] is retu
3cc90 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 72 72 6f rned and an erro
3cca0 72 20 6d 65 73 73 61 67 65 20 6c 65 66 74 0a 2a r message left.*
3ccb0 2a 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 * in the [databa
3ccc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 se connection] (
3ccd0 74 6f 20 62 65 20 72 65 74 72 69 65 76 65 64 20 to be retrieved
3cce0 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 using sqlite3_er
3ccf0 72 6d 73 67 28 29 29 2e 0a 2a 2a 0a 2a 2a 20 54 rmsg())..**.** T
3cd00 68 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 his API is only
3cd10 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 available if the
3cd20 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d library was com
3cd30 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a piled with the.*
3cd40 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 * [SQLITE_ENABLE
3cd50 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 _COLUMN_METADATA
3cd60 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 ] C-preprocessor
3cd70 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e symbol defined.
3cd80 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
3cd90 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 table_column_met
3cda0 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33 adata(. sqlite3
3cdb0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
3cdc0 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 /* Connecti
3cdd0 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 on handle */. c
3cde0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 onst char *zDbNa
3cdf0 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61 me, /* Da
3ce00 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e tabase name or N
3ce10 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 ULL */. const c
3ce20 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c har *zTableName,
3ce30 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 /* Table na
3ce40 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 me */. const ch
3ce50 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c ar *zColumnName,
3ce60 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 /* Column na
3ce70 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e me */. char con
3ce80 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c st **pzDataType,
3ce90 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 /* OUTPUT: D
3cea0 65 63 6c 61 72 65 64 20 64 61 74 61 20 74 79 70 eclared data typ
3ceb0 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 e */. char cons
3cec0 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 t **pzCollSeq,
3ced0 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f /* OUTPUT: Co
3cee0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 llation sequence
3cef0 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a name */. int *
3cf00 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 pNotNull,
3cf10 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 /* OUTPUT
3cf20 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 : True if NOT NU
3cf30 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 LL constraint ex
3cf40 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 ists */. int *p
3cf50 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 PrimaryKey,
3cf60 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a /* OUTPUT:
3cf70 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 True if column
3cf80 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 part of PK */.
3cf90 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 int *pAutoinc
3cfa0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f /* O
3cfb0 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 UTPUT: True if c
3cfc0 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e olumn is auto-in
3cfd0 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f crement */.);../
3cfe0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c *.** CAPI3REF: L
3cff0 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e oad An Extension
3d000 20 7b 48 31 32 36 30 30 7d 20 3c 53 32 30 35 30 {H12600} <S2050
3d010 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 0>.**.** This in
3d020 74 65 72 66 61 63 65 20 6c 6f 61 64 73 20 61 6e terface loads an
3d030 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f SQLite extensio
3d040 6e 20 6c 69 62 72 61 72 79 20 66 72 6f 6d 20 74 n library from t
3d050 68 65 20 6e 61 6d 65 64 20 66 69 6c 65 2e 0a 2a he named file..*
3d060 2a 0a 2a 2a 20 7b 48 31 32 36 30 31 7d 20 54 68 *.** {H12601} Th
3d070 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 e sqlite3_load_e
3d080 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 xtension() inter
3d090 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f face attempts to
3d0a0 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 20 20 20 20 load an.**
3d0b0 20 20 20 20 20 53 51 4c 69 74 65 20 65 78 74 65 SQLite exte
3d0c0 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f nsion library co
3d0d0 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 65 20 66 ntained in the f
3d0e0 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a ile zFile..**.**
3d0f0 20 7b 48 31 32 36 30 32 7d 20 54 68 65 20 65 6e {H12602} The en
3d100 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72 try point is zPr
3d110 6f 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 oc..**.** {H1260
3d120 33 7d 20 7a 50 72 6f 63 20 6d 61 79 20 62 65 20 3} zProc may be
3d130 30 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 0, in which case
3d140 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
3d150 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 entry point.**
3d160 20 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 default
3d170 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 s to "sqlite3_ex
3d180 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a tension_init"..*
3d190 2a 0a 2a 2a 20 7b 48 31 32 36 30 34 7d 20 54 68 *.** {H12604} Th
3d1a0 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 e sqlite3_load_e
3d1b0 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 xtension() inter
3d1c0 66 61 63 65 20 73 68 61 6c 6c 20 72 65 74 75 72 face shall retur
3d1d0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 n.** [S
3d1e0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 QLITE_OK] on suc
3d1f0 63 65 73 73 20 61 6e 64 20 5b 53 51 4c 49 54 45 cess and [SQLITE
3d200 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74 _ERROR] if somet
3d210 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e hing goes wrong.
3d220 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 35 7d 20 .**.** {H12605}
3d230 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 If an error occu
3d240 72 73 20 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 rs and pzErrMsg
3d250 69 73 20 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74 is not 0, then t
3d260 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b he.** [
3d270 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 sqlite3_load_ext
3d280 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 ension()] interf
3d290 61 63 65 20 73 68 61 6c 6c 20 61 74 74 65 6d 70 ace shall attemp
3d2a0 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 t to.**
3d2b0 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 20 fill *pzErrMsg
3d2c0 77 69 74 68 20 65 72 72 6f 72 20 6d 65 73 73 61 with error messa
3d2d0 67 65 20 74 65 78 74 20 73 74 6f 72 65 64 20 69 ge text stored i
3d2e0 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 n memory.**
3d2f0 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20 66 72 obtained fr
3d300 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
3d310 6f 63 28 29 5d 2e 20 7b 45 4e 44 7d 20 20 54 68 oc()]. {END} Th
3d320 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 e calling functi
3d330 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 on.** s
3d340 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73 20 hould free this
3d350 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e memory by callin
3d360 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 g [sqlite3_free(
3d370 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 )]..**.** {H1260
3d380 36 7d 20 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 6} Extension loa
3d390 64 69 6e 67 20 6d 75 73 74 20 62 65 20 65 6e 61 ding must be ena
3d3a0 62 6c 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 bled using.**
3d3b0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
3d3c0 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 enable_load_exte
3d3d0 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74 nsion()] prior t
3d3e0 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 o calling this A
3d3f0 50 49 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 PI,.**
3d400 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 otherwise an err
3d410 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72 or will be retur
3d420 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ned..*/.int sqli
3d430 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 te3_load_extensi
3d440 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 on(. sqlite3 *d
3d450 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4c b, /* L
3d460 6f 61 64 20 74 68 65 20 65 78 74 65 6e 73 69 6f oad the extensio
3d470 6e 20 69 6e 74 6f 20 74 68 69 73 20 64 61 74 61 n into this data
3d480 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
3d490 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
3d4a0 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 *zFile, /* Na
3d4b0 6d 65 20 6f 66 20 74 68 65 20 73 68 61 72 65 64 me of the shared
3d4c0 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e library contain
3d4d0 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f ing extension */
3d4e0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
3d4f0 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72 Proc, /* Entr
3d500 79 20 70 6f 69 6e 74 2e 20 20 44 65 72 69 76 65 y point. Derive
3d510 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20 d from zFile if
3d520 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 0 */. char **pz
3d530 45 72 72 4d 73 67 20 20 20 20 20 20 20 2f 2a 20 ErrMsg /*
3d540 50 75 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67 Put error messag
3d550 65 20 68 65 72 65 20 69 66 20 6e 6f 74 20 30 20 e here if not 0
3d560 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.);../*.** CAP
3d570 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 I3REF: Enable Or
3d580 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 73 69 Disable Extensi
3d590 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b 48 31 32 36 on Loading {H126
3d5a0 32 30 7d 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 20} <S20500>.**.
3d5b0 2a 2a 20 53 6f 20 61 73 20 6e 6f 74 20 74 6f 20 ** So as not to
3d5c0 6f 70 65 6e 20 73 65 63 75 72 69 74 79 20 68 6f open security ho
3d5d0 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 61 70 70 les in older app
3d5e0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 61 lications that a
3d5f0 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72 65 64 re.** unprepared
3d600 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 65 78 to deal with ex
3d610 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c tension loading,
3d620 20 61 6e 64 20 61 73 20 61 20 6d 65 61 6e 73 20 and as a means
3d630 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a 2a 20 of disabling.**
3d640 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e extension loadin
3d650 67 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 g while evaluati
3d660 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 ng user-entered
3d670 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 SQL, the followi
3d680 6e 67 20 41 50 49 0a 2a 2a 20 69 73 20 70 72 6f ng API.** is pro
3d690 76 69 64 65 64 20 74 6f 20 74 75 72 6e 20 74 68 vided to turn th
3d6a0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f e [sqlite3_load_
3d6b0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d 65 63 extension()] mec
3d6c0 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 20 6f 66 hanism on and of
3d6d0 66 2e 0a 2a 2a 0a 2a 2a 20 45 78 74 65 6e 73 69 f..**.** Extensi
3d6e0 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20 6f 66 on loading is of
3d6f0 66 20 62 79 20 64 65 66 61 75 6c 74 2e 20 53 65 f by default. Se
3d700 65 20 74 69 63 6b 65 74 20 23 31 38 36 33 2e 0a e ticket #1863..
3d710 2a 2a 0a 2a 2a 20 7b 48 31 32 36 32 31 7d 20 43 **.** {H12621} C
3d720 61 6c 6c 20 74 68 65 20 73 71 6c 69 74 65 33 5f all the sqlite3_
3d730 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 enable_load_exte
3d740 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65 20 nsion() routine
3d750 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a with onoff==1.**
3d760 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 75 72 to tur
3d770 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 n extension load
3d780 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61 6c 6c 20 ing on and call
3d790 69 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 30 it with onoff==0
3d7a0 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 20 20 20 20 to turn.**
3d7b0 20 20 20 20 20 69 74 20 62 61 63 6b 20 6f 66 66 it back off
3d7c0 20 61 67 61 69 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 again..**.** {H
3d7d0 31 32 36 32 32 7d 20 45 78 74 65 6e 73 69 6f 6e 12622} Extension
3d7e0 20 6c 6f 61 64 69 6e 67 20 69 73 20 6f 66 66 20 loading is off
3d7f0 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2f 0a 69 by default..*/.i
3d800 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c nt sqlite3_enabl
3d810 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e e_load_extension
3d820 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 69 6e (sqlite3 *db, in
3d830 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a t onoff);../*.**
3d840 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 6f 6d CAPI3REF: Autom
3d850 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64 20 41 6e atically Load An
3d860 20 45 78 74 65 6e 73 69 6f 6e 73 20 7b 48 31 32 Extensions {H12
3d870 36 34 30 7d 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 640} <S20500>.**
3d880 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 63 61 6e .** This API can
3d890 20 62 65 20 69 6e 76 6f 6b 65 64 20 61 74 20 70 be invoked at p
3d8a0 72 6f 67 72 61 6d 20 73 74 61 72 74 75 70 20 69 rogram startup i
3d8b0 6e 20 6f 72 64 65 72 20 74 6f 20 72 65 67 69 73 n order to regis
3d8c0 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f ter.** one or mo
3d8d0 72 65 20 73 74 61 74 69 63 61 6c 6c 79 20 6c 69 re statically li
3d8e0 6e 6b 65 64 20 65 78 74 65 6e 73 69 6f 6e 73 20 nked extensions
3d8f0 74 68 61 74 20 77 69 6c 6c 20 62 65 20 61 76 61 that will be ava
3d900 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c ilable.** to all
3d910 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 63 new [database c
3d920 6f 6e 6e 65 63 74 69 6f 6e 73 5d 2e 20 7b 45 4e onnections]. {EN
3d930 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f D}.**.** This ro
3d940 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61 20 70 utine stores a p
3d950 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 65 78 ointer to the ex
3d960 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 61 72 tension in an ar
3d970 72 61 79 20 74 68 61 74 20 69 73 0a 2a 2a 20 6f ray that is.** o
3d980 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
3d990 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e lite3_malloc()].
3d9a0 20 20 49 66 20 79 6f 75 20 72 75 6e 20 61 20 6d If you run a m
3d9b0 65 6d 6f 72 79 20 6c 65 61 6b 20 63 68 65 63 6b emory leak check
3d9c0 65 72 0a 2a 2a 20 6f 6e 20 79 6f 75 72 20 70 72 er.** on your pr
3d9d0 6f 67 72 61 6d 20 61 6e 64 20 69 74 20 72 65 70 ogram and it rep
3d9e0 6f 72 74 73 20 61 20 6c 65 61 6b 20 62 65 63 61 orts a leak beca
3d9f0 75 73 65 20 6f 66 20 74 68 69 73 20 61 72 72 61 use of this arra
3da00 79 2c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 5b 73 71 y, invoke.** [sq
3da10 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f lite3_reset_auto
3da20 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 _extension()] pr
3da30 69 6f 72 20 74 6f 20 73 68 75 74 64 6f 77 6e 20 ior to shutdown
3da40 74 6f 20 66 72 65 65 20 74 68 65 20 6d 65 6d 6f to free the memo
3da50 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34 ry..**.** {H1264
3da60 31 7d 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 1} This function
3da70 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 65 78 registers an ex
3da80 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f tension entry po
3da90 69 6e 74 20 74 68 61 74 20 69 73 0a 2a 2a 20 20 int that is.**
3daa0 20 20 20 20 20 20 20 20 61 75 74 6f 6d 61 74 69 automati
3dab0 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 20 77 68 cally invoked wh
3dac0 65 6e 65 76 65 72 20 61 20 6e 65 77 20 5b 64 61 enever a new [da
3dad0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
3dae0 6e 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 n].** i
3daf0 73 20 6f 70 65 6e 65 64 20 75 73 69 6e 67 20 5b s opened using [
3db00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
3db10 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
3db20 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 ()],.**
3db30 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 or [sqlite3_ope
3db40 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b n_v2()]..**.** {
3db50 48 31 32 36 34 32 7d 20 44 75 70 6c 69 63 61 74 H12642} Duplicat
3db60 65 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 72 65 e extensions are
3db70 20 64 65 74 65 63 74 65 64 20 73 6f 20 63 61 6c detected so cal
3db80 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e ling this routin
3db90 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 75 e.** mu
3dba0 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 ltiple times wit
3dbb0 68 20 74 68 65 20 73 61 6d 65 20 65 78 74 65 6e h the same exten
3dbc0 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73 73 sion is harmless
3dbd0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34 33 7d ..**.** {H12643}
3dbe0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 This routine st
3dbf0 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 ores a pointer t
3dc00 6f 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 o the extension
3dc10 69 6e 20 61 6e 20 61 72 72 61 79 0a 2a 2a 20 20 in an array.**
3dc20 20 20 20 20 20 20 20 20 74 68 61 74 20 69 73 20 that is
3dc30 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 obtained from [s
3dc40 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
3dc50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34 34 7d ..**.** {H12644}
3dc60 20 41 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e Automatic exten
3dc70 73 69 6f 6e 73 20 61 70 70 6c 79 20 61 63 72 6f sions apply acro
3dc80 73 73 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a ss all threads..
3dc90 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 */.int sqlite3_a
3dca0 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f uto_extension(vo
3dcb0 69 64 20 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29 id *xEntryPoint)
3dcc0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
3dcd0 46 3a 20 52 65 73 65 74 20 41 75 74 6f 6d 61 74 F: Reset Automat
3dce0 69 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 ic Extension Loa
3dcf0 64 69 6e 67 20 7b 48 31 32 36 36 30 7d 20 3c 53 ding {H12660} <S
3dd00 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 20500>.**.** Thi
3dd10 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 s function disab
3dd20 6c 65 73 20 61 6c 6c 20 70 72 65 76 69 6f 75 73 les all previous
3dd30 6c 79 20 72 65 67 69 73 74 65 72 65 64 20 61 75 ly registered au
3dd40 74 6f 6d 61 74 69 63 0a 2a 2a 20 65 78 74 65 6e tomatic.** exten
3dd50 73 69 6f 6e 73 2e 20 7b 45 4e 44 7d 20 20 49 74 sions. {END} It
3dd60 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 undoes the effe
3dd70 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f 72 0a ct of all prior.
3dd80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f ** [sqlite3_auto
3dd90 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 63 61 _extension()] ca
3dda0 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 lls..**.** {H126
3ddb0 36 31 7d 20 54 68 69 73 20 66 75 6e 63 74 69 6f 61} This functio
3ddc0 6e 20 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 70 n disables all p
3ddd0 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 reviously regist
3dde0 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 ered.**
3ddf0 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e automatic exten
3de00 73 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 sions..**.** {H1
3de10 32 36 36 32 7d 20 54 68 69 73 20 66 75 6e 63 74 2662} This funct
3de20 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 75 74 ion disables aut
3de30 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e omatic extension
3de40 73 20 69 6e 20 61 6c 6c 20 74 68 72 65 61 64 73 s in all threads
3de50 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 ..*/.void sqlite
3de60 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 3_reset_auto_ext
3de70 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f ension(void);../
3de80 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d *.****** EXPERIM
3de90 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 ENTAL - subject
3dea0 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 to change withou
3deb0 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a t notice *******
3dec0 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 *******.**.** Th
3ded0 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 e interface to t
3dee0 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 he virtual-table
3def0 20 6d 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75 mechanism is cu
3df00 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 rrently consider
3df10 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 ed.** to be expe
3df20 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 rimental. The i
3df30 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 nterface might c
3df40 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 hange in incompa
3df50 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 tible ways..** I
3df60 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 f this is a prob
3df70 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 lem for you, do
3df80 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 not use the inte
3df90 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69 rface at this ti
3dfa0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 me..**.** When t
3dfb0 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 he virtual-table
3dfc0 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 mechanism stabi
3dfd0 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 lizes, we will d
3dfe0 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e eclare the.** in
3dff0 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 terface fixed, s
3e000 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 upport it indefi
3e010 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f nitely, and remo
3e020 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e ve this comment.
3e030 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 .*/../*.** Struc
3e040 74 75 72 65 73 20 75 73 65 64 20 62 79 20 74 68 tures used by th
3e050 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 e virtual table
3e060 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 interface.*/.typ
3e070 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
3e080 74 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33 te3_vtab sqlite3
3e090 5f 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73 _vtab;.typedef s
3e0a0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e truct sqlite3_in
3e0b0 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 dex_info sqlite3
3e0c0 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 _index_info;.typ
3e0d0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
3e0e0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 te3_vtab_cursor
3e0f0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 sqlite3_vtab_cur
3e100 73 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72 sor;.typedef str
3e110 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 uct sqlite3_modu
3e120 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c le sqlite3_modul
3e130 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 e;../*.** CAPI3R
3e140 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c EF: Virtual Tabl
3e150 65 20 4f 62 6a 65 63 74 20 7b 48 31 38 30 30 30 e Object {H18000
3e160 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 } <S20400>.** KE
3e170 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f YWORDS: sqlite3_
3e180 6d 6f 64 75 6c 65 0a 2a 2a 20 45 58 50 45 52 49 module.** EXPERI
3e190 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 20 6d MENTAL.**.** A m
3e1a0 6f 64 75 6c 65 20 69 73 20 61 20 63 6c 61 73 73 odule is a class
3e1b0 20 6f 66 20 76 69 72 74 75 61 6c 20 74 61 62 6c of virtual tabl
3e1c0 65 73 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 es. Each module
3e1d0 20 69 73 20 64 65 66 69 6e 65 64 0a 2a 2a 20 62 is defined.** b
3e1e0 79 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 y an instance of
3e1f0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 the following s
3e200 74 72 75 63 74 75 72 65 2e 20 20 54 68 69 73 20 tructure. This
3e210 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73 structure consis
3e220 74 73 0a 2a 2a 20 6d 6f 73 74 6c 79 20 6f 66 20 ts.** mostly of
3e230 6d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 methods for the
3e240 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 module..**.** Th
3e250 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 is interface is
3e260 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 experimental and
3e270 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 is subject to c
3e280 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f hange or.** remo
3e290 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65 val in future re
3e2a0 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
3e2b0 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 ..*/.struct sqli
3e2c0 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 te3_module {. i
3e2d0 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 nt iVersion;. i
3e2e0 6e 74 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 nt (*xCreate)(sq
3e2f0 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 lite3*, void *pA
3e300 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 ux,.
3e310 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e int argc, con
3e320 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 st char *const*a
3e330 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 rgv,.
3e340 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 sqlite3_vtab
3e350 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a **ppVTab, char*
3e360 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e *);. int (*xCon
3e370 6e 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 nect)(sqlite3*,
3e380 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 void *pAux,.
3e390 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 int a
3e3a0 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 rgc, const char
3e3b0 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 *const*argv,.
3e3c0 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 sqli
3e3d0 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 te3_vtab **ppVTa
3e3e0 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e b, char**);. in
3e3f0 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 t (*xBestIndex)(
3e400 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 sqlite3_vtab *pV
3e410 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 Tab, sqlite3_ind
3e420 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 ex_info*);. int
3e430 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 (*xDisconnect)(
3e440 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 sqlite3_vtab *pV
3e450 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 Tab);. int (*xD
3e460 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f estroy)(sqlite3_
3e470 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 vtab *pVTab);.
3e480 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c int (*xOpen)(sql
3e490 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 ite3_vtab *pVTab
3e4a0 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 , sqlite3_vtab_c
3e4b0 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 ursor **ppCursor
3e4c0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 );. int (*xClos
3e4d0 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f e)(sqlite3_vtab_
3e4e0 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 cursor*);. int
3e4f0 28 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 (*xFilter)(sqlit
3e500 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c e3_vtab_cursor*,
3e510 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e int idxNum, con
3e520 73 74 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c st char *idxStr,
3e530 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 .
3e540 20 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 int argc, sqlit
3e550 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 e3_value **argv)
3e560 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 ;. int (*xNext)
3e570 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 (sqlite3_vtab_cu
3e580 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a rsor*);. int (*
3e590 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 xEof)(sqlite3_vt
3e5a0 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 ab_cursor*);. i
3e5b0 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 nt (*xColumn)(sq
3e5c0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f lite3_vtab_curso
3e5d0 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 r*, sqlite3_cont
3e5e0 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e ext*, int);. in
3e5f0 74 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 t (*xRowid)(sqli
3e600 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a te3_vtab_cursor*
3e610 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
3e620 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 *pRowid);. int
3e630 28 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 (*xUpdate)(sqlit
3e640 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 e3_vtab *, int,
3e650 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a sqlite3_value **
3e660 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
3e670 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 *);. int (*xBeg
3e680 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 in)(sqlite3_vtab
3e690 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 *pVTab);. int
3e6a0 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 (*xSync)(sqlite3
3e6b0 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 _vtab *pVTab);.
3e6c0 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 int (*xCommit)(
3e6d0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 sqlite3_vtab *pV
3e6e0 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 Tab);. int (*xR
3e6f0 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 ollback)(sqlite3
3e700 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 _vtab *pVTab);.
3e710 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 int (*xFindFunc
3e720 74 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 tion)(sqlite3_vt
3e730 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e ab *pVtab, int n
3e740 41 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 Arg, const char
3e750 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 *zName,.
3e760 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 v
3e770 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 oid (**pxFunc)(s
3e780 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
3e790 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 int,sqlite3_valu
3e7a0 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20 e**),.
3e7b0 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 voi
3e7c0 64 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e d **ppArg);. in
3e7d0 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c t (*xRename)(sql
3e7e0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 ite3_vtab *pVtab
3e7f0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
3e800 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ew);.};../*.** C
3e810 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c API3REF: Virtual
3e820 20 54 61 62 6c 65 20 49 6e 64 65 78 69 6e 67 20 Table Indexing
3e830 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 7b 48 31 38 Information {H18
3e840 31 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 100} <S20400>.**
3e850 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 KEYWORDS: sqlit
3e860 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a e3_index_info.**
3e870 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a EXPERIMENTAL.**
3e880 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
3e890 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 index_info struc
3e8a0 74 75 72 65 20 61 6e 64 20 69 74 73 20 73 75 62 ture and its sub
3e8b0 73 74 72 75 63 74 75 72 65 73 20 69 73 20 75 73 structures is us
3e8c0 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e ed to.** pass in
3e8d0 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 formation into a
3e8e0 6e 64 20 72 65 63 65 69 76 65 20 74 68 65 20 72 nd receive the r
3e8f0 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 78 42 eply from the xB
3e900 65 73 74 49 6e 64 65 78 0a 2a 2a 20 6d 65 74 68 estIndex.** meth
3e910 6f 64 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 od of an sqlite3
3e920 5f 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 66 69 _module. The fi
3e930 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70 elds under **Inp
3e940 75 74 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a uts** are the.**
3e950 20 69 6e 70 75 74 73 20 74 6f 20 78 42 65 73 74 inputs to xBest
3e960 49 6e 64 65 78 20 61 6e 64 20 61 72 65 20 72 65 Index and are re
3e970 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49 ad-only. xBestI
3e980 6e 64 65 78 20 69 6e 73 65 72 74 73 20 69 74 73 ndex inserts its
3e990 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f .** results into
3e9a0 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a the **Outputs**
3e9b0 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 fields..**.** T
3e9c0 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d he aConstraint[]
3e9d0 20 61 72 72 61 79 20 72 65 63 6f 72 64 73 20 57 array records W
3e9e0 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 HERE clause cons
3e9f0 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65 20 66 traints of the f
3ea00 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e orm:.**.** <pre>
3ea10 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c 2f column OP expr</
3ea20 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 pre>.**.** where
3ea30 20 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c 20 OP is =, <,
3ea40 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72 20 <=, >, or
3ea50 26 67 74 3b 3d 2e 20 20 54 68 65 20 70 61 72 74 >=. The part
3ea60 69 63 75 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 icular operator
3ea70 69 73 0a 2a 2a 20 73 74 6f 72 65 64 20 69 6e 20 is.** stored in
3ea80 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 aConstraint[].op
3ea90 2e 20 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 . The index of
3eaa0 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 the column is st
3eab0 6f 72 65 64 20 69 6e 0a 2a 2a 20 61 43 6f 6e 73 ored in.** aCons
3eac0 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e traint[].iColumn
3ead0 2e 20 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d . aConstraint[]
3eae0 2e 75 73 61 62 6c 65 20 69 73 20 54 52 55 45 20 .usable is TRUE
3eaf0 69 66 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f if the.** expr o
3eb00 6e 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 n the right-hand
3eb10 20 73 69 64 65 20 63 61 6e 20 62 65 20 65 76 61 side can be eva
3eb20 6c 75 61 74 65 64 20 28 61 6e 64 20 74 68 75 73 luated (and thus
3eb30 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a the constraint.
3eb40 2a 2a 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e ** is usable) an
3eb50 64 20 66 61 6c 73 65 20 69 66 20 69 74 20 63 61 d false if it ca
3eb60 6e 6e 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 nnot..**.** The
3eb70 6f 70 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 optimizer automa
3eb80 74 69 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 20 tically inverts
3eb90 74 65 72 6d 73 20 6f 66 20 74 68 65 20 66 6f 72 terms of the for
3eba0 6d 20 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d m "expr OP colum
3ebb0 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20 n".** and makes
3ebc0 6f 74 68 65 72 20 73 69 6d 70 6c 69 66 69 63 61 other simplifica
3ebd0 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 57 48 45 tions to the WHE
3ebe0 52 45 20 63 6c 61 75 73 65 20 69 6e 20 61 6e 20 RE clause in an
3ebf0 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 attempt to.** ge
3ec00 74 20 61 73 20 6d 61 6e 79 20 57 48 45 52 45 20 t as many WHERE
3ec10 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e 74 clause terms int
3ec20 6f 20 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e o the form shown
3ec30 20 61 62 6f 76 65 20 61 73 20 70 6f 73 73 69 62 above as possib
3ec40 6c 65 2e 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 le..** The aCons
3ec50 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f traint[] array o
3ec60 6e 6c 79 20 72 65 70 6f 72 74 73 20 57 48 45 52 nly reports WHER
3ec70 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 E clause terms i
3ec80 6e 20 74 68 65 20 63 6f 72 72 65 63 74 0a 2a 2a n the correct.**
3ec90 20 66 6f 72 6d 20 74 68 61 74 20 72 65 66 65 72 form that refer
3eca0 20 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c to the particul
3ecb0 61 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 ar virtual table
3ecc0 20 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a being queried..
3ecd0 2a 2a 0a 2a 2a 20 49 6e 66 6f 72 6d 61 74 69 6f **.** Informatio
3ece0 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45 n about the ORDE
3ecf0 52 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 73 R BY clause is s
3ed00 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42 tored in aOrderB
3ed10 79 5b 5d 2e 0a 2a 2a 20 45 61 63 68 20 74 65 72 y[]..** Each ter
3ed20 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65 m of aOrderBy re
3ed30 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f cords a column o
3ed40 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 f the ORDER BY c
3ed50 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 lause..**.** The
3ed60 20 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 xBestIndex meth
3ed70 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f od must fill aCo
3ed80 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 nstraintUsage[]
3ed90 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e with information
3eda0 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70 .** about what p
3edb0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73 arameters to pas
3edc0 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 49 s to xFilter. I
3edd0 66 20 61 72 67 76 49 6e 64 65 78 3e 30 20 74 68 f argvIndex>0 th
3ede0 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 2d en.** the right-
3edf0 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65 hand side of the
3ee00 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 corresponding a
3ee10 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 Constraint[] is
3ee20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 evaluated.** and
3ee30 20 62 65 63 6f 6d 65 73 20 74 68 65 20 61 72 67 becomes the arg
3ee40 76 49 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 20 vIndex-th entry
3ee50 69 6e 20 61 72 67 76 2e 20 20 49 66 20 61 43 6f in argv. If aCo
3ee60 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e nstraintUsage[].
3ee70 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c omit.** is true,
3ee80 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 then the constr
3ee90 61 69 6e 74 20 69 73 20 61 73 73 75 6d 65 64 20 aint is assumed
3eea0 74 6f 20 62 65 20 66 75 6c 6c 79 20 68 61 6e 64 to be fully hand
3eeb0 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 69 led by the.** vi
3eec0 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 rtual table and
3eed0 69 73 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 61 is not checked a
3eee0 67 61 69 6e 20 62 79 20 53 51 4c 69 74 65 2e 0a gain by SQLite..
3eef0 2a 2a 0a 2a 2a 20 54 68 65 20 69 64 78 4e 75 6d **.** The idxNum
3ef00 20 61 6e 64 20 69 64 78 50 74 72 20 76 61 6c 75 and idxPtr valu
3ef10 65 73 20 61 72 65 20 72 65 63 6f 72 64 65 64 20 es are recorded
3ef20 61 6e 64 20 70 61 73 73 65 64 20 69 6e 74 6f 20 and passed into
3ef30 78 46 69 6c 74 65 72 2e 0a 2a 2a 20 73 71 6c 69 xFilter..** sqli
3ef40 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 75 73 te3_free() is us
3ef50 65 64 20 74 6f 20 66 72 65 65 20 69 64 78 50 74 ed to free idxPt
3ef60 72 20 69 66 20 6e 65 65 64 54 6f 46 72 65 65 49 r if needToFreeI
3ef70 64 78 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a dxPtr is true..*
3ef80 2a 0a 2a 2a 20 54 68 65 20 6f 72 64 65 72 42 79 *.** The orderBy
3ef90 43 6f 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 Consumed means t
3efa0 68 61 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 hat output from
3efb0 78 46 69 6c 74 65 72 20 77 69 6c 6c 20 6f 63 63 xFilter will occ
3efc0 75 72 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 ur in.** the cor
3efd0 72 65 63 74 20 6f 72 64 65 72 20 74 6f 20 73 61 rect order to sa
3efe0 74 69 73 66 79 20 74 68 65 20 4f 52 44 45 52 20 tisfy the ORDER
3eff0 42 59 20 63 6c 61 75 73 65 20 73 6f 20 74 68 61 BY clause so tha
3f000 74 20 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a t no separate.**
3f010 20 73 6f 72 74 69 6e 67 20 73 74 65 70 20 69 73 sorting step is
3f020 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a required..**.**
3f030 20 54 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f The estimatedCo
3f040 73 74 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65 st value is an e
3f050 73 74 69 6d 61 74 65 20 6f 66 20 74 68 65 20 63 stimate of the c
3f060 6f 73 74 20 6f 66 20 64 6f 69 6e 67 20 74 68 65 ost of doing the
3f070 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 6c .** particular l
3f080 6f 6f 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20 73 ookup. A full s
3f090 63 61 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 77 can of a table w
3f0a0 69 74 68 20 4e 20 65 6e 74 72 69 65 73 20 73 68 ith N entries sh
3f0b0 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20 63 ould have.** a c
3f0c0 6f 73 74 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e ost of N. A bin
3f0d0 61 72 79 20 73 65 61 72 63 68 20 6f 66 20 61 20 ary search of a
3f0e0 74 61 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69 table of N entri
3f0f0 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 20 61 es should have a
3f100 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 61 70 70 72 .** cost of appr
3f110 6f 78 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29 oximately log(N)
3f120 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 ..**.** This int
3f130 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72 69 erface is experi
3f140 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75 mental and is su
3f150 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 bject to change
3f160 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e or.** removal in
3f170 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
3f180 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 73 of SQLite..*/.s
3f190 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e truct sqlite3_in
3f1a0 64 65 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 dex_info {. /*
3f1b0 49 6e 70 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 Inputs */. int
3f1c0 6e 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 nConstraint;
3f1d0 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 /* Number
3f1e0 20 6f 66 20 65 6e 74 72 69 65 73 20 69 6e 20 61 of entries in a
3f1f0 43 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 Constraint */.
3f200 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 struct sqlite3_i
3f210 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 ndex_constraint
3f220 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 {. int iColu
3f230 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 mn;
3f240 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 /* Column on le
3f250 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 ft-hand side of
3f260 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 constraint */.
3f270 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 unsigned char
3f280 20 6f 70 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 op; /*
3f290 43 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65 72 61 Constraint opera
3f2a0 74 6f 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 tor */. unsi
3f2b0 67 6e 65 64 20 63 68 61 72 20 75 73 61 62 6c 65 gned char usable
3f2c0 3b 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 ; /* True if
3f2d0 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 this constraint
3f2e0 20 69 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 is usable */.
3f2f0 20 20 20 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 int iTermOffs
3f300 65 74 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 et; /*
3f310 55 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 Used internally
3f320 2d 20 78 42 65 73 74 49 6e 64 65 78 20 73 68 6f - xBestIndex sho
3f330 75 6c 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 uld ignore */.
3f340 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 } *aConstraint;
3f350 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 61 /* Ta
3f360 62 6c 65 20 6f 66 20 57 48 45 52 45 20 63 6c 61 ble of WHERE cla
3f370 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 use constraints
3f380 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 */. int nOrderB
3f390 79 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 y;
3f3a0 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 /* Number of ter
3f3b0 6d 73 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20 ms in the ORDER
3f3c0 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 BY clause */. s
3f3d0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e truct sqlite3_in
3f3e0 64 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 dex_orderby {.
3f3f0 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 int iColumn;
3f400 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
3f410 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f Column number */
3f420 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 . unsigned c
3f430 68 61 72 20 64 65 73 63 3b 20 20 20 20 20 20 20 har desc;
3f440 2f 2a 20 54 72 75 65 20 66 6f 72 20 44 45 53 43 /* True for DESC
3f450 2e 20 20 46 61 6c 73 65 20 66 6f 72 20 41 53 43 . False for ASC
3f460 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 . */. } *aOrder
3f470 42 79 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 By;
3f480 20 20 2f 2a 20 54 68 65 20 4f 52 44 45 52 20 42 /* The ORDER B
3f490 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a Y clause */. /*
3f4a0 20 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 Outputs */. st
3f4b0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 ruct sqlite3_ind
3f4c0 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 ex_constraint_us
3f4d0 61 67 65 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 age {. int ar
3f4e0 67 76 49 6e 64 65 78 3b 20 20 20 20 20 20 20 20 gvIndex;
3f4f0 20 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e /* if >0, con
3f500 73 74 72 61 69 6e 74 20 69 73 20 70 61 72 74 20 straint is part
3f510 6f 66 20 61 72 67 76 20 74 6f 20 78 46 69 6c 74 of argv to xFilt
3f520 65 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e er */. unsign
3f530 65 64 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 ed char omit;
3f540 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 /* Do not cod
3f550 65 20 61 20 74 65 73 74 20 66 6f 72 20 74 68 69 e a test for thi
3f560 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a s constraint */.
3f570 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 } *aConstraint
3f580 55 73 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 Usage;. int idx
3f590 4e 75 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20 Num;
3f5a0 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 /* Number us
3f5b0 65 64 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74 ed to identify t
3f5c0 68 65 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 he index */. ch
3f5d0 61 72 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20 ar *idxStr;
3f5e0 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69 /* Stri
3f5f0 6e 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 ng, possibly obt
3f600 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 ained from sqlit
3f610 65 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 e3_malloc */. i
3f620 6e 74 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 nt needToFreeIdx
3f630 53 74 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 Str; /* Fre
3f640 65 20 69 64 78 53 74 72 20 75 73 69 6e 67 20 73 e idxStr using s
3f650 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 66 qlite3_free() if
3f660 20 74 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f true */. int o
3f670 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 rderByConsumed;
3f680 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 /* True if
3f690 20 6f 75 74 70 75 74 20 69 73 20 61 6c 72 65 61 output is alrea
3f6a0 64 79 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 dy ordered */.
3f6b0 64 6f 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64 double estimated
3f6c0 43 6f 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 Cost; /* Es
3f6d0 74 69 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20 timated cost of
3f6e0 75 73 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78 using this index
3f6f0 20 2a 2f 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53 */.};.#define S
3f700 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 QLITE_INDEX_CONS
3f710 54 52 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 TRAINT_EQ 2.#
3f720 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e define SQLITE_IN
3f730 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 DEX_CONSTRAINT_G
3f740 54 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 T 4.#define S
3f750 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 QLITE_INDEX_CONS
3f760 54 52 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 TRAINT_LE 8.#
3f770 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e define SQLITE_IN
3f780 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c DEX_CONSTRAINT_L
3f790 54 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 T 16.#define
3f7a0 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e SQLITE_INDEX_CON
3f7b0 53 54 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32 STRAINT_GE 32
3f7c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3f7d0 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 INDEX_CONSTRAINT
3f7e0 5f 4d 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a _MATCH 64../*.**
3f7f0 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 CAPI3REF: Regis
3f800 74 65 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 ter A Virtual Ta
3f810 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 ble Implementati
3f820 6f 6e 20 7b 48 31 38 32 30 30 7d 20 3c 53 32 30 on {H18200} <S20
3f830 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 400>.** EXPERIME
3f840 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 NTAL.**.** This
3f850 72 6f 75 74 69 6e 65 20 69 73 20 75 73 65 64 20 routine is used
3f860 74 6f 20 72 65 67 69 73 74 65 72 20 61 20 6e 65 to register a ne
3f870 77 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 77 69 w module name wi
3f880 74 68 20 61 0a 2a 2a 20 5b 64 61 74 61 62 61 73 th a.** [databas
3f890 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 e connection].
3f8a0 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73 Module names mus
3f8b0 74 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 t be registered
3f8c0 62 65 66 6f 72 65 0a 2a 2a 20 63 72 65 61 74 69 before.** creati
3f8d0 6e 67 20 6e 65 77 20 76 69 72 74 75 61 6c 20 74 ng new virtual t
3f8e0 61 62 6c 65 73 20 6f 6e 20 74 68 65 20 6d 6f 64 ables on the mod
3f8f0 75 6c 65 2c 20 6f 72 20 62 65 66 6f 72 65 20 75 ule, or before u
3f900 73 69 6e 67 0a 2a 2a 20 70 72 65 65 78 69 73 74 sing.** preexist
3f910 69 6e 67 20 76 69 72 74 75 61 6c 20 74 61 62 6c ing virtual tabl
3f920 65 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 es of the module
3f930 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 ..**.** This int
3f940 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72 69 erface is experi
3f950 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75 mental and is su
3f960 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 bject to change
3f970 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e or.** removal in
3f980 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
3f990 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 of SQLite..*/.S
3f9a0 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 QLITE_EXPERIMENT
3f9b0 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 AL int sqlite3_c
3f9c0 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 reate_module(.
3f9d0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
3f9e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 /* SQ
3f9f0 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 Lite connection
3fa00 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 to register modu
3fa10 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e le with */. con
3fa20 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
3fa30 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 /* Name
3fa40 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f of the module */
3fa50 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 . const sqlite3
3fa60 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20 20 20 2f 2a _module *, /*
3fa70 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 Methods for the
3fa80 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 module */. voi
3fa90 64 20 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 d *
3faa0 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e /* Clien
3fab0 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 t data for xCrea
3fac0 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 te/xConnect */.)
3fad0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
3fae0 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 56 69 F: Register A Vi
3faf0 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c rtual Table Impl
3fb00 65 6d 65 6e 74 61 74 69 6f 6e 20 7b 48 31 38 32 ementation {H182
3fb10 31 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 10} <S20400>.**
3fb20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a EXPERIMENTAL.**.
3fb30 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
3fb40 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 is identical to
3fb50 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 the [sqlite3_cre
3fb60 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6d 65 ate_module()] me
3fb70 74 68 6f 64 20 61 62 6f 76 65 2c 0a 2a 2a 20 65 thod above,.** e
3fb80 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c xcept that it al
3fb90 6c 6f 77 73 20 61 20 64 65 73 74 72 75 63 74 6f lows a destructo
3fba0 72 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 r function to be
3fbb0 20 73 70 65 63 69 66 69 65 64 2e 20 49 74 20 69 specified. It i
3fbc0 73 0a 2a 2a 20 65 76 65 6e 20 6d 6f 72 65 20 65 s.** even more e
3fbd0 78 70 65 72 69 6d 65 6e 74 61 6c 20 74 68 61 6e xperimental than
3fbe0 20 74 68 65 20 72 65 73 74 20 6f 66 20 74 68 65 the rest of the
3fbf0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 virtual tables
3fc00 41 50 49 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 API..*/.SQLITE_E
3fc10 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 XPERIMENTAL int
3fc20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d sqlite3_create_m
3fc30 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73 71 6c 69 odule_v2(. sqli
3fc40 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
3fc50 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 /* SQLite
3fc60 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 connection to r
3fc70 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 egister module w
3fc80 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 ith */. const c
3fc90 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 har *zName,
3fca0 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 /* Name of t
3fcb0 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 he module */. c
3fcc0 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 onst sqlite3_mod
3fcd0 75 6c 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 ule *, /* Met
3fce0 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 hods for the mod
3fcf0 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c ule */. void *,
3fd00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3fd10 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 /* Client da
3fd20 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 ta for xCreate/x
3fd30 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20 76 6f 69 Connect */. voi
3fd40 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 d(*xDestroy)(voi
3fd50 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f 64 75 6c d*) /* Modul
3fd60 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e e destructor fun
3fd70 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a ction */.);../*.
3fd80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 ** CAPI3REF: Vir
3fd90 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 73 74 61 tual Table Insta
3fda0 6e 63 65 20 4f 62 6a 65 63 74 20 7b 48 31 38 30 nce Object {H180
3fdb0 31 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 10} <S20400>.**
3fdc0 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 KEYWORDS: sqlite
3fdd0 33 5f 76 74 61 62 0a 2a 2a 20 45 58 50 45 52 49 3_vtab.** EXPERI
3fde0 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 MENTAL.**.** Eve
3fdf0 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d ry module implem
3fe00 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 entation uses a
3fe10 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 20 subclass of the
3fe20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 following struct
3fe30 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73 63 72 69 ure.** to descri
3fe40 62 65 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 be a particular
3fe50 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 instance of the
3fe60 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 73 75 module. Each su
3fe70 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62 bclass will.** b
3fe80 65 20 74 61 69 6c 6f 72 65 64 20 74 6f 20 74 68 e tailored to th
3fe90 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 e specific needs
3fea0 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 of the module i
3feb0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a mplementation..*
3fec0 2a 20 54 68 65 20 70 75 72 70 6f 73 65 20 6f 66 * The purpose of
3fed0 20 74 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 this superclass
3fee0 20 69 73 20 74 6f 20 64 65 66 69 6e 65 20 63 65 is to define ce
3fef0 72 74 61 69 6e 20 66 69 65 6c 64 73 20 74 68 61 rtain fields tha
3ff00 74 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20 t are.** common
3ff10 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d to all module im
3ff20 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a plementations..*
3ff30 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 *.** Virtual tab
3ff40 6c 65 73 20 6d 65 74 68 6f 64 73 20 63 61 6e 20 les methods can
3ff50 73 65 74 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 set an error mes
3ff60 73 61 67 65 20 62 79 20 61 73 73 69 67 6e 69 6e sage by assignin
3ff70 67 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 62 g a.** string ob
3ff80 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c tained from [sql
3ff90 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 ite3_mprintf()]
3ffa0 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54 68 65 to zErrMsg. The
3ffb0 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a method should.*
3ffc0 2a 20 74 61 6b 65 20 63 61 72 65 20 74 68 61 74 * take care that
3ffd0 20 61 6e 79 20 70 72 69 6f 72 20 73 74 72 69 6e any prior strin
3ffe0 67 20 69 73 20 66 72 65 65 64 20 62 79 20 61 20 g is freed by a
3fff0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
40000 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 70 72 69 6f _free()].** prio
40010 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 61 r to assigning a
40020 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20 7a new string to z
40030 45 72 72 4d 73 67 2e 20 20 41 66 74 65 72 20 74 ErrMsg. After t
40040 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 he error message
40050 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65 64 .** is delivered
40060 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65 6e up to the clien
40070 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 t application, t
40080 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 he string will b
40090 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a e automatically.
400a0 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c 69 ** freed by sqli
400b0 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20 74 te3_free() and t
400c0 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 he zErrMsg field
400d0 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e will be zeroed.
400e0 20 20 4e 6f 74 65 0a 2a 2a 20 74 68 61 74 20 73 Note.** that s
400f0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 qlite3_mprintf()
40100 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 66 72 65 and sqlite3_fre
40110 65 28 29 20 61 72 65 20 75 73 65 64 20 6f 6e 20 e() are used on
40120 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c the zErrMsg fiel
40130 64 0a 2a 2a 20 73 69 6e 63 65 20 76 69 72 74 75 d.** since virtu
40140 61 6c 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f al tables are co
40150 6d 6d 6f 6e 6c 79 20 69 6d 70 6c 65 6d 65 6e 74 mmonly implement
40160 65 64 20 69 6e 20 6c 6f 61 64 61 62 6c 65 20 65 ed in loadable e
40170 78 74 65 6e 73 69 6f 6e 73 20 77 68 69 63 68 0a xtensions which.
40180 2a 2a 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 61 ** do not have a
40190 63 63 65 73 73 20 74 6f 20 73 71 6c 69 74 65 33 ccess to sqlite3
401a0 4d 50 72 69 6e 74 66 28 29 20 6f 72 20 73 71 6c MPrintf() or sql
401b0 69 74 65 33 46 72 65 65 28 29 2e 0a 2a 2a 0a 2a ite3Free()..**.*
401c0 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 * This interface
401d0 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c is experimental
401e0 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 and is subject
401f0 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 to change or.**
40200 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 removal in futur
40210 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 e releases of SQ
40220 4c 69 74 65 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 Lite..*/.struct
40230 73 71 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 sqlite3_vtab {.
40240 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d const sqlite3_m
40250 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 odule *pModule;
40260 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 /* The module f
40270 6f 72 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 or this virtual
40280 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e table */. int n
40290 52 65 66 3b 20 20 20 20 20 20 20 20 20 20 20 20 Ref;
402a0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 /* Us
402b0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2a 2f ed internally */
402c0 0a 20 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 . char *zErrMsg
402d0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ;
402e0 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 /* Error mess
402f0 61 67 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 age from sqlite3
40300 5f 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 _mprintf() */.
40310 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 /* Virtual table
40320 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
40330 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 will typically
40340 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 add additional f
40350 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a ields */.};../*.
40360 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 ** CAPI3REF: Vir
40370 74 75 61 6c 20 54 61 62 6c 65 20 43 75 72 73 6f tual Table Curso
40380 72 20 4f 62 6a 65 63 74 20 20 7b 48 31 38 30 32 r Object {H1802
40390 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 0} <S20400>.** K
403a0 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 EYWORDS: sqlite3
403b0 5f 76 74 61 62 5f 63 75 72 73 6f 72 0a 2a 2a 20 _vtab_cursor.**
403c0 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a EXPERIMENTAL.**.
403d0 2a 2a 20 45 76 65 72 79 20 6d 6f 64 75 6c 65 20 ** Every module
403e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 implementation u
403f0 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 20 6f ses a subclass o
40400 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 f the following
40410 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 74 6f 20 structure.** to
40420 64 65 73 63 72 69 62 65 20 63 75 72 73 6f 72 73 describe cursors
40430 20 74 68 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f that point into
40440 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 the virtual tab
40450 6c 65 20 61 6e 64 20 61 72 65 20 75 73 65 64 0a le and are used.
40460 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74 68 72 6f 75 ** to loop throu
40470 67 68 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 gh the virtual t
40480 61 62 6c 65 2e 20 20 43 75 72 73 6f 72 73 20 61 able. Cursors a
40490 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 re created using
404a0 20 74 68 65 0a 2a 2a 20 78 4f 70 65 6e 20 6d 65 the.** xOpen me
404b0 74 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 75 thod of the modu
404c0 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 le. Each module
404d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
404e0 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74 will define.** t
404f0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20 he content of a
40500 63 75 72 73 6f 72 20 73 74 72 75 63 74 75 72 65 cursor structure
40510 20 74 6f 20 73 75 69 74 20 69 74 73 20 6f 77 6e to suit its own
40520 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 needs..**.** Th
40530 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 65 78 is superclass ex
40540 69 73 74 73 20 69 6e 20 6f 72 64 65 72 20 74 6f ists in order to
40550 20 64 65 66 69 6e 65 20 66 69 65 6c 64 73 20 6f define fields o
40560 66 20 74 68 65 20 63 75 72 73 6f 72 20 74 68 61 f the cursor tha
40570 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 t.** are common
40580 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 to all implement
40590 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 ations..**.** Th
405a0 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 is interface is
405b0 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 experimental and
405c0 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 is subject to c
405d0 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f hange or.** remo
405e0 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65 val in future re
405f0 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
40600 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 ..*/.struct sqli
40610 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 te3_vtab_cursor
40620 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 {. sqlite3_vtab
40630 20 2a 70 56 74 61 62 3b 20 20 20 20 20 20 2f 2a *pVtab; /*
40640 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6f Virtual table o
40650 66 20 74 68 69 73 20 63 75 72 73 6f 72 20 2a 2f f this cursor */
40660 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 . /* Virtual ta
40670 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ble implementati
40680 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c ons will typical
40690 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 ly add additiona
406a0 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a l fields */.};..
406b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
406c0 44 65 63 6c 61 72 65 20 54 68 65 20 53 63 68 65 Declare The Sche
406d0 6d 61 20 4f 66 20 41 20 56 69 72 74 75 61 6c 20 ma Of A Virtual
406e0 54 61 62 6c 65 20 7b 48 31 38 32 38 30 7d 20 3c Table {H18280} <
406f0 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 S20400>.** EXPER
40700 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 IMENTAL.**.** Th
40710 65 20 78 43 72 65 61 74 65 20 61 6e 64 20 78 43 e xCreate and xC
40720 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 73 20 6f onnect methods o
40730 66 20 61 20 6d 6f 64 75 6c 65 20 75 73 65 20 74 f a module use t
40740 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 he following API
40750 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72 65 20 74 .** to declare t
40760 68 65 20 66 6f 72 6d 61 74 20 28 74 68 65 20 6e he format (the n
40770 61 6d 65 73 20 61 6e 64 20 64 61 74 61 74 79 70 ames and datatyp
40780 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e es of the column
40790 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20 76 69 72 s) of.** the vir
407a0 74 75 61 6c 20 74 61 62 6c 65 73 20 74 68 65 79 tual tables they
407b0 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a implement..**.*
407c0 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 * This interface
407d0 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c is experimental
407e0 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 and is subject
407f0 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 to change or.**
40800 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 removal in futur
40810 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 e releases of SQ
40820 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f Lite..*/.SQLITE_
40830 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 EXPERIMENTAL int
40840 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 sqlite3_declare
40850 5f 76 74 61 62 28 73 71 6c 69 74 65 33 2a 2c 20 _vtab(sqlite3*,
40860 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 72 65 const char *zCre
40870 61 74 65 54 61 62 6c 65 29 3b 0a 0a 2f 2a 0a 2a ateTable);../*.*
40880 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 76 65 72 * CAPI3REF: Over
40890 6c 6f 61 64 20 41 20 46 75 6e 63 74 69 6f 6e 20 load A Function
408a0 46 6f 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 For A Virtual Ta
408b0 62 6c 65 20 7b 48 31 38 33 30 30 7d 20 3c 53 32 ble {H18300} <S2
408c0 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 0400>.** EXPERIM
408d0 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 56 69 72 74 ENTAL.**.** Virt
408e0 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 20 70 ual tables can p
408f0 72 6f 76 69 64 65 20 61 6c 74 65 72 6e 61 74 69 rovide alternati
40900 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ve implementatio
40910 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a ns of functions.
40920 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 78 46 69 ** using the xFi
40930 6e 64 46 75 6e 63 74 69 6f 6e 20 6d 65 74 68 6f ndFunction metho
40940 64 2e 20 20 42 75 74 20 67 6c 6f 62 61 6c 20 76 d. But global v
40950 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65 ersions of those
40960 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 functions.** mu
40970 73 74 20 65 78 69 73 74 20 69 6e 20 6f 72 64 65 st exist in orde
40980 72 20 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64 r to be overload
40990 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 ed..**.** This A
409a0 50 49 20 6d 61 6b 65 73 20 73 75 72 65 20 61 20 PI makes sure a
409b0 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f global version o
409c0 66 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 f a function wit
409d0 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a h a particular.*
409e0 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65 * name and numbe
409f0 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20 r of parameters
40a00 65 78 69 73 74 73 2e 20 20 49 66 20 6e 6f 20 73 exists. If no s
40a10 75 63 68 20 66 75 6e 63 74 69 6f 6e 20 65 78 69 uch function exi
40a20 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 sts.** before th
40a30 69 73 20 41 50 49 20 69 73 20 63 61 6c 6c 65 64 is API is called
40a40 2c 20 61 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e , a new function
40a50 20 69 73 20 63 72 65 61 74 65 64 2e 20 20 54 68 is created. Th
40a60 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
40a70 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 65 77 20 66 .** of the new f
40a80 75 6e 63 74 69 6f 6e 20 61 6c 77 61 79 73 20 63 unction always c
40a90 61 75 73 65 73 20 61 6e 20 65 78 63 65 70 74 69 auses an excepti
40aa0 6f 6e 20 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e on to be thrown.
40ab0 20 20 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20 So.** the new
40ac0 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 function is not
40ad0 67 6f 6f 64 20 66 6f 72 20 61 6e 79 74 68 69 6e good for anythin
40ae0 67 20 62 79 20 69 74 73 65 6c 66 2e 20 20 49 74 g by itself. It
40af0 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 s only.** purpos
40b00 65 20 69 73 20 74 6f 20 62 65 20 61 20 70 6c 61 e is to be a pla
40b10 63 65 68 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f ceholder functio
40b20 6e 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 n that can be ov
40b30 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20 76 erloaded.** by v
40b40 69 72 74 75 61 6c 20 74 61 62 6c 65 73 2e 0a 2a irtual tables..*
40b50 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 73 68 *.** This API sh
40b60 6f 75 6c 64 20 62 65 20 63 6f 6e 73 69 64 65 72 ould be consider
40b70 65 64 20 70 61 72 74 20 6f 66 20 74 68 65 20 76 ed part of the v
40b80 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 irtual table int
40b90 65 72 66 61 63 65 2c 0a 2a 2a 20 77 68 69 63 68 erface,.** which
40ba0 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c is experimental
40bb0 20 61 6e 64 20 73 75 62 6a 65 63 74 20 74 6f 20 and subject to
40bc0 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 change..*/.SQLIT
40bd0 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 E_EXPERIMENTAL i
40be0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c nt sqlite3_overl
40bf0 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c oad_function(sql
40c00 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 ite3*, const cha
40c10 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e r *zFuncName, in
40c20 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 t nArg);../*.**
40c30 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f The interface to
40c40 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 the virtual-tab
40c50 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 64 65 66 le mechanism def
40c60 69 6e 65 64 20 61 62 6f 76 65 20 28 62 61 63 6b ined above (back
40c70 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d up.** to a comm
40c80 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c 79 20 73 ent remarkably s
40c90 69 6d 69 6c 61 72 20 74 6f 20 74 68 69 73 20 6f imilar to this o
40ca0 6e 65 29 20 69 73 20 63 75 72 72 65 6e 74 6c 79 ne) is currently
40cb0 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 considered.** t
40cc0 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61 o be experimenta
40cd0 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 l. The interfac
40ce0 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 e might change i
40cf0 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 n incompatible w
40d00 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 ays..** If this
40d10 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 is a problem for
40d20 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 you, do not use
40d30 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 61 the interface a
40d40 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a t this time..**.
40d50 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72 74 ** When the virt
40d60 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e ual-table mechan
40d70 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 ism stabilizes,
40d80 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 we will declare
40d90 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 the.** interface
40da0 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20 fixed, support
40db0 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c it indefinitely,
40dc0 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73 and remove this
40dd0 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a comment..**.***
40de0 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c *** EXPERIMENTAL
40df0 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 - subject to ch
40e00 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 ange without not
40e10 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ice ************
40e20 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 **.*/../*.** CAP
40e30 49 33 52 45 46 3a 20 41 20 48 61 6e 64 6c 65 20 I3REF: A Handle
40e40 54 6f 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 20 To An Open BLOB
40e50 7b 48 31 37 38 30 30 7d 20 3c 53 33 30 32 33 30 {H17800} <S30230
40e60 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b >.** KEYWORDS: {
40e70 42 4c 4f 42 20 68 61 6e 64 6c 65 7d 20 7b 42 4c BLOB handle} {BL
40e80 4f 42 20 68 61 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a OB handles}.**.*
40e90 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 * An instance of
40ea0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 this object rep
40eb0 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 resents an open
40ec0 42 4c 4f 42 20 6f 6e 20 77 68 69 63 68 0a 2a 2a BLOB on which.**
40ed0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f [sqlite3_blob_o
40ee0 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 pen | incrementa
40ef0 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 63 61 6e 20 l BLOB I/O] can
40f00 62 65 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a be performed..**
40f10 20 4f 62 6a 65 63 74 73 20 6f 66 20 74 68 69 73 Objects of this
40f20 20 74 79 70 65 20 61 72 65 20 63 72 65 61 74 65 type are create
40f30 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c d by [sqlite3_bl
40f40 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e ob_open()].** an
40f50 64 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b d destroyed by [
40f60 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f sqlite3_blob_clo
40f70 73 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 se()]..** The [s
40f80 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 qlite3_blob_read
40f90 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
40fa0 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 69 _blob_write()] i
40fb0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 63 61 6e nterfaces.** can
40fc0 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 61 64 be used to read
40fd0 20 6f 72 20 77 72 69 74 65 20 73 6d 61 6c 6c 20 or write small
40fe0 73 75 62 73 65 63 74 69 6f 6e 73 20 6f 66 20 74 subsections of t
40ff0 68 65 20 42 4c 4f 42 2e 0a 2a 2a 20 54 68 65 20 he BLOB..** The
41000 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 [sqlite3_blob_by
41010 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 tes()] interface
41020 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a returns the siz
41030 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 69 6e e of the BLOB in
41040 20 62 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 bytes..*/.typed
41050 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
41060 33 5f 62 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 3_blob sqlite3_b
41070 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 lob;../*.** CAPI
41080 33 52 45 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 3REF: Open A BLO
41090 42 20 46 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 B For Incrementa
410a0 6c 20 49 2f 4f 20 7b 48 31 37 38 31 30 7d 20 3c l I/O {H17810} <
410b0 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S30230>.**.** Th
410c0 69 73 20 69 6e 74 65 72 66 61 63 65 73 20 6f 70 is interfaces op
410d0 65 6e 73 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 ens a [BLOB hand
410e0 6c 65 20 7c 20 68 61 6e 64 6c 65 5d 20 74 6f 20 le | handle] to
410f0 74 68 65 20 42 4c 4f 42 20 6c 6f 63 61 74 65 64 the BLOB located
41100 0a 2a 2a 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c .** in row iRow,
41110 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c column zColumn,
41120 20 74 61 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e table zTable in
41130 20 64 61 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a database zDb;.*
41140 2a 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 * in other words
41150 2c 20 74 68 65 20 73 61 6d 65 20 42 4c 4f 42 20 , the same BLOB
41160 74 68 61 74 20 77 6f 75 6c 64 20 62 65 20 73 65 that would be se
41170 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a lected by:.**.**
41180 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 <pre>.** SE
41190 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f LECT zColumn FRO
411a0 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 M zDb.zTable WHE
411b0 52 45 20 72 6f 77 69 64 20 3d 20 69 52 6f 77 3b RE rowid = iRow;
411c0 0a 2a 2a 20 3c 2f 70 72 65 3e 20 7b 45 4e 44 7d .** </pre> {END}
411d0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 6c .**.** If the fl
411e0 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 ags parameter is
411f0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 74 non-zero, the t
41200 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 he BLOB is opene
41210 64 20 66 6f 72 20 72 65 61 64 0a 2a 2a 20 61 6e d for read.** an
41220 64 20 77 72 69 74 65 20 61 63 63 65 73 73 2e 20 d write access.
41230 49 66 20 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 If it is zero, t
41240 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 he BLOB is opene
41250 64 20 66 6f 72 20 72 65 61 64 20 61 63 63 65 73 d for read acces
41260 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 s..**.** Note th
41270 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 at the database
41280 6e 61 6d 65 20 69 73 20 6e 6f 74 20 74 68 65 20 name is not the
41290 66 69 6c 65 6e 61 6d 65 20 74 68 61 74 20 63 6f filename that co
412a0 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61 ntains.** the da
412b0 74 61 62 61 73 65 20 62 75 74 20 72 61 74 68 65 tabase but rathe
412c0 72 20 74 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e r the symbolic n
412d0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 ame of the datab
412e0 61 73 65 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 ase that.** is a
412f0 73 73 69 67 6e 65 64 20 77 68 65 6e 20 74 68 65 ssigned when the
41300 20 64 61 74 61 62 61 73 65 20 69 73 20 63 6f 6e database is con
41310 6e 65 63 74 65 64 20 75 73 69 6e 67 20 5b 41 54 nected using [AT
41320 54 41 43 48 5d 2e 0a 2a 2a 20 46 6f 72 20 74 68 TACH]..** For th
41330 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 e main database
41340 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 62 61 file, the databa
41350 73 65 20 6e 61 6d 65 20 69 73 20 22 6d 61 69 6e se name is "main
41360 22 2e 0a 2a 2a 20 46 6f 72 20 54 45 4d 50 20 74 "..** For TEMP t
41370 61 62 6c 65 73 2c 20 74 68 65 20 64 61 74 61 62 ables, the datab
41380 61 73 65 20 6e 61 6d 65 20 69 73 20 22 74 65 6d ase name is "tem
41390 70 22 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 p"..**.** On suc
413a0 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b cess, [SQLITE_OK
413b0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e ] is returned an
413c0 64 20 74 68 65 20 6e 65 77 20 5b 42 4c 4f 42 20 d the new [BLOB
413d0 68 61 6e 64 6c 65 5d 20 69 73 20 77 72 69 74 74 handle] is writt
413e0 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c 6f 62 en.** to *ppBlob
413f0 2e 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b . Otherwise an [
41400 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 error code] is r
41410 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 79 20 eturned and any
41420 76 61 6c 75 65 20 77 72 69 74 74 65 6e 0a 2a 2a value written.**
41430 20 74 6f 20 2a 70 70 42 6c 6f 62 20 73 68 6f 75 to *ppBlob shou
41440 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 ld not be used b
41450 79 20 74 68 65 20 63 61 6c 6c 65 72 2e 0a 2a 2a y the caller..**
41460 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 This function s
41470 65 74 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 ets the [databas
41480 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 e connection] er
41490 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 ror code and mes
414a0 73 61 67 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 sage.** accessib
414b0 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f le via [sqlite3_
414c0 65 72 72 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b errcode()] and [
414d0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 sqlite3_errmsg()
414e0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 ]..**.** If the
414f0 72 6f 77 20 74 68 61 74 20 61 20 42 4c 4f 42 20 row that a BLOB
41500 68 61 6e 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f handle points to
41510 20 69 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 is modified by
41520 61 6e 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20 an.** [UPDATE],
41530 5b 44 45 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20 [DELETE], or by
41540 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69 [ON CONFLICT] si
41550 64 65 2d 65 66 66 65 63 74 73 0a 2a 2a 20 74 68 de-effects.** th
41560 65 6e 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 en the BLOB hand
41570 6c 65 20 69 73 20 6d 61 72 6b 65 64 20 61 73 20 le is marked as
41580 22 65 78 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68 "expired"..** Th
41590 69 73 20 69 73 20 74 72 75 65 20 69 66 20 61 6e is is true if an
415a0 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 y column of the
415b0 72 6f 77 20 69 73 20 63 68 61 6e 67 65 64 2c 20 row is changed,
415c0 65 76 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a even a column.**
415d0 20 6f 74 68 65 72 20 74 68 61 6e 20 74 68 65 20 other than the
415e0 6f 6e 65 20 74 68 65 20 42 4c 4f 42 20 68 61 6e one the BLOB han
415f0 64 6c 65 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 0a dle is open on..
41600 2a 2a 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c ** Calls to [sql
41610 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 ite3_blob_read()
41620 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 ] and [sqlite3_b
41630 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 66 6f 72 lob_write()] for
41640 0a 2a 2a 20 61 20 65 78 70 69 72 65 64 20 42 4c .** a expired BL
41650 4f 42 20 68 61 6e 64 6c 65 20 66 61 69 6c 20 77 OB handle fail w
41660 69 74 68 20 61 6e 20 72 65 74 75 72 6e 20 63 6f ith an return co
41670 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 de of [SQLITE_AB
41680 4f 52 54 5d 2e 0a 2a 2a 20 43 68 61 6e 67 65 73 ORT]..** Changes
41690 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 61 20 written into a
416a0 42 4c 4f 42 20 70 72 69 6f 72 20 74 6f 20 74 68 BLOB prior to th
416b0 65 20 42 4c 4f 42 20 65 78 70 69 72 69 6e 67 20 e BLOB expiring
416c0 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c 62 are not.** rollb
416d0 61 63 6b 20 62 79 20 74 68 65 20 65 78 70 69 72 ack by the expir
416e0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 42 4c 4f ation of the BLO
416f0 42 2e 20 20 53 75 63 68 20 63 68 61 6e 67 65 73 B. Such changes
41700 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 will eventually
41710 0a 2a 2a 20 63 6f 6d 6d 69 74 20 69 66 20 74 68 .** commit if th
41720 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f e transaction co
41730 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c ntinues to compl
41740 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 etion..**.** INV
41750 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
41760 48 31 37 38 31 33 7d 20 41 20 73 75 63 63 65 73 H17813} A succes
41770 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 sful invocation
41780 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
41790 62 6c 6f 62 5f 6f 70 65 6e 28 44 2c 42 2c 54 2c blob_open(D,B,T,
417a0 43 2c 52 2c 46 2c 50 29 5d 0a 2a 2a 20 20 20 20 C,R,F,P)].**
417b0 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 interface
417c0 73 68 61 6c 6c 20 6f 70 65 6e 20 61 6e 20 5b 73 shall open an [s
417d0 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a qlite3_blob] obj
417e0 65 63 74 20 50 20 6f 6e 20 74 68 65 20 42 4c 4f ect P on the BLO
417f0 42 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e B.** in
41800 20 63 6f 6c 75 6d 6e 20 43 20 6f 66 20 74 68 65 column C of the
41810 20 74 61 62 6c 65 20 54 20 69 6e 20 74 68 65 20 table T in the
41820 64 61 74 61 62 61 73 65 20 42 20 6f 6e 0a 2a 2a database B on.**
41830 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 64 the [d
41840 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
41850 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 on] D..**.** {H1
41860 37 38 31 34 7d 20 41 20 73 75 63 63 65 73 73 66 7814} A successf
41870 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 ul invocation of
41880 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f [sqlite3_blob_o
41890 70 65 6e 28 44 2c 2e 2e 2e 29 5d 20 73 68 61 6c pen(D,...)] shal
418a0 6c 20 73 74 61 72 74 0a 2a 2a 20 20 20 20 20 20 l start.**
418b0 20 20 20 20 61 20 6e 65 77 20 74 72 61 6e 73 61 a new transa
418c0 63 74 69 6f 6e 20 6f 6e 20 74 68 65 20 5b 64 61 ction on the [da
418d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
418e0 6e 5d 20 44 20 69 66 20 74 68 61 74 0a 2a 2a 20 n] D if that.**
418f0 20 20 20 20 20 20 20 20 20 63 6f 6e 6e 65 63 74 connect
41900 69 6f 6e 20 69 73 20 6e 6f 74 20 61 6c 72 65 61 ion is not alrea
41910 64 79 20 69 6e 20 61 20 74 72 61 6e 73 61 63 74 dy in a transact
41920 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 ion..**.** {H178
41930 31 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 16} The [sqlite3
41940 5f 62 6c 6f 62 5f 6f 70 65 6e 28 44 2c 42 2c 54 _blob_open(D,B,T
41950 2c 43 2c 52 2c 46 2c 50 29 5d 20 69 6e 74 65 72 ,C,R,F,P)] inter
41960 66 61 63 65 20 73 68 61 6c 6c 20 6f 70 65 6e 0a face shall open.
41970 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
41980 42 4c 4f 42 20 66 6f 72 20 72 65 61 64 20 61 6e BLOB for read an
41990 64 20 77 72 69 74 65 20 61 63 63 65 73 73 20 69 d write access i
419a0 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 f and only if th
419b0 65 20 46 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 e F.**
419c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e parameter is non
419d0 2d 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 -zero..**.** {H1
419e0 37 38 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 7819} The [sqlit
419f0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 e3_blob_open()]
41a00 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 interface shall
41a10 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f return [SQLITE_O
41a20 4b 5d 20 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 K] on.**
41a30 20 20 73 75 63 63 65 73 73 20 61 6e 64 20 61 6e success and an
41a40 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 appropriate [er
41a50 72 6f 72 20 63 6f 64 65 5d 20 6f 6e 20 66 61 69 ror code] on fai
41a60 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 lure..**.** {H17
41a70 38 32 31 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 821} If an error
41a80 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 65 occurs during e
41a90 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 valuation of [sq
41aa0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 lite3_blob_open(
41ab0 44 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 D,...)].**
41ac0 20 20 20 20 74 68 65 6e 20 73 75 62 73 65 71 75 then subsequ
41ad0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 ent calls to [sq
41ae0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 lite3_errcode(D)
41af0 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b ],.** [
41b00 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
41b10 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 0a 2a 2a _errcode()], .**
41b20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
41b30 65 33 5f 65 72 72 6d 73 67 28 44 29 5d 2c 20 61 e3_errmsg(D)], a
41b40 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d nd [sqlite3_errm
41b50 73 67 31 36 28 44 29 5d 20 73 68 61 6c 6c 20 72 sg16(D)] shall r
41b60 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 eturn.**
41b70 20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 70 information ap
41b80 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68 propriate for th
41b90 61 74 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 at error..**.**
41ba0 7b 48 31 37 38 32 34 7d 20 49 66 20 61 6e 79 20 {H17824} If any
41bb0 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 72 6f column in the ro
41bc0 77 20 74 68 61 74 20 61 20 5b 73 71 6c 69 74 65 w that a [sqlite
41bd0 33 5f 62 6c 6f 62 5d 20 68 61 73 20 6f 70 65 6e 3_blob] has open
41be0 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 is.**
41bf0 63 68 61 6e 67 65 64 20 62 79 20 61 20 73 65 70 changed by a sep
41c00 61 72 61 74 65 20 5b 55 50 44 41 54 45 5d 20 6f arate [UPDATE] o
41c10 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 r [DELETE] state
41c20 6d 65 6e 74 20 6f 72 20 62 79 0a 2a 2a 20 20 20 ment or by.**
41c30 20 20 20 20 20 20 20 61 6e 20 5b 4f 4e 20 43 4f an [ON CO
41c40 4e 46 4c 49 43 54 5d 20 73 69 64 65 20 65 66 66 NFLICT] side eff
41c50 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 5b 73 ect, then the [s
41c60 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 73 68 61 qlite3_blob] sha
41c70 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 ll.** b
41c80 65 20 6d 61 72 6b 65 64 20 61 73 20 69 6e 76 61 e marked as inva
41c90 6c 69 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 lid..*/.int sqli
41ca0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 te3_blob_open(.
41cb0 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e sqlite3*,. con
41cc0 73 74 20 63 68 61 72 20 2a 7a 44 62 2c 0a 20 20 st char *zDb,.
41cd0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 const char *zTab
41ce0 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 le,. const char
41cf0 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c *zColumn,. sql
41d00 69 74 65 33 5f 69 6e 74 36 34 20 69 52 6f 77 2c ite3_int64 iRow,
41d10 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 0a 20 20 . int flags,.
41d20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 sqlite3_blob **p
41d30 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 pBlob.);../*.**
41d40 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 65 20 CAPI3REF: Close
41d50 41 20 42 4c 4f 42 20 48 61 6e 64 6c 65 20 7b 48 A BLOB Handle {H
41d60 31 37 38 33 30 7d 20 3c 53 33 30 32 33 30 3e 0a 17830} <S30230>.
41d70 2a 2a 0a 2a 2a 20 43 6c 6f 73 65 73 20 61 6e 20 **.** Closes an
41d80 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c open [BLOB handl
41d90 65 5d 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 69 6e e]..**.** Closin
41da0 67 20 61 20 42 4c 4f 42 20 73 68 61 6c 6c 20 63 g a BLOB shall c
41db0 61 75 73 65 20 74 68 65 20 63 75 72 72 65 6e 74 ause the current
41dc0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 transaction to
41dd0 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66 20 74 68 65 commit.** if the
41de0 72 65 20 61 72 65 20 6e 6f 20 6f 74 68 65 72 20 re are no other
41df0 42 4c 4f 42 73 2c 20 6e 6f 20 70 65 6e 64 69 6e BLOBs, no pendin
41e00 67 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 g prepared state
41e10 6d 65 6e 74 73 2c 20 61 6e 64 20 74 68 65 0a 2a ments, and the.*
41e20 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
41e30 63 74 69 6f 6e 20 69 73 20 69 6e 20 5b 61 75 74 ction is in [aut
41e40 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 5d 2e 0a 2a ocommit mode]..*
41e50 2a 20 49 66 20 61 6e 79 20 77 72 69 74 65 73 20 * If any writes
41e60 77 65 72 65 20 6d 61 64 65 20 74 6f 20 74 68 65 were made to the
41e70 20 42 4c 4f 42 2c 20 74 68 65 79 20 6d 69 67 68 BLOB, they migh
41e80 74 20 62 65 20 68 65 6c 64 20 69 6e 20 63 61 63 t be held in cac
41e90 68 65 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20 he.** until the
41ea0 63 6c 6f 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 close operation
41eb0 69 66 20 74 68 65 79 20 77 69 6c 6c 20 66 69 74 if they will fit
41ec0 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 43 6c . {END}.**.** Cl
41ed0 6f 73 69 6e 67 20 74 68 65 20 42 4c 4f 42 20 6f osing the BLOB o
41ee0 66 74 65 6e 20 66 6f 72 63 65 73 20 74 68 65 20 ften forces the
41ef0 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 75 74 20 74 changes.** out t
41f00 6f 20 64 69 73 6b 20 61 6e 64 20 73 6f 20 69 66 o disk and so if
41f10 20 61 6e 79 20 49 2f 4f 20 65 72 72 6f 72 73 20 any I/O errors
41f20 6f 63 63 75 72 2c 20 74 68 65 79 20 77 69 6c 6c occur, they will
41f30 20 6c 69 6b 65 6c 79 20 6f 63 63 75 72 0a 2a 2a likely occur.**
41f40 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 at the time whe
41f50 6e 20 74 68 65 20 42 4c 4f 42 20 69 73 20 63 6c n the BLOB is cl
41f60 6f 73 65 64 2e 20 20 7b 48 31 37 38 33 33 7d 20 osed. {H17833}
41f70 41 6e 79 20 65 72 72 6f 72 73 20 74 68 61 74 20 Any errors that
41f80 6f 63 63 75 72 20 64 75 72 69 6e 67 0a 2a 2a 20 occur during.**
41f90 63 6c 6f 73 69 6e 67 20 61 72 65 20 72 65 70 6f closing are repo
41fa0 72 74 65 64 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 rted as a non-ze
41fb0 72 6f 20 72 65 74 75 72 6e 20 76 61 6c 75 65 2e ro return value.
41fc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 42 4c 4f 42 20 .**.** The BLOB
41fd0 69 73 20 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 is closed uncond
41fe0 69 74 69 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e itionally. Even
41ff0 20 69 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 if this routine
42000 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 returns.** an e
42010 72 72 6f 72 20 63 6f 64 65 2c 20 74 68 65 20 42 rror code, the B
42020 4c 4f 42 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f LOB is still clo
42030 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 sed..**.** INVAR
42040 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 IANTS:.**.** {H1
42050 37 38 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 7833} The [sqlit
42060 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 50 29 e3_blob_close(P)
42070 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6c 6f 73 ] interface clos
42080 65 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 62 es an [sqlite3_b
42090 6c 6f 62 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 lob].**
420a0 20 6f 62 6a 65 63 74 20 50 20 70 72 65 76 69 6f object P previo
420b0 75 73 6c 79 20 6f 70 65 6e 65 64 20 75 73 69 6e usly opened usin
420c0 67 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f g [sqlite3_blob_
420d0 6f 70 65 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b open()]..**.** {
420e0 48 31 37 38 33 36 7d 20 43 6c 6f 73 69 6e 67 20 H17836} Closing
420f0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 an [sqlite3_blob
42100 5d 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 0a 2a ] object using.*
42110 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
42120 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 te3_blob_close()
42130 5d 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 ] shall cause th
42140 65 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 e current transa
42150 63 74 69 6f 6e 20 74 6f 0a 2a 2a 20 20 20 20 20 ction to.**
42160 20 20 20 20 20 63 6f 6d 6d 69 74 20 69 66 20 74 commit if t
42170 68 65 72 65 20 61 72 65 20 6e 6f 20 6f 74 68 65 here are no othe
42180 72 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f r open [sqlite3_
42190 62 6c 6f 62 5d 20 6f 62 6a 65 63 74 73 0a 2a 2a blob] objects.**
421a0 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 70 72 or [pr
421b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
421c0 73 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b s] on the same [
421d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
421e0 69 6f 6e 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 ion] and.**
421f0 20 20 20 20 20 74 68 65 20 64 61 74 61 62 61 73 the databas
42200 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
42210 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d in [autocommit m
42220 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 ode]..**.** {H17
42230 38 33 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 839} The [sqlite
42240 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 50 29 5d 3_blob_close(P)]
42250 20 69 6e 74 65 72 66 61 63 65 73 20 73 68 61 6c interfaces shal
42260 6c 20 63 6c 6f 73 65 20 74 68 65 0a 2a 2a 20 20 l close the.**
42270 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
42280 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63 74 20 50 20 _blob] object P
42290 75 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79 2c unconditionally,
422a0 20 65 76 65 6e 20 69 66 0a 2a 2a 20 20 20 20 20 even if.**
422b0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 6c [sqlite3_bl
422c0 6f 62 5f 63 6c 6f 73 65 28 50 29 5d 20 72 65 74 ob_close(P)] ret
422d0 75 72 6e 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f urns something o
422e0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
422f0 45 5f 4f 4b 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 E_OK]..*/.int sq
42300 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 lite3_blob_close
42310 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 (sqlite3_blob *)
42320 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
42330 46 3a 20 52 65 74 75 72 6e 20 54 68 65 20 53 69 F: Return The Si
42340 7a 65 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c ze Of An Open BL
42350 4f 42 20 7b 48 31 37 38 34 30 7d 20 3c 53 33 30 OB {H17840} <S30
42360 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 230>.**.** Retur
42370 6e 73 20 74 68 65 20 73 69 7a 65 20 69 6e 20 62 ns the size in b
42380 79 74 65 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 ytes of the BLOB
42390 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 accessible via
423a0 74 68 65 20 6f 70 65 6e 0a 2a 2a 20 5b 5d 42 4c the open.** []BL
423b0 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 20 69 74 OB handle] in it
423c0 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e s only argument.
423d0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
423e0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 34 33 S:.**.** {H17843
423f0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 } The [sqlite3_b
42400 6c 6f 62 5f 62 79 74 65 73 28 50 29 5d 20 69 6e lob_bytes(P)] in
42410 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
42420 74 68 65 20 73 69 7a 65 0a 2a 2a 20 20 20 20 20 the size.**
42430 20 20 20 20 20 69 6e 20 62 79 74 65 73 20 6f 66 in bytes of
42440 20 74 68 65 20 42 4c 4f 42 20 74 68 61 74 20 74 the BLOB that t
42450 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 he [sqlite3_blob
42460 5d 20 6f 62 6a 65 63 74 20 50 0a 2a 2a 20 20 20 ] object P.**
42470 20 20 20 20 20 20 20 72 65 66 65 72 73 20 74 6f refers to
42480 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
42490 5f 62 6c 6f 62 5f 62 79 74 65 73 28 73 71 6c 69 _blob_bytes(sqli
424a0 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a te3_blob *);../*
424b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
424c0 61 64 20 44 61 74 61 20 46 72 6f 6d 20 41 20 42 ad Data From A B
424d0 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c LOB Incrementall
424e0 79 20 7b 48 31 37 38 35 30 7d 20 3c 53 33 30 32 y {H17850} <S302
424f0 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 30>.**.** This f
42500 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20 unction is used
42510 74 6f 20 72 65 61 64 20 64 61 74 61 20 66 72 6f to read data fro
42520 6d 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 m an open [BLOB
42530 68 61 6e 64 6c 65 5d 20 69 6e 74 6f 20 61 0a 2a handle] into a.*
42540 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70 6c 69 65 * caller-supplie
42550 64 20 62 75 66 66 65 72 2e 20 4e 20 62 79 74 65 d buffer. N byte
42560 73 20 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f s of data are co
42570 70 69 65 64 20 69 6e 74 6f 20 62 75 66 66 65 72 pied into buffer
42580 20 5a 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 6f Z.** from the o
42590 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74 69 pen BLOB, starti
425a0 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 ng at offset iOf
425b0 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 6f fset..**.** If o
425c0 66 66 73 65 74 20 69 4f 66 66 73 65 74 20 69 73 ffset iOffset is
425d0 20 6c 65 73 73 20 74 68 61 6e 20 4e 20 62 79 74 less than N byt
425e0 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e 64 20 es from the end
425f0 6f 66 20 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 of the BLOB,.**
42600 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 [SQLITE_ERROR] i
42610 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e s returned and n
42620 6f 20 64 61 74 61 20 69 73 20 72 65 61 64 2e 20 o data is read.
42630 20 49 66 20 4e 20 6f 72 20 69 4f 66 66 73 65 74 If N or iOffset
42640 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e is.** less than
42650 20 7a 65 72 6f 2c 20 5b 53 51 4c 49 54 45 5f 45 zero, [SQLITE_E
42660 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 RROR] is returne
42670 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 d and no data is
42680 20 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 read..**.** An
42690 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 attempt to read
426a0 66 72 6f 6d 20 61 6e 20 65 78 70 69 72 65 64 20 from an expired
426b0 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 [BLOB handle] fa
426c0 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 ils with an.** e
426d0 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 rror code of [SQ
426e0 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a LITE_ABORT]..**.
426f0 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 53 ** On success, S
42700 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 QLITE_OK is retu
42710 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 rned..** Otherwi
42720 73 65 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f se, an [error co
42730 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e de] or an [exten
42740 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 ded error code]
42750 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a is returned..**.
42760 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
42770 2a 0a 2a 2a 20 7b 48 31 37 38 35 33 7d 20 41 20 *.** {H17853} A
42780 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 successful invoc
42790 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 ation of [sqlite
427a0 33 5f 62 6c 6f 62 5f 72 65 61 64 28 50 2c 5a 2c 3_blob_read(P,Z,
427b0 4e 2c 58 29 5d 20 0a 2a 2a 20 20 20 20 20 20 20 N,X)] .**
427c0 20 20 20 73 68 61 6c 6c 20 72 65 61 64 73 20 4e shall reads N
427d0 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 6f bytes of data o
427e0 75 74 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 72 ut of the BLOB r
427f0 65 66 65 72 65 6e 63 65 64 20 62 79 0a 2a 2a 20 eferenced by.**
42800 20 20 20 20 20 20 20 20 20 5b 42 4c 4f 42 20 68 [BLOB h
42810 61 6e 64 6c 65 5d 20 50 20 62 65 67 69 6e 6e 69 andle] P beginni
42820 6e 67 20 61 74 20 6f 66 66 73 65 74 20 58 20 61 ng at offset X a
42830 6e 64 20 73 74 6f 72 65 20 74 68 6f 73 65 20 62 nd store those b
42840 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 ytes.**
42850 20 69 6e 74 6f 20 62 75 66 66 65 72 20 5a 2e 0a into buffer Z..
42860 2a 2a 0a 2a 2a 20 7b 48 31 37 38 35 36 7d 20 49 **.** {H17856} I
42870 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f n [sqlite3_blob_
42880 72 65 61 64 28 50 2c 5a 2c 4e 2c 58 29 5d 20 69 read(P,Z,N,X)] i
42890 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 f the size of th
428a0 65 20 42 4c 4f 42 0a 2a 2a 20 20 20 20 20 20 20 e BLOB.**
428b0 20 20 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 is less than
428c0 4e 2b 58 20 62 79 74 65 73 2c 20 74 68 65 6e 20 N+X bytes, then
428d0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 the function sha
428e0 6c 6c 20 6c 65 61 76 65 20 74 68 65 0a 2a 2a 20 ll leave the.**
428f0 20 20 20 20 20 20 20 20 20 5a 20 62 75 66 66 65 Z buffe
42900 72 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 r unchanged and
42910 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 return [SQLITE_E
42920 52 52 4f 52 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 RROR]..**.** {H1
42930 37 38 35 39 7d 20 49 6e 20 5b 73 71 6c 69 74 65 7859} In [sqlite
42940 33 5f 62 6c 6f 62 5f 72 65 61 64 28 50 2c 5a 2c 3_blob_read(P,Z,
42950 4e 2c 58 29 5d 20 69 66 20 58 20 6f 72 20 4e 20 N,X)] if X or N
42960 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 is less than zer
42970 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 o.** th
42980 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 en the function
42990 73 68 61 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 shall leave the
429a0 5a 20 62 75 66 66 65 72 20 75 6e 63 68 61 6e 67 Z buffer unchang
429b0 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 ed.** a
429c0 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 nd return [SQLIT
429d0 45 5f 45 52 52 4f 52 5d 2e 0a 2a 2a 0a 2a 2a 20 E_ERROR]..**.**
429e0 7b 48 31 37 38 36 32 7d 20 54 68 65 20 5b 73 71 {H17862} The [sq
429f0 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 lite3_blob_read(
42a00 50 2c 5a 2c 4e 2c 58 29 5d 20 69 6e 74 65 72 66 P,Z,N,X)] interf
42a10 61 63 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e ace shall return
42a20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 [SQLITE_OK].**
42a30 20 20 20 20 20 20 20 20 20 69 66 20 4e 20 62 79 if N by
42a40 74 65 73 20 61 72 65 20 73 75 63 63 65 73 73 66 tes are successf
42a50 75 6c 6c 79 20 72 65 61 64 20 69 6e 74 6f 20 62 ully read into b
42a60 75 66 66 65 72 20 5a 2e 0a 2a 2a 0a 2a 2a 20 7b uffer Z..**.** {
42a70 48 31 37 38 36 33 7d 20 49 66 20 74 68 65 20 5b H17863} If the [
42a80 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 50 20 69 BLOB handle] P i
42a90 73 20 65 78 70 69 72 65 64 20 61 6e 64 20 58 20 s expired and X
42aa0 61 6e 64 20 4e 20 61 72 65 20 77 69 74 68 69 6e and N are within
42ab0 20 62 6f 75 6e 64 73 0a 2a 2a 20 20 20 20 20 20 bounds.**
42ac0 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 then [sqlite
42ad0 33 5f 62 6c 6f 62 5f 72 65 61 64 28 50 2c 5a 2c 3_blob_read(P,Z,
42ae0 4e 2c 58 29 5d 20 73 68 61 6c 6c 20 6c 65 61 76 N,X)] shall leav
42af0 65 20 74 68 65 20 5a 20 62 75 66 66 65 72 0a 2a e the Z buffer.*
42b00 2a 20 20 20 20 20 20 20 20 20 20 75 6e 63 68 61 * uncha
42b10 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 20 nged and return
42b20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a [SQLITE_ABORT]..
42b30 2a 2a 0a 2a 2a 20 7b 48 31 37 38 36 35 7d 20 49 **.** {H17865} I
42b40 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 f the requested
42b50 72 65 61 64 20 63 6f 75 6c 64 20 6e 6f 74 20 62 read could not b
42b60 65 20 63 6f 6d 70 6c 65 74 65 64 2c 0a 2a 2a 20 e completed,.**
42b70 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 the [sq
42b80 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 lite3_blob_read(
42b90 50 2c 5a 2c 4e 2c 58 29 5d 20 69 6e 74 65 72 66 P,Z,N,X)] interf
42ba0 61 63 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e ace shall return
42bb0 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 an.**
42bc0 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 appropriate [err
42bd0 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 or code] or [ext
42be0 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 ended error code
42bf0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 36 38 ]..**.** {H17868
42c00 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 } If an error oc
42c10 63 75 72 73 20 64 75 72 69 6e 67 20 65 76 61 6c curs during eval
42c20 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 uation of [sqlit
42c30 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 50 2c 2e e3_blob_read(P,.
42c40 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 ..)].**
42c50 20 74 68 65 6e 20 73 75 62 73 65 71 75 65 6e 74 then subsequent
42c60 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 calls to [sqlit
42c70 65 33 5f 65 72 72 63 6f 64 65 28 44 29 5d 2c 0a e3_errcode(D)],.
42c80 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
42c90 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 ite3_extended_er
42ca0 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20 rcode()],.**
42cb0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 [sqlite3_e
42cc0 72 72 6d 73 67 28 44 29 5d 2c 20 61 6e 64 20 5b rrmsg(D)], and [
42cd0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 sqlite3_errmsg16
42ce0 28 44 29 5d 20 73 68 61 6c 6c 20 72 65 74 75 72 (D)] shall retur
42cf0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e n.** in
42d00 66 6f 72 6d 61 74 69 6f 6e 20 61 70 70 72 6f 70 formation approp
42d10 72 69 61 74 65 20 66 6f 72 20 74 68 61 74 20 65 riate for that e
42d20 72 72 6f 72 2c 20 77 68 65 72 65 20 44 20 69 73 rror, where D is
42d30 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
42d40 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
42d50 63 74 69 6f 6e 5d 20 74 68 61 74 20 77 61 73 20 ction] that was
42d60 75 73 65 64 20 74 6f 20 6f 70 65 6e 20 74 68 65 used to open the
42d70 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 50 [BLOB handle] P
42d80 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
42d90 5f 62 6c 6f 62 5f 72 65 61 64 28 73 71 6c 69 74 _blob_read(sqlit
42da0 65 33 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 e3_blob *, void
42db0 2a 5a 2c 20 69 6e 74 20 4e 2c 20 69 6e 74 20 69 *Z, int N, int i
42dc0 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 Offset);../*.**
42dd0 43 41 50 49 33 52 45 46 3a 20 57 72 69 74 65 20 CAPI3REF: Write
42de0 44 61 74 61 20 49 6e 74 6f 20 41 20 42 4c 4f 42 Data Into A BLOB
42df0 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b Incrementally {
42e00 48 31 37 38 37 30 7d 20 3c 53 33 30 32 33 30 3e H17870} <S30230>
42e10 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 .**.** This func
42e20 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 tion is used to
42e30 77 72 69 74 65 20 64 61 74 61 20 69 6e 74 6f 20 write data into
42e40 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 an open [BLOB ha
42e50 6e 64 6c 65 5d 20 66 72 6f 6d 20 61 0a 2a 2a 20 ndle] from a.**
42e60 63 61 6c 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 caller-supplied
42e70 62 75 66 66 65 72 2e 20 4e 20 62 79 74 65 73 20 buffer. N bytes
42e80 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 of data are copi
42e90 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 66 66 ed from the buff
42ea0 65 72 20 5a 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 er Z.** into the
42eb0 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72 open BLOB, star
42ec0 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69 ting at offset i
42ed0 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 Offset..**.** If
42ee0 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c the [BLOB handl
42ef0 65 5d 20 70 61 73 73 65 64 20 61 73 20 74 68 65 e] passed as the
42f00 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
42f10 77 61 73 20 6e 6f 74 20 6f 70 65 6e 65 64 20 66 was not opened f
42f20 6f 72 0a 2a 2a 20 77 72 69 74 69 6e 67 20 28 74 or.** writing (t
42f30 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 he flags paramet
42f40 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 er to [sqlite3_b
42f50 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 77 61 73 20 lob_open()] was
42f60 7a 65 72 6f 29 2c 0a 2a 2a 20 74 68 69 73 20 66 zero),.** this f
42f70 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
42f80 5b 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 [SQLITE_READONLY
42f90 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 ]..**.** This fu
42fa0 6e 63 74 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 nction may only
42fb0 6d 6f 64 69 66 79 20 74 68 65 20 63 6f 6e 74 65 modify the conte
42fc0 6e 74 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 3b nts of the BLOB;
42fd0 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f it is.** not po
42fe0 73 73 69 62 6c 65 20 74 6f 20 69 6e 63 72 65 61 ssible to increa
42ff0 73 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 se the size of a
43000 20 42 4c 4f 42 20 75 73 69 6e 67 20 74 68 69 73 BLOB using this
43010 20 41 50 49 2e 0a 2a 2a 20 49 66 20 6f 66 66 73 API..** If offs
43020 65 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 et iOffset is le
43030 73 73 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20 ss than N bytes
43040 66 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 from the end of
43050 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 the BLOB,.** [SQ
43060 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 LITE_ERROR] is r
43070 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 eturned and no d
43080 61 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e 20 ata is written.
43090 20 49 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 If N is.** less
430a0 20 74 68 61 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 than zero [SQLI
430b0 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 TE_ERROR] is ret
430c0 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 urned and no dat
430d0 61 20 69 73 20 77 72 69 74 74 65 6e 2e 0a 2a 2a a is written..**
430e0 0a 2a 2a 20 41 6e 20 61 74 74 65 6d 70 74 20 74 .** An attempt t
430f0 6f 20 77 72 69 74 65 20 74 6f 20 61 6e 20 65 78 o write to an ex
43100 70 69 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 pired [BLOB hand
43110 6c 65 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 le] fails with a
43120 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 n.** error code
43130 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 of [SQLITE_ABORT
43140 5d 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 ]. Writes to th
43150 65 20 42 4c 4f 42 20 74 68 61 74 20 6f 63 63 75 e BLOB that occu
43160 72 72 65 64 0a 2a 2a 20 62 65 66 6f 72 65 20 74 rred.** before t
43170 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d he [BLOB handle]
43180 20 65 78 70 69 72 65 64 20 61 72 65 20 6e 6f 74 expired are not
43190 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79 20 rolled back by
431a0 74 68 65 0a 2a 2a 20 65 78 70 69 72 61 74 69 6f the.** expiratio
431b0 6e 20 6f 66 20 74 68 65 20 68 61 6e 64 6c 65 2c n of the handle,
431c0 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 though of cours
431d0 65 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20 e those changes
431e0 6d 69 67 68 74 0a 2a 2a 20 68 61 76 65 20 62 65 might.** have be
431f0 65 6e 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 en overwritten b
43200 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 y the statement
43210 74 68 61 74 20 65 78 70 69 72 65 64 20 74 68 65 that expired the
43220 20 42 4c 4f 42 20 68 61 6e 64 6c 65 0a 2a 2a 20 BLOB handle.**
43230 6f 72 20 62 79 20 6f 74 68 65 72 20 69 6e 64 65 or by other inde
43240 70 65 6e 64 65 6e 74 20 73 74 61 74 65 6d 65 6e pendent statemen
43250 74 73 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 ts..**.** On suc
43260 63 65 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 cess, SQLITE_OK
43270 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 is returned..**
43280 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20 20 5b Otherwise, an [
43290 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 error code] or a
432a0 6e 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f n [extended erro
432b0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 r code] is retur
432c0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 ned..**.** INVAR
432d0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 IANTS:.**.** {H1
432e0 37 38 37 33 7d 20 41 20 73 75 63 63 65 73 73 66 7873} A successf
432f0 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 ul invocation of
43300 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 [sqlite3_blob_w
43310 72 69 74 65 28 50 2c 5a 2c 4e 2c 58 29 5d 0a 2a rite(P,Z,N,X)].*
43320 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c * shall
43330 20 77 72 69 74 65 20 4e 20 62 79 74 65 73 20 6f write N bytes o
43340 66 20 64 61 74 61 20 66 72 6f 6d 20 62 75 66 66 f data from buff
43350 65 72 20 5a 20 69 6e 74 6f 20 74 68 65 20 42 4c er Z into the BL
43360 4f 42 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 OB .**
43370 72 65 66 65 72 65 6e 63 65 64 20 62 79 20 5b 42 referenced by [B
43380 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 50 20 62 65 LOB handle] P be
43390 67 69 6e 6e 69 6e 67 20 61 74 20 6f 66 66 73 65 ginning at offse
433a0 74 20 58 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 t X into.**
433b0 20 20 20 20 20 74 68 65 20 42 4c 4f 42 2e 0a 2a the BLOB..*
433c0 2a 0a 2a 2a 20 7b 48 31 37 38 37 34 7d 20 49 6e *.** {H17874} In
433d0 20 74 68 65 20 61 62 73 65 6e 63 65 20 6f 66 20 the absence of
433e0 6f 74 68 65 72 20 6f 76 65 72 72 69 64 64 69 6e other overriddin
433f0 67 20 63 68 61 6e 67 65 73 2c 20 74 68 65 20 63 g changes, the c
43400 68 61 6e 67 65 73 0a 2a 2a 20 20 20 20 20 20 20 hanges.**
43410 20 20 20 77 72 69 74 74 65 6e 20 74 6f 20 61 20 written to a
43420 42 4c 4f 42 20 62 79 20 5b 73 71 6c 69 74 65 33 BLOB by [sqlite3
43430 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 73 _blob_write()] s
43440 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 hall.**
43450 20 72 65 6d 61 69 6e 20 69 6e 20 65 66 66 65 63 remain in effec
43460 74 20 61 66 74 65 72 20 74 68 65 20 61 73 73 6f t after the asso
43470 63 69 61 74 65 64 20 5b 42 4c 4f 42 20 68 61 6e ciated [BLOB han
43480 64 6c 65 5d 20 65 78 70 69 72 65 73 2e 0a 2a 2a dle] expires..**
43490 0a 2a 2a 20 7b 48 31 37 38 37 35 7d 20 49 66 20 .** {H17875} If
434a0 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 the [BLOB handle
434b0 5d 20 50 20 77 61 73 20 6f 70 65 6e 65 64 20 66 ] P was opened f
434c0 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 20 or reading only
434d0 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 then.**
434e0 20 61 6e 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f an invocation o
434f0 66 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f f [sqlite3_blob_
43500 77 72 69 74 65 28 50 2c 5a 2c 4e 2c 58 29 5d 20 write(P,Z,N,X)]
43510 73 68 61 6c 6c 20 6c 65 61 76 65 0a 2a 2a 20 20 shall leave.**
43520 20 20 20 20 20 20 20 20 74 68 65 20 72 65 66 65 the refe
43530 72 65 6e 63 65 64 20 42 4c 4f 42 20 75 6e 63 68 renced BLOB unch
43540 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e anged and return
43550 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c [SQLITE_READONL
43560 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 37 Y]..**.** {H1787
43570 36 7d 20 49 66 20 74 68 65 20 73 69 7a 65 20 6f 6} If the size o
43580 66 20 74 68 65 20 42 4c 4f 42 20 72 65 66 65 72 f the BLOB refer
43590 65 6e 63 65 64 20 62 79 20 5b 42 4c 4f 42 20 68 enced by [BLOB h
435a0 61 6e 64 6c 65 5d 20 50 20 69 73 0a 2a 2a 20 20 andle] P is.**
435b0 20 20 20 20 20 20 20 20 6c 65 73 73 20 74 68 61 less tha
435c0 6e 20 4e 2b 58 20 62 79 74 65 73 20 74 68 65 6e n N+X bytes then
435d0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 [sqlite3_blob_w
435e0 72 69 74 65 28 50 2c 5a 2c 4e 2c 58 29 5d 20 73 rite(P,Z,N,X)] s
435f0 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 hall.**
43600 20 6c 65 61 76 65 20 74 68 65 20 42 4c 4f 42 20 leave the BLOB
43610 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 unchanged and re
43620 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 turn [SQLITE_ERR
43630 4f 52 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 OR]..**.** {H178
43640 37 37 7d 20 49 66 20 74 68 65 20 5b 42 4c 4f 42 77} If the [BLOB
43650 20 68 61 6e 64 6c 65 5d 20 50 20 69 73 20 65 78 handle] P is ex
43660 70 69 72 65 64 20 61 6e 64 20 58 20 61 6e 64 20 pired and X and
43670 4e 20 61 72 65 20 77 69 74 68 69 6e 20 62 6f 75 N are within bou
43680 6e 64 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 nds.**
43690 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c then [sqlite3_bl
436a0 6f 62 5f 72 65 61 64 28 50 2c 5a 2c 4e 2c 58 29 ob_read(P,Z,N,X)
436b0 5d 20 73 68 61 6c 6c 20 6c 65 61 76 65 20 74 68 ] shall leave th
436c0 65 20 42 4c 4f 42 0a 2a 2a 20 20 20 20 20 20 20 e BLOB.**
436d0 20 20 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 unchanged and
436e0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
436f0 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ABORT]..**.** {H
43700 31 37 38 37 39 7d 20 49 66 20 58 20 6f 72 20 4e 17879} If X or N
43710 20 61 72 65 20 6c 65 73 73 20 74 68 61 6e 20 7a are less than z
43720 65 72 6f 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 ero then [sqlite
43730 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 50 2c 5a 3_blob_write(P,Z
43740 2c 4e 2c 58 29 5d 0a 2a 2a 20 20 20 20 20 20 20 ,N,X)].**
43750 20 20 20 73 68 61 6c 6c 20 6c 65 61 76 65 20 74 shall leave t
43760 68 65 20 42 4c 4f 42 20 72 65 66 65 72 65 6e 63 he BLOB referenc
43770 65 64 20 62 79 20 5b 42 4c 4f 42 20 68 61 6e 64 ed by [BLOB hand
43780 6c 65 5d 20 50 20 75 6e 63 68 61 6e 67 65 64 0a le] P unchanged.
43790 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 ** and
437a0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 return [SQLITE_E
437b0 52 52 4f 52 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 RROR]..**.** {H1
437c0 37 38 38 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 7882} The [sqlit
437d0 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 50 2c e3_blob_write(P,
437e0 5a 2c 4e 2c 58 29 5d 20 69 6e 74 65 72 66 61 63 Z,N,X)] interfac
437f0 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 0a 2a e shall return.*
43800 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 * [SQLI
43810 54 45 5f 4f 4b 5d 20 69 66 20 4e 20 62 79 74 65 TE_OK] if N byte
43820 73 20 77 68 65 72 65 20 73 75 63 63 65 73 73 66 s where successf
43830 75 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 ully written int
43840 6f 20 74 68 65 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a o the BLOB..**.*
43850 2a 20 7b 48 31 37 38 38 35 7d 20 49 66 20 74 68 * {H17885} If th
43860 65 20 72 65 71 75 65 73 74 65 64 20 77 72 69 74 e requested writ
43870 65 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 e could not be c
43880 6f 6d 70 6c 65 74 65 64 2c 0a 2a 2a 20 20 20 20 ompleted,.**
43890 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 the [sqlit
438a0 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 50 2c e3_blob_write(P,
438b0 5a 2c 4e 2c 58 29 5d 20 69 6e 74 65 72 66 61 63 Z,N,X)] interfac
438c0 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 61 e shall return a
438d0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 70 n.** ap
438e0 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 propriate [error
438f0 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e code] or [exten
43900 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e ded error code].
43910 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 38 38 7d 20 .**.** {H17888}
43920 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 If an error occu
43930 72 73 20 64 75 72 69 6e 67 20 65 76 61 6c 75 61 rs during evalua
43940 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 tion of [sqlite3
43950 5f 62 6c 6f 62 5f 77 72 69 74 65 28 44 2c 2e 2e _blob_write(D,..
43960 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 .)].**
43970 74 68 65 6e 20 73 75 62 73 65 71 75 65 6e 74 20 then subsequent
43980 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
43990 33 5f 65 72 72 63 6f 64 65 28 44 29 5d 2c 0a 2a 3_errcode(D)],.*
439a0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
439b0 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 te3_extended_err
439c0 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 code()],.**
439d0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 [sqlite3_er
439e0 72 6d 73 67 28 44 29 5d 2c 20 61 6e 64 20 5b 73 rmsg(D)], and [s
439f0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 qlite3_errmsg16(
43a00 44 29 5d 20 73 68 61 6c 6c 20 72 65 74 75 72 6e D)] shall return
43a10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 66 .** inf
43a20 6f 72 6d 61 74 69 6f 6e 20 61 70 70 72 6f 70 72 ormation appropr
43a30 69 61 74 65 20 66 6f 72 20 74 68 61 74 20 65 72 iate for that er
43a40 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ror..*/.int sqli
43a50 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 73 te3_blob_write(s
43a60 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 63 qlite3_blob *, c
43a70 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20 69 6e onst void *z, in
43a80 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 t n, int iOffset
43a90 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
43aa0 45 46 3a 20 56 69 72 74 75 61 6c 20 46 69 6c 65 EF: Virtual File
43ab0 20 53 79 73 74 65 6d 20 4f 62 6a 65 63 74 73 20 System Objects
43ac0 7b 48 31 31 32 30 30 7d 20 3c 53 32 30 31 30 30 {H11200} <S20100
43ad0 3e 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61 >.**.** A virtua
43ae0 6c 20 66 69 6c 65 73 79 73 74 65 6d 20 28 56 46 l filesystem (VF
43af0 53 29 20 69 73 20 61 6e 20 5b 73 71 6c 69 74 65 S) is an [sqlite
43b00 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a 3_vfs] object.**
43b10 20 74 68 61 74 20 53 51 4c 69 74 65 20 75 73 65 that SQLite use
43b20 73 20 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a 2a s to interact.**
43b30 20 77 69 74 68 20 74 68 65 20 75 6e 64 65 72 6c with the underl
43b40 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 ying operating s
43b50 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20 53 51 4c ystem. Most SQL
43b60 69 74 65 20 62 75 69 6c 64 73 20 63 6f 6d 65 20 ite builds come
43b70 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 with a.** single
43b80 20 64 65 66 61 75 6c 74 20 56 46 53 20 74 68 61 default VFS tha
43b90 74 20 69 73 20 61 70 70 72 6f 70 72 69 61 74 65 t is appropriate
43ba0 20 66 6f 72 20 74 68 65 20 68 6f 73 74 20 63 6f for the host co
43bb0 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20 56 mputer..** New V
43bc0 46 53 65 73 20 63 61 6e 20 62 65 20 72 65 67 69 FSes can be regi
43bd0 73 74 65 72 65 64 20 61 6e 64 20 65 78 69 73 74 stered and exist
43be0 69 6e 67 20 56 46 53 65 73 20 63 61 6e 20 62 65 ing VFSes can be
43bf0 20 75 6e 72 65 67 69 73 74 65 72 65 64 2e 0a 2a unregistered..*
43c00 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 * The following
43c10 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 interfaces are p
43c20 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 rovided..**.** T
43c30 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 he sqlite3_vfs_f
43c40 69 6e 64 28 29 20 69 6e 74 65 72 66 61 63 65 20 ind() interface
43c50 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
43c60 72 20 74 6f 20 61 20 56 46 53 20 67 69 76 65 6e r to a VFS given
43c70 20 69 74 73 20 6e 61 6d 65 2e 0a 2a 2a 20 4e 61 its name..** Na
43c80 6d 65 73 20 61 72 65 20 63 61 73 65 20 73 65 6e mes are case sen
43c90 73 69 74 69 76 65 2e 0a 2a 2a 20 4e 61 6d 65 73 sitive..** Names
43ca0 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e are zero-termin
43cb0 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e ated UTF-8 strin
43cc0 67 73 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 gs..** If there
43cd0 69 73 20 6e 6f 20 6d 61 74 63 68 2c 20 61 20 4e is no match, a N
43ce0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 ULL pointer is r
43cf0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 7a eturned..** If z
43d00 56 66 73 4e 61 6d 65 20 69 73 20 4e 55 4c 4c 20 VfsName is NULL
43d10 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 then the default
43d20 20 56 46 53 20 69 73 20 72 65 74 75 72 6e 65 64 VFS is returned
43d30 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 56 46 53 65 ..**.** New VFSe
43d40 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64 s are registered
43d50 20 77 69 74 68 20 73 71 6c 69 74 65 33 5f 76 66 with sqlite3_vf
43d60 73 5f 72 65 67 69 73 74 65 72 28 29 2e 0a 2a 2a s_register()..**
43d70 20 45 61 63 68 20 6e 65 77 20 56 46 53 20 62 65 Each new VFS be
43d80 63 6f 6d 65 73 20 74 68 65 20 64 65 66 61 75 6c comes the defaul
43d90 74 20 56 46 53 20 69 66 20 74 68 65 20 6d 61 6b t VFS if the mak
43da0 65 44 66 6c 74 20 66 6c 61 67 20 69 73 20 73 65 eDflt flag is se
43db0 74 2e 0a 2a 2a 20 54 68 65 20 73 61 6d 65 20 56 t..** The same V
43dc0 46 53 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 FS can be regist
43dd0 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 ered multiple ti
43de0 6d 65 73 20 77 69 74 68 6f 75 74 20 69 6e 6a 75 mes without inju
43df0 72 79 2e 0a 2a 2a 20 54 6f 20 6d 61 6b 65 20 61 ry..** To make a
43e00 6e 20 65 78 69 73 74 69 6e 67 20 56 46 53 20 69 n existing VFS i
43e10 6e 74 6f 20 74 68 65 20 64 65 66 61 75 6c 74 20 nto the default
43e20 56 46 53 2c 20 72 65 67 69 73 74 65 72 20 69 74 VFS, register it
43e30 20 61 67 61 69 6e 0a 2a 2a 20 77 69 74 68 20 74 again.** with t
43e40 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 he makeDflt flag
43e50 20 73 65 74 2e 20 20 49 66 20 74 77 6f 20 64 69 set. If two di
43e60 66 66 65 72 65 6e 74 20 56 46 53 65 73 20 77 69 fferent VFSes wi
43e70 74 68 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 6e th the.** same n
43e80 61 6d 65 20 61 72 65 20 72 65 67 69 73 74 65 72 ame are register
43e90 65 64 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 ed, the behavior
43ea0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 is undefined.
43eb0 49 66 20 61 0a 2a 2a 20 56 46 53 20 69 73 20 72 If a.** VFS is r
43ec0 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 61 egistered with a
43ed0 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20 4e 55 name that is NU
43ee0 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 LL or an empty s
43ef0 74 72 69 6e 67 2c 0a 2a 2a 20 74 68 65 6e 20 74 tring,.** then t
43f00 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 he behavior is u
43f10 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
43f20 55 6e 72 65 67 69 73 74 65 72 20 61 20 56 46 53 Unregister a VFS
43f30 20 77 69 74 68 20 74 68 65 20 73 71 6c 69 74 65 with the sqlite
43f40 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 3_vfs_unregister
43f50 28 29 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a () interface..**
43f60 20 49 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 If the default
43f70 56 46 53 20 69 73 20 75 6e 72 65 67 69 73 74 65 VFS is unregiste
43f80 72 65 64 2c 20 61 6e 6f 74 68 65 72 20 56 46 53 red, another VFS
43f90 20 69 73 20 63 68 6f 73 65 6e 20 61 73 0a 2a 2a is chosen as.**
43fa0 20 74 68 65 20 64 65 66 61 75 6c 74 2e 20 20 54 the default. T
43fb0 68 65 20 63 68 6f 69 63 65 20 66 6f 72 20 74 68 he choice for th
43fc0 65 20 6e 65 77 20 56 46 53 20 69 73 20 61 72 62 e new VFS is arb
43fd0 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e itrary..**.** IN
43fe0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
43ff0 7b 48 31 31 32 30 33 7d 20 54 68 65 20 5b 73 71 {H11203} The [sq
44000 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 4e lite3_vfs_find(N
44010 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
44020 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
44030 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 o the.**
44040 20 20 72 65 67 69 73 74 65 72 65 64 20 5b 73 71 registered [sq
44050 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 lite3_vfs] objec
44060 74 20 77 68 6f 73 65 20 6e 61 6d 65 20 65 78 61 t whose name exa
44070 63 74 6c 79 20 6d 61 74 63 68 65 73 0a 2a 2a 20 ctly matches.**
44080 20 20 20 20 20 20 20 20 20 74 68 65 20 7a 65 72 the zer
44090 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 o-terminated UTF
440a0 2d 38 20 73 74 72 69 6e 67 20 4e 2c 20 6f 72 20 -8 string N, or
440b0 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 it returns NULL
440c0 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 if.** t
440d0 68 65 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 here is no match
440e0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 32 30 36 7d ..**.** {H11206}
440f0 20 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65 If the N parame
44100 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
44110 76 66 73 5f 66 69 6e 64 28 4e 29 5d 20 69 73 20 vfs_find(N)] is
44120 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 NULL then.**
44130 20 20 20 20 20 20 74 68 65 20 66 75 6e 63 74 69 the functi
44140 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 on returns a poi
44150 6e 74 65 72 20 74 6f 20 74 68 65 20 64 65 66 61 nter to the defa
44160 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 ult [sqlite3_vfs
44170 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 ].** ob
44180 6a 65 63 74 20 69 66 20 74 68 65 72 65 20 69 73 ject if there is
44190 20 6f 6e 65 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 one, or NULL if
441a0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 65 66 there is no def
441b0 61 75 6c 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 ault.**
441c0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f [sqlite3_vfs] o
441d0 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 bject..**.** {H1
441e0 31 32 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 1209} The [sqlit
441f0 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 e3_vfs_register(
44200 50 2c 46 29 5d 20 69 6e 74 65 72 66 61 63 65 20 P,F)] interface
44210 72 65 67 69 73 74 65 72 73 20 74 68 65 0a 2a 2a registers the.**
44220 20 20 20 20 20 20 20 20 20 20 77 65 6c 6c 2d 66 well-f
44230 6f 72 6d 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 ormed [sqlite3_v
44240 66 73 5d 20 6f 62 6a 65 63 74 20 50 20 75 73 69 fs] object P usi
44250 6e 67 20 74 68 65 20 6e 61 6d 65 20 67 69 76 65 ng the name give
44260 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 n.** by
44270 20 74 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 the zName field
44280 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 2e 0a of the object..
44290 2a 2a 0a 2a 2a 20 7b 48 31 31 32 31 32 7d 20 55 **.** {H11212} U
442a0 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 sing the [sqlite
442b0 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 50 3_vfs_register(P
442c0 2c 46 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 ,F)] interface t
442d0 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 20 20 o register.**
442e0 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 the same
442f0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 [sqlite3_vfs] ob
44300 6a 65 63 74 20 6d 75 6c 74 69 70 6c 65 20 74 69 ject multiple ti
44310 6d 65 73 20 69 73 20 61 20 68 61 72 6d 6c 65 73 mes is a harmles
44320 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b s no-op..**.** {
44330 48 31 31 32 31 35 7d 20 54 68 65 20 5b 73 71 6c H11215} The [sql
44340 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 ite3_vfs_registe
44350 72 28 50 2c 46 29 5d 20 69 6e 74 65 72 66 61 63 r(P,F)] interfac
44360 65 20 6d 61 6b 65 73 20 74 68 65 20 5b 73 71 6c e makes the [sql
44370 69 74 65 33 5f 76 66 73 5d 0a 2a 2a 20 20 20 20 ite3_vfs].**
44380 20 20 20 20 20 20 6f 62 6a 65 63 74 20 50 20 74 object P t
44390 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 he default [sqli
443a0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 te3_vfs] object
443b0 69 66 20 46 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f if F is non-zero
443c0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 32 31 38 7d ..**.** {H11218}
443d0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 The [sqlite3_vf
443e0 73 5f 75 6e 72 65 67 69 73 74 65 72 28 50 29 5d s_unregister(P)]
443f0 20 69 6e 74 65 72 66 61 63 65 20 75 6e 72 65 67 interface unreg
44400 69 73 74 65 72 73 20 74 68 65 0a 2a 2a 20 20 20 isters the.**
44410 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
44420 76 66 73 5d 20 6f 62 6a 65 63 74 20 50 20 73 6f vfs] object P so
44430 20 74 68 61 74 20 69 74 20 69 73 20 6e 6f 20 6c that it is no l
44440 6f 6e 67 65 72 20 72 65 74 75 72 6e 65 64 20 62 onger returned b
44450 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 75 y.** su
44460 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 bsequent calls t
44470 6f 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 o [sqlite3_vfs_f
44480 69 6e 64 28 29 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 ind()]..*/.sqlit
44490 65 33 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 5f e3_vfs *sqlite3_
444a0 76 66 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63 vfs_find(const c
444b0 68 61 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a har *zVfsName);.
444c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f int sqlite3_vfs_
444d0 72 65 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 register(sqlite3
444e0 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 _vfs*, int makeD
444f0 66 6c 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 flt);.int sqlite
44500 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 3_vfs_unregister
44510 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a (sqlite3_vfs*);.
44520 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
44530 20 4d 75 74 65 78 65 73 20 7b 48 31 37 30 30 30 Mutexes {H17000
44540 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a } <S20000>.**.**
44550 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 The SQLite core
44560 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 uses these rout
44570 69 6e 65 73 20 66 6f 72 20 74 68 72 65 61 64 0a ines for thread.
44580 2a 2a 20 73 79 6e 63 68 72 6f 6e 69 7a 61 74 69 ** synchronizati
44590 6f 6e 2e 20 54 68 6f 75 67 68 20 74 68 65 79 20 on. Though they
445a0 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 are intended for
445b0 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 internal.** use
445c0 20 62 79 20 53 51 4c 69 74 65 2c 20 63 6f 64 65 by SQLite, code
445d0 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 that links agai
445e0 6e 73 74 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a nst SQLite is.**
445f0 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 75 73 permitted to us
44600 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 e any of these r
44610 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 outines..**.** T
44620 68 65 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 he SQLite source
44630 20 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 6d code contains m
44640 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e ultiple implemen
44650 74 61 74 69 6f 6e 73 0a 2a 2a 20 6f 66 20 74 68 tations.** of th
44660 65 73 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e ese mutex routin
44670 65 73 2e 20 20 41 6e 20 61 70 70 72 6f 70 72 69 es. An appropri
44680 61 74 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ate implementati
44690 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c 65 63 74 65 on.** is selecte
446a0 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 d automatically
446b0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e at compile-time.
446c0 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a The following.
446d0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
446e0 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 ns are available
446f0 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 63 in the SQLite c
44700 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a ore:.**.** <ul>.
44710 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 ** <li> SQLITE
44720 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c _MUTEX_OS2.** <l
44730 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 i> SQLITE_MUTE
44740 58 5f 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 X_PTHREAD.** <li
44750 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 > SQLITE_MUTEX
44760 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 _W32.** <li> S
44770 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 QLITE_MUTEX_NOOP
44780 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
44790 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 The SQLITE_MUTEX
447a0 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74 61 _NOOP implementa
447b0 74 69 6f 6e 20 69 73 20 61 20 73 65 74 20 6f 66 tion is a set of
447c0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 74 68 61 routines.** tha
447d0 74 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c 20 6c t does no real l
447e0 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73 20 61 70 ocking and is ap
447f0 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73 propriate for us
44800 65 20 69 6e 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 e in.** a single
44810 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 -threaded applic
44820 61 74 69 6f 6e 2e 20 20 54 68 65 20 53 51 4c 49 ation. The SQLI
44830 54 45 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a TE_MUTEX_OS2,.**
44840 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 SQLITE_MUTEX_PT
44850 48 52 45 41 44 2c 20 61 6e 64 20 53 51 4c 49 54 HREAD, and SQLIT
44860 45 5f 4d 55 54 45 58 5f 57 33 32 20 69 6d 70 6c E_MUTEX_W32 impl
44870 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 ementations.** a
44880 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 re appropriate f
44890 6f 72 20 75 73 65 20 6f 6e 20 4f 53 2f 32 2c 20 or use on OS/2,
448a0 55 6e 69 78 2c 20 61 6e 64 20 57 69 6e 64 6f 77 Unix, and Window
448b0 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 53 51 4c 69 s..**.** If SQLi
448c0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
448d0 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 4d ith the SQLITE_M
448e0 55 54 45 58 5f 41 50 50 44 45 46 20 70 72 65 70 UTEX_APPDEF prep
448f0 72 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d 61 63 72 rocessor.** macr
44900 6f 20 64 65 66 69 6e 65 64 20 28 77 69 74 68 20 o defined (with
44910 22 2d 44 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f "-DSQLITE_MUTEX_
44920 41 50 50 44 45 46 3d 31 22 29 2c 20 74 68 65 6e APPDEF=1"), then
44930 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 no mutex.** imp
44940 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 69 lementation is i
44950 6e 63 6c 75 64 65 64 20 77 69 74 68 20 74 68 65 ncluded with the
44960 20 6c 69 62 72 61 72 79 2e 20 49 6e 20 74 68 69 library. In thi
44970 73 20 63 61 73 65 20 74 68 65 0a 2a 2a 20 61 70 s case the.** ap
44980 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 plication must s
44990 75 70 70 6c 79 20 61 20 63 75 73 74 6f 6d 20 6d upply a custom m
449a0 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 utex implementat
449b0 69 6f 6e 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a ion using the.**
449c0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
449d0 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 20 6f 66 MUTEX] option of
449e0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e the sqlite3_con
449f0 66 69 67 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a fig() function.*
44a00 2a 20 62 65 66 6f 72 65 20 63 61 6c 6c 69 6e 67 * before calling
44a10 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
44a20 69 7a 65 28 29 20 6f 72 20 61 6e 79 20 6f 74 68 ize() or any oth
44a30 65 72 20 70 75 62 6c 69 63 20 73 71 6c 69 74 65 er public sqlite
44a40 33 5f 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 3_.** function t
44a50 68 61 74 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 hat calls sqlite
44a60 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 3_initialize()..
44a70 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 31 7d 20 54 **.** {H17011} T
44a80 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 he sqlite3_mutex
44a90 5f 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 _alloc() routine
44aa0 20 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65 77 allocates a new
44ab0 0a 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20 72 65 .** mutex and re
44ac0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
44ad0 74 6f 20 69 74 2e 20 7b 48 31 37 30 31 32 7d 20 to it. {H17012}
44ae0 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 If it returns NU
44af0 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d 65 61 6e 73 LL.** that means
44b00 20 74 68 61 74 20 61 20 6d 75 74 65 78 20 63 6f that a mutex co
44b10 75 6c 64 20 6e 6f 74 20 62 65 20 61 6c 6c 6f 63 uld not be alloc
44b20 61 74 65 64 2e 20 7b 48 31 37 30 31 33 7d 20 53 ated. {H17013} S
44b30 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e QLite.** will un
44b40 77 69 6e 64 20 69 74 73 20 73 74 61 63 6b 20 61 wind its stack a
44b50 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 nd return an err
44b60 6f 72 2e 20 7b 48 31 37 30 31 34 7d 20 54 68 65 or. {H17014} The
44b70 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 argument.** to
44b80 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c sqlite3_mutex_al
44b90 6c 6f 63 28 29 20 69 73 20 6f 6e 65 20 6f 66 20 loc() is one of
44ba0 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f these integer co
44bb0 6e 73 74 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c nstants:.**.** <
44bc0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c ul>.** <li> SQL
44bd0 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a ITE_MUTEX_FAST.*
44be0 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d * <li> SQLITE_M
44bf0 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a UTEX_RECURSIVE.*
44c00 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d * <li> SQLITE_M
44c10 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 UTEX_STATIC_MAST
44c20 45 52 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 ER.** <li> SQLI
44c30 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
44c40 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c MEM.** <li> SQL
44c50 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 ITE_MUTEX_STATIC
44c60 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 3e 20 20 53 _MEM2.** <li> S
44c70 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 QLITE_MUTEX_STAT
44c80 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c 6c 69 3e 20 IC_PRNG.** <li>
44c90 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 SQLITE_MUTEX_ST
44ca0 41 54 49 43 5f 4c 52 55 0a 2a 2a 20 3c 6c 69 3e ATIC_LRU.** <li>
44cb0 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 SQLITE_MUTEX_S
44cc0 54 41 54 49 43 5f 4c 52 55 32 0a 2a 2a 20 3c 2f TATIC_LRU2.** </
44cd0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 ul>.**.** {H1701
44ce0 35 7d 20 54 68 65 20 66 69 72 73 74 20 74 77 6f 5} The first two
44cf0 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 75 73 65 constants cause
44d00 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 sqlite3_mutex_a
44d10 6c 6c 6f 63 28 29 20 74 6f 20 63 72 65 61 74 65 lloc() to create
44d20 0a 2a 2a 20 61 20 6e 65 77 20 6d 75 74 65 78 2e .** a new mutex.
44d30 20 20 54 68 65 20 6e 65 77 20 6d 75 74 65 78 20 The new mutex
44d40 69 73 20 72 65 63 75 72 73 69 76 65 20 77 68 65 is recursive whe
44d50 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 n SQLITE_MUTEX_R
44d60 45 43 55 52 53 49 56 45 0a 2a 2a 20 69 73 20 75 ECURSIVE.** is u
44d70 73 65 64 20 62 75 74 20 6e 6f 74 20 6e 65 63 65 sed but not nece
44d80 73 73 61 72 69 6c 79 20 73 6f 20 77 68 65 6e 20 ssarily so when
44d90 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 SQLITE_MUTEX_FAS
44da0 54 20 69 73 20 75 73 65 64 2e 20 7b 45 4e 44 7d T is used. {END}
44db0 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 69 6d .** The mutex im
44dc0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 plementation doe
44dd0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d 61 s not need to ma
44de0 6b 65 20 61 20 64 69 73 74 69 6e 63 74 69 6f 6e ke a distinction
44df0 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 .** between SQLI
44e00 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 TE_MUTEX_RECURSI
44e10 56 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 VE and SQLITE_MU
44e20 54 45 58 5f 46 41 53 54 20 69 66 20 69 74 20 64 TEX_FAST if it d
44e30 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 oes.** not want
44e40 74 6f 2e 20 20 7b 48 31 37 30 31 36 7d 20 42 75 to. {H17016} Bu
44e50 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e t SQLite will on
44e60 6c 79 20 72 65 71 75 65 73 74 20 61 20 72 65 63 ly request a rec
44e70 75 72 73 69 76 65 20 6d 75 74 65 78 20 69 6e 0a ursive mutex in.
44e80 2a 2a 20 63 61 73 65 73 20 77 68 65 72 65 20 69 ** cases where i
44e90 74 20 72 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f t really needs o
44ea0 6e 65 2e 20 20 7b 45 4e 44 7d 20 49 66 20 61 20 ne. {END} If a
44eb0 66 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63 75 72 faster non-recur
44ec0 73 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20 69 6d sive mutex.** im
44ed0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 plementation is
44ee0 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65 available on the
44ef0 20 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d 2c 20 host platform,
44f00 74 68 65 20 6d 75 74 65 78 20 73 75 62 73 79 73 the mutex subsys
44f10 74 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 65 74 tem.** might ret
44f20 75 72 6e 20 73 75 63 68 20 61 20 6d 75 74 65 78 urn such a mutex
44f30 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 in response to
44f40 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 SQLITE_MUTEX_FAS
44f50 54 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 37 T..**.** {H17017
44f60 7d 20 54 68 65 20 6f 74 68 65 72 20 61 6c 6c 6f } The other allo
44f70 77 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 74 wed parameters t
44f80 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f o sqlite3_mutex_
44f90 61 6c 6c 6f 63 28 29 20 65 61 63 68 20 72 65 74 alloc() each ret
44fa0 75 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 urn.** a pointer
44fb0 20 74 6f 20 61 20 73 74 61 74 69 63 20 70 72 65 to a static pre
44fc0 65 78 69 73 74 69 6e 67 20 6d 75 74 65 78 2e 20 existing mutex.
44fd0 7b 45 4e 44 7d 20 20 46 6f 75 72 20 73 74 61 74 {END} Four stat
44fe0 69 63 20 6d 75 74 65 78 65 73 20 61 72 65 0a 2a ic mutexes are.*
44ff0 2a 20 75 73 65 64 20 62 79 20 74 68 65 20 63 75 * used by the cu
45000 72 72 65 6e 74 20 76 65 72 73 69 6f 6e 20 6f 66 rrent version of
45010 20 53 51 4c 69 74 65 2e 20 20 46 75 74 75 72 65 SQLite. Future
45020 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
45030 69 74 65 0a 2a 2a 20 6d 61 79 20 61 64 64 20 61 ite.** may add a
45040 64 64 69 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 dditional static
45050 20 6d 75 74 65 78 65 73 2e 20 20 53 74 61 74 69 mutexes. Stati
45060 63 20 6d 75 74 65 78 65 73 20 61 72 65 20 66 6f c mutexes are fo
45070 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 r internal.** us
45080 65 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 6c 79 e by SQLite only
45090 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 . Applications
450a0 74 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 20 that use SQLite
450b0 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 0a 2a mutexes should.*
450c0 2a 20 75 73 65 20 6f 6e 6c 79 20 74 68 65 20 64 * use only the d
450d0 79 6e 61 6d 69 63 20 6d 75 74 65 78 65 73 20 72 ynamic mutexes r
450e0 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 49 54 eturned by SQLIT
450f0 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 6f 72 0a E_MUTEX_FAST or.
45100 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f ** SQLITE_MUTEX_
45110 52 45 43 55 52 53 49 56 45 2e 0a 2a 2a 0a 2a 2a RECURSIVE..**.**
45120 20 7b 48 31 37 30 31 38 7d 20 4e 6f 74 65 20 74 {H17018} Note t
45130 68 61 74 20 69 66 20 6f 6e 65 20 6f 66 20 74 68 hat if one of th
45140 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 e dynamic mutex
45150 70 61 72 61 6d 65 74 65 72 73 20 28 53 51 4c 49 parameters (SQLI
45160 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a TE_MUTEX_FAST.**
45170 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 or SQLITE_MUTEX
45180 5f 52 45 43 55 52 53 49 56 45 29 20 69 73 20 75 _RECURSIVE) is u
45190 73 65 64 20 74 68 65 6e 20 73 71 6c 69 74 65 33 sed then sqlite3
451a0 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a _mutex_alloc().*
451b0 2a 20 72 65 74 75 72 6e 73 20 61 20 64 69 66 66 * returns a diff
451c0 65 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65 erent mutex on e
451d0 76 65 72 79 20 63 61 6c 6c 2e 20 20 7b 48 31 37 very call. {H17
451e0 30 33 34 7d 20 42 75 74 20 66 6f 72 20 74 68 65 034} But for the
451f0 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 static.** mutex
45200 20 74 79 70 65 73 2c 20 74 68 65 20 73 61 6d 65 types, the same
45210 20 6d 75 74 65 78 20 69 73 20 72 65 74 75 72 6e mutex is return
45220 65 64 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c ed on every call
45230 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 74 68 65 that has.** the
45240 20 73 61 6d 65 20 74 79 70 65 20 6e 75 6d 62 65 same type numbe
45250 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 39 r..**.** {H17019
45260 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 } The sqlite3_mu
45270 74 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74 69 tex_free() routi
45280 6e 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 ne deallocates a
45290 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61 previously.** a
452a0 6c 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69 63 llocated dynamic
452b0 20 6d 75 74 65 78 2e 20 7b 48 31 37 30 32 30 7d mutex. {H17020}
452c0 20 53 51 4c 69 74 65 20 69 73 20 63 61 72 65 66 SQLite is caref
452d0 75 6c 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 ul to deallocate
452e0 20 65 76 65 72 79 0a 2a 2a 20 64 79 6e 61 6d 69 every.** dynami
452f0 63 20 6d 75 74 65 78 20 74 68 61 74 20 69 74 20 c mutex that it
45300 61 6c 6c 6f 63 61 74 65 73 2e 20 7b 41 31 37 30 allocates. {A170
45310 32 31 7d 20 54 68 65 20 64 79 6e 61 6d 69 63 20 21} The dynamic
45320 6d 75 74 65 78 65 73 20 6d 75 73 74 20 6e 6f 74 mutexes must not
45330 20 62 65 20 69 6e 0a 2a 2a 20 75 73 65 20 77 68 be in.** use wh
45340 65 6e 20 74 68 65 79 20 61 72 65 20 64 65 61 6c en they are deal
45350 6c 6f 63 61 74 65 64 2e 20 7b 41 31 37 30 32 32 located. {A17022
45360 7d 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 } Attempting to
45370 64 65 61 6c 6c 6f 63 61 74 65 20 61 20 73 74 61 deallocate a sta
45380 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20 72 65 73 tic.** mutex res
45390 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 ults in undefine
453a0 64 20 62 65 68 61 76 69 6f 72 2e 20 7b 48 31 37 d behavior. {H17
453b0 30 32 33 7d 20 53 51 4c 69 74 65 20 6e 65 76 65 023} SQLite neve
453c0 72 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a r deallocates.**
453d0 20 61 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e a static mutex.
453e0 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 {END}.**.** The
453f0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 sqlite3_mutex_e
45400 6e 74 65 72 28 29 20 61 6e 64 20 73 71 6c 69 74 nter() and sqlit
45410 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 72 e3_mutex_try() r
45420 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 0a outines attempt.
45430 2a 2a 20 74 6f 20 65 6e 74 65 72 20 61 20 6d 75 ** to enter a mu
45440 74 65 78 2e 20 7b 48 31 37 30 32 34 7d 20 49 66 tex. {H17024} If
45450 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 another thread
45460 69 73 20 61 6c 72 65 61 64 79 20 77 69 74 68 69 is already withi
45470 6e 20 74 68 65 20 6d 75 74 65 78 2c 0a 2a 2a 20 n the mutex,.**
45480 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e sqlite3_mutex_en
45490 74 65 72 28 29 20 77 69 6c 6c 20 62 6c 6f 63 6b ter() will block
454a0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 and sqlite3_mut
454b0 65 78 5f 74 72 79 28 29 20 77 69 6c 6c 20 72 65 ex_try() will re
454c0 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 turn.** SQLITE_B
454d0 55 53 59 2e 20 7b 48 31 37 30 32 35 7d 20 20 54 USY. {H17025} T
454e0 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 he sqlite3_mutex
454f0 5f 74 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 _try() interface
45500 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
45510 5f 4f 4b 5d 0a 2a 2a 20 75 70 6f 6e 20 73 75 63 _OK].** upon suc
45520 63 65 73 73 66 75 6c 20 65 6e 74 72 79 2e 20 20 cessful entry.
45530 7b 48 31 37 30 32 36 7d 20 4d 75 74 65 78 65 73 {H17026} Mutexes
45540 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a created using.*
45550 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 * SQLITE_MUTEX_R
45560 45 43 55 52 53 49 56 45 20 63 61 6e 20 62 65 20 ECURSIVE can be
45570 65 6e 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 entered multiple
45580 20 74 69 6d 65 73 20 62 79 20 74 68 65 20 73 61 times by the sa
45590 6d 65 20 74 68 72 65 61 64 2e 0a 2a 2a 20 7b 48 me thread..** {H
455a0 31 37 30 32 37 7d 20 49 6e 20 73 75 63 68 20 63 17027} In such c
455b0 61 73 65 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 ases the,.** mut
455c0 65 78 20 6d 75 73 74 20 62 65 20 65 78 69 74 65 ex must be exite
455d0 64 20 61 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65 d an equal numbe
455e0 72 20 6f 66 20 74 69 6d 65 73 20 62 65 66 6f 72 r of times befor
455f0 65 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 e another thread
45600 0a 2a 2a 20 63 61 6e 20 65 6e 74 65 72 2e 20 20 .** can enter.
45610 7b 41 31 37 30 32 38 7d 20 49 66 20 74 68 65 20 {A17028} If the
45620 73 61 6d 65 20 74 68 72 65 61 64 20 74 72 69 65 same thread trie
45630 73 20 74 6f 20 65 6e 74 65 72 20 61 6e 79 20 6f s to enter any o
45640 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 ther.** kind of
45650 6d 75 74 65 78 20 6d 6f 72 65 20 74 68 61 6e 20 mutex more than
45660 6f 6e 63 65 2c 20 74 68 65 20 62 65 68 61 76 69 once, the behavi
45670 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e or is undefined.
45680 0a 2a 2a 20 7b 48 31 37 30 32 39 7d 20 53 51 4c .** {H17029} SQL
45690 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 65 ite will never e
456a0 78 68 69 62 69 74 0a 2a 2a 20 73 75 63 68 20 62 xhibit.** such b
456b0 65 68 61 76 69 6f 72 20 69 6e 20 69 74 73 20 6f ehavior in its o
456c0 77 6e 20 75 73 65 20 6f 66 20 6d 75 74 65 78 65 wn use of mutexe
456d0 73 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 73 79 s..**.** Some sy
456e0 73 74 65 6d 73 20 28 66 6f 72 20 65 78 61 6d 70 stems (for examp
456f0 6c 65 2c 20 57 69 6e 64 6f 77 73 20 39 35 29 20 le, Windows 95)
45700 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 74 do not support t
45710 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 he operation.**
45720 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 73 implemented by s
45730 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 qlite3_mutex_try
45740 28 29 2e 20 20 4f 6e 20 74 68 6f 73 65 20 73 79 (). On those sy
45750 73 74 65 6d 73 2c 20 73 71 6c 69 74 65 33 5f 6d stems, sqlite3_m
45760 75 74 65 78 5f 74 72 79 28 29 0a 2a 2a 20 77 69 utex_try().** wi
45770 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e ll always return
45780 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 7b SQLITE_BUSY. {
45790 48 31 37 30 33 30 7d 20 54 68 65 20 53 51 4c 69 H17030} The SQLi
457a0 74 65 20 63 6f 72 65 20 6f 6e 6c 79 20 65 76 65 te core only eve
457b0 72 20 75 73 65 73 0a 2a 2a 20 73 71 6c 69 74 65 r uses.** sqlite
457c0 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 61 73 3_mutex_try() as
457d0 20 61 6e 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e an optimization
457e0 20 73 6f 20 74 68 69 73 20 69 73 20 61 63 63 65 so this is acce
457f0 70 74 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e ptable behavior.
45800 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 33 31 7d 20 .**.** {H17031}
45810 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 The sqlite3_mute
45820 78 5f 6c 65 61 76 65 28 29 20 72 6f 75 74 69 6e x_leave() routin
45830 65 20 65 78 69 74 73 20 61 20 6d 75 74 65 78 20 e exits a mutex
45840 74 68 61 74 20 77 61 73 0a 2a 2a 20 70 72 65 76 that was.** prev
45850 69 6f 75 73 6c 79 20 65 6e 74 65 72 65 64 20 62 iously entered b
45860 79 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 y the same threa
45870 64 2e 20 20 7b 41 31 37 30 33 32 7d 20 54 68 65 d. {A17032} The
45880 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 behavior.** is
45890 75 6e 64 65 66 69 6e 65 64 20 69 66 20 74 68 65 undefined if the
458a0 20 6d 75 74 65 78 20 69 73 20 6e 6f 74 20 63 75 mutex is not cu
458b0 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 rrently entered
458c0 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e by the.** callin
458d0 67 20 74 68 72 65 61 64 20 6f 72 20 69 73 20 6e g thread or is n
458e0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c ot currently all
458f0 6f 63 61 74 65 64 2e 20 20 7b 48 31 37 30 33 33 ocated. {H17033
45900 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a } SQLite will.**
45910 20 6e 65 76 65 72 20 64 6f 20 65 69 74 68 65 72 never do either
45920 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 . {END}.**.** If
45930 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f the argument to
45940 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 sqlite3_mutex_e
45950 6e 74 65 72 28 29 2c 20 73 71 6c 69 74 65 33 5f nter(), sqlite3_
45960 6d 75 74 65 78 5f 74 72 79 28 29 2c 20 6f 72 0a mutex_try(), or.
45970 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 ** sqlite3_mutex
45980 5f 6c 65 61 76 65 28 29 20 69 73 20 61 20 4e 55 _leave() is a NU
45990 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e LL pointer, then
459a0 20 61 6c 6c 20 74 68 72 65 65 20 72 6f 75 74 69 all three routi
459b0 6e 65 73 0a 2a 2a 20 62 65 68 61 76 65 20 61 73 nes.** behave as
459c0 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 53 no-ops..**.** S
459d0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
459e0 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 3_mutex_held()]
459f0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 and [sqlite3_mut
45a00 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a ex_notheld()]..*
45a10 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 /.sqlite3_mutex
45a20 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 *sqlite3_mutex_a
45a30 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 lloc(int);.void
45a40 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 sqlite3_mutex_fr
45a50 65 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 ee(sqlite3_mutex
45a60 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 *);.void sqlite3
45a70 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 73 71 6c _mutex_enter(sql
45a80 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e ite3_mutex*);.in
45a90 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f t sqlite3_mutex_
45aa0 74 72 79 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 try(sqlite3_mute
45ab0 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 x*);.void sqlite
45ac0 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 73 71 3_mutex_leave(sq
45ad0 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a lite3_mutex*);..
45ae0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
45af0 4d 75 74 65 78 20 4d 65 74 68 6f 64 73 20 4f 62 Mutex Methods Ob
45b00 6a 65 63 74 20 7b 48 31 37 31 32 30 7d 20 3c 53 ject {H17120} <S
45b10 32 30 31 33 30 3e 0a 2a 2a 20 45 58 50 45 52 49 20130>.** EXPERI
45b20 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20 MENTAL.**.** An
45b30 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 instance of this
45b40 20 73 74 72 75 63 74 75 72 65 20 64 65 66 69 6e structure defin
45b50 65 73 20 74 68 65 20 6c 6f 77 2d 6c 65 76 65 6c es the low-level
45b60 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73 65 routines.** use
45b70 64 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 6e d to allocate an
45b80 64 20 75 73 65 20 6d 75 74 65 78 65 73 2e 0a 2a d use mutexes..*
45b90 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 74 68 *.** Usually, th
45ba0 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 e default mutex
45bb0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
45bc0 70 72 6f 76 69 64 65 64 20 62 79 20 53 51 4c 69 provided by SQLi
45bd0 74 65 20 61 72 65 0a 2a 2a 20 73 75 66 66 69 63 te are.** suffic
45be0 69 65 6e 74 2c 20 68 6f 77 65 76 65 72 20 74 68 ient, however th
45bf0 65 20 75 73 65 72 20 68 61 73 20 74 68 65 20 6f e user has the o
45c00 70 74 69 6f 6e 20 6f 66 20 73 75 62 73 74 69 74 ption of substit
45c10 75 74 69 6e 67 20 61 20 63 75 73 74 6f 6d 0a 2a uting a custom.*
45c20 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
45c30 20 66 6f 72 20 73 70 65 63 69 61 6c 69 7a 65 64 for specialized
45c40 20 64 65 70 6c 6f 79 6d 65 6e 74 73 20 6f 72 20 deployments or
45c50 73 79 73 74 65 6d 73 20 66 6f 72 20 77 68 69 63 systems for whic
45c60 68 20 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 h SQLite.** does
45c70 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 20 73 not provide a s
45c80 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e uitable implemen
45c90 74 61 74 69 6f 6e 2e 20 49 6e 20 74 68 69 73 20 tation. In this
45ca0 63 61 73 65 2c 20 74 68 65 20 75 73 65 72 0a 2a case, the user.*
45cb0 2a 20 63 72 65 61 74 65 73 20 61 6e 64 20 70 6f * creates and po
45cc0 70 75 6c 61 74 65 73 20 61 6e 20 69 6e 73 74 61 pulates an insta
45cd0 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 nce of this stru
45ce0 63 74 75 72 65 20 74 6f 20 70 61 73 73 0a 2a 2a cture to pass.**
45cf0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 to sqlite3_conf
45d00 69 67 28 29 20 61 6c 6f 6e 67 20 77 69 74 68 20 ig() along with
45d10 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 the [SQLITE_CONF
45d20 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e IG_MUTEX] option
45d30 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 6c ..** Additionall
45d40 79 2c 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f y, an instance o
45d50 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 f this structure
45d60 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 can be used as
45d70 61 6e 0a 2a 2a 20 6f 75 74 70 75 74 20 76 61 72 an.** output var
45d80 69 61 62 6c 65 20 77 68 65 6e 20 71 75 65 72 79 iable when query
45d90 69 6e 67 20 74 68 65 20 73 79 73 74 65 6d 20 66 ing the system f
45da0 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 6d or the current m
45db0 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e utex.** implemen
45dc0 74 61 74 69 6f 6e 2c 20 75 73 69 6e 67 20 74 68 tation, using th
45dd0 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 e [SQLITE_CONFIG
45de0 5f 47 45 54 4d 55 54 45 58 5d 20 6f 70 74 69 6f _GETMUTEX] optio
45df0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 n..**.** The xMu
45e00 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 64 texInit method d
45e10 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 efined by this s
45e20 74 72 75 63 74 75 72 65 20 69 73 20 69 6e 76 6f tructure is invo
45e30 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f ked as.** part o
45e40 66 20 73 79 73 74 65 6d 20 69 6e 69 74 69 61 6c f system initial
45e50 69 7a 61 74 69 6f 6e 20 62 79 20 74 68 65 20 73 ization by the s
45e60 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
45e70 65 28 29 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a e() function..**
45e80 20 7b 48 31 37 30 30 31 7d 20 54 68 65 20 78 4d {H17001} The xM
45e90 75 74 65 78 49 6e 69 74 20 72 6f 75 74 69 6e 65 utexInit routine
45ea0 20 73 68 61 6c 6c 20 62 65 20 63 61 6c 6c 65 64 shall be called
45eb0 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 63 65 20 by SQLite once
45ec0 66 6f 72 20 65 61 63 68 0a 2a 2a 20 65 66 66 65 for each.** effe
45ed0 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 5b 73 ctive call to [s
45ee0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
45ef0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 e()]..**.** The
45f00 78 4d 75 74 65 78 45 6e 64 20 6d 65 74 68 6f 64 xMutexEnd method
45f10 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 defined by this
45f20 20 73 74 72 75 63 74 75 72 65 20 69 73 20 69 6e structure is in
45f30 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 voked as.** part
45f40 20 6f 66 20 73 79 73 74 65 6d 20 73 68 75 74 64 of system shutd
45f50 6f 77 6e 20 62 79 20 74 68 65 20 73 71 6c 69 74 own by the sqlit
45f60 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 66 75 e3_shutdown() fu
45f70 6e 63 74 69 6f 6e 2e 20 54 68 65 0a 2a 2a 20 69 nction. The.** i
45f80 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
45f90 20 74 68 69 73 20 6d 65 74 68 6f 64 20 69 73 20 this method is
45fa0 65 78 70 65 63 74 65 64 20 74 6f 20 72 65 6c 65 expected to rele
45fb0 61 73 65 20 61 6c 6c 20 6f 75 74 73 74 61 6e 64 ase all outstand
45fc0 69 6e 67 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 ing.** resources
45fd0 20 6f 62 74 61 69 6e 65 64 20 62 79 20 74 68 65 obtained by the
45fe0 20 6d 75 74 65 78 20 6d 65 74 68 6f 64 73 20 69 mutex methods i
45ff0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 65 mplementation, e
46000 73 70 65 63 69 61 6c 6c 79 0a 2a 2a 20 74 68 6f specially.** tho
46010 73 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 74 se obtained by t
46020 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 he xMutexInit me
46030 74 68 6f 64 2e 20 7b 48 31 37 30 30 33 7d 20 54 thod. {H17003} T
46040 68 65 20 78 4d 75 74 65 78 45 6e 64 28 29 0a 2a he xMutexEnd().*
46050 2a 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c * interface shal
46060 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 l be invoked onc
46070 65 20 66 6f 72 20 65 61 63 68 20 63 61 6c 6c 20 e for each call
46080 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 to [sqlite3_shut
46090 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 down()]..**.** T
460a0 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 73 65 76 he remaining sev
460b0 65 6e 20 6d 65 74 68 6f 64 73 20 64 65 66 69 6e en methods defin
460c0 65 64 20 62 79 20 74 68 69 73 20 73 74 72 75 63 ed by this struc
460d0 74 75 72 65 20 28 78 4d 75 74 65 78 41 6c 6c 6f ture (xMutexAllo
460e0 63 2c 0a 2a 2a 20 78 4d 75 74 65 78 46 72 65 65 c,.** xMutexFree
460f0 2c 20 78 4d 75 74 65 78 45 6e 74 65 72 2c 20 78 , xMutexEnter, x
46100 4d 75 74 65 78 54 72 79 2c 20 78 4d 75 74 65 78 MutexTry, xMutex
46110 4c 65 61 76 65 2c 20 78 4d 75 74 65 78 48 65 6c Leave, xMutexHel
46120 64 20 61 6e 64 0a 2a 2a 20 78 4d 75 74 65 78 4e d and.** xMutexN
46130 6f 74 68 65 6c 64 29 20 69 6d 70 6c 65 6d 65 6e otheld) implemen
46140 74 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 t the following
46150 69 6e 74 65 72 66 61 63 65 73 20 28 72 65 73 70 interfaces (resp
46160 65 63 74 69 76 65 6c 79 29 3a 0a 2a 2a 0a 2a 2a ectively):.**.**
46170 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 <ul>.** <li>
46180 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
46190 61 6c 6c 6f 63 28 29 5d 20 3c 2f 6c 69 3e 0a 2a alloc()] </li>.*
461a0 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 * <li> [sqlit
461b0 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 5d e3_mutex_free()]
461c0 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e </li>.** <li>
461d0 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 [sqlite3_mutex
461e0 5f 65 6e 74 65 72 28 29 5d 20 3c 2f 6c 69 3e 0a _enter()] </li>.
461f0 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 ** <li> [sqli
46200 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 5d te3_mutex_try()]
46210 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e </li>.** <li>
46220 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 [sqlite3_mutex
46230 5f 6c 65 61 76 65 28 29 5d 20 3c 2f 6c 69 3e 0a _leave()] </li>.
46240 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 ** <li> [sqli
46250 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 te3_mutex_held()
46260 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 ] </li>.** <li
46270 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 > [sqlite3_mute
46280 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 20 3c 2f 6c x_notheld()] </l
46290 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a i>.** </ul>.**.*
462a0 2a 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 * The only diffe
462b0 72 65 6e 63 65 20 69 73 20 74 68 61 74 20 74 68 rence is that th
462c0 65 20 70 75 62 6c 69 63 20 73 71 6c 69 74 65 33 e public sqlite3
462d0 5f 58 58 58 20 66 75 6e 63 74 69 6f 6e 73 20 65 _XXX functions e
462e0 6e 75 6d 65 72 61 74 65 64 0a 2a 2a 20 61 62 6f numerated.** abo
462f0 76 65 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f ve silently igno
46300 72 65 20 61 6e 79 20 69 6e 76 6f 63 61 74 69 6f re any invocatio
46310 6e 73 20 74 68 61 74 20 70 61 73 73 20 61 20 4e ns that pass a N
46320 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 ULL pointer inst
46330 65 61 64 0a 2a 2a 20 6f 66 20 61 20 76 61 6c 69 ead.** of a vali
46340 64 20 6d 75 74 65 78 20 68 61 6e 64 6c 65 2e 20 d mutex handle.
46350 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 The implementati
46360 6f 6e 73 20 6f 66 20 74 68 65 20 6d 65 74 68 6f ons of the metho
46370 64 73 20 64 65 66 69 6e 65 64 0a 2a 2a 20 62 79 ds defined.** by
46380 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 this structure
46390 61 72 65 20 6e 6f 74 20 72 65 71 75 69 72 65 64 are not required
463a0 20 74 6f 20 68 61 6e 64 6c 65 20 74 68 69 73 20 to handle this
463b0 63 61 73 65 2c 20 74 68 65 20 72 65 73 75 6c 74 case, the result
463c0 73 0a 2a 2a 20 6f 66 20 70 61 73 73 69 6e 67 20 s.** of passing
463d0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 a NULL pointer i
463e0 6e 73 74 65 61 64 20 6f 66 20 61 20 76 61 6c 69 nstead of a vali
463f0 64 20 6d 75 74 65 78 20 68 61 6e 64 6c 65 20 61 d mutex handle a
46400 72 65 20 75 6e 64 65 66 69 6e 65 64 0a 2a 2a 20 re undefined.**
46410 28 69 2e 65 2e 20 69 74 20 69 73 20 61 63 63 65 (i.e. it is acce
46420 70 74 61 62 6c 65 20 74 6f 20 70 72 6f 76 69 64 ptable to provid
46430 65 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e an implementat
46440 69 6f 6e 20 74 68 61 74 20 73 65 67 66 61 75 6c ion that segfaul
46450 74 73 20 69 66 0a 2a 2a 20 69 74 20 69 73 20 70 ts if.** it is p
46460 61 73 73 65 64 20 61 20 4e 55 4c 4c 20 70 6f 69 assed a NULL poi
46470 6e 74 65 72 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 nter)..*/.typede
46480 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
46490 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 20 73 _mutex_methods s
464a0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
464b0 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c hods;.struct sql
464c0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
464d0 64 73 20 7b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 ds {. int (*xMu
464e0 74 65 78 49 6e 69 74 29 28 76 6f 69 64 29 3b 0a texInit)(void);.
464f0 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 45 6e int (*xMutexEn
46500 64 29 28 76 6f 69 64 29 3b 0a 20 20 73 71 6c 69 d)(void);. sqli
46510 74 65 33 5f 6d 75 74 65 78 20 2a 28 2a 78 4d 75 te3_mutex *(*xMu
46520 74 65 78 41 6c 6c 6f 63 29 28 69 6e 74 29 3b 0a texAlloc)(int);.
46530 20 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 46 void (*xMutexF
46540 72 65 65 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 ree)(sqlite3_mut
46550 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a ex *);. void (*
46560 78 4d 75 74 65 78 45 6e 74 65 72 29 28 73 71 6c xMutexEnter)(sql
46570 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 ite3_mutex *);.
46580 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 54 72 79 int (*xMutexTry
46590 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 )(sqlite3_mutex
465a0 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 *);. void (*xMu
465b0 74 65 78 4c 65 61 76 65 29 28 73 71 6c 69 74 65 texLeave)(sqlite
465c0 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69 6e 3_mutex *);. in
465d0 74 20 28 2a 78 4d 75 74 65 78 48 65 6c 64 29 28 t (*xMutexHeld)(
465e0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 sqlite3_mutex *)
465f0 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 ;. int (*xMutex
46600 4e 6f 74 68 65 6c 64 29 28 73 71 6c 69 74 65 33 Notheld)(sqlite3
46610 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d 3b 0a 0a 2f _mutex *);.};../
46620 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
46630 75 74 65 78 20 56 65 72 69 66 69 63 61 74 69 6f utex Verificatio
46640 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48 31 37 30 n Routines {H170
46650 38 30 7d 20 3c 53 32 30 31 33 30 3e 20 3c 53 33 80} <S20130> <S3
46660 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 0800>.**.** The
46670 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 sqlite3_mutex_he
46680 6c 64 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 ld() and sqlite3
46690 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 _mutex_notheld()
466a0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 routines.** are
466b0 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 intended for us
466c0 65 20 69 6e 73 69 64 65 20 61 73 73 65 72 74 28 e inside assert(
466d0 29 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 7b 48 ) statements. {H
466e0 31 37 30 38 31 7d 20 54 68 65 20 53 51 4c 69 74 17081} The SQLit
466f0 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65 72 20 e core.** never
46700 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 69 uses these routi
46710 6e 65 73 20 65 78 63 65 70 74 20 69 6e 73 69 64 nes except insid
46720 65 20 61 6e 20 61 73 73 65 72 74 28 29 20 61 6e e an assert() an
46730 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a d applications.*
46740 2a 20 61 72 65 20 61 64 76 69 73 65 64 20 74 6f * are advised to
46750 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65 61 64 follow the lead
46760 20 6f 66 20 74 68 65 20 63 6f 72 65 2e 20 20 7b of the core. {
46770 48 31 37 30 38 32 7d 20 54 68 65 20 63 6f 72 65 H17082} The core
46780 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69 64 65 only.** provide
46790 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e s implementation
467a0 73 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 s for these rout
467b0 69 6e 65 73 20 77 68 65 6e 20 69 74 20 69 73 20 ines when it is
467c0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 compiled.** with
467d0 20 74 68 65 20 53 51 4c 49 54 45 5f 44 45 42 55 the SQLITE_DEBU
467e0 47 20 66 6c 61 67 2e 20 20 7b 41 31 37 30 38 37 G flag. {A17087
467f0 7d 20 45 78 74 65 72 6e 61 6c 20 6d 75 74 65 78 } External mutex
46800 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
46810 0a 2a 2a 20 61 72 65 20 6f 6e 6c 79 20 72 65 71 .** are only req
46820 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65 uired to provide
46830 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
46840 69 66 20 53 51 4c 49 54 45 5f 44 45 42 55 47 20 if SQLITE_DEBUG
46850 69 73 0a 2a 2a 20 64 65 66 69 6e 65 64 20 61 6e is.** defined an
46860 64 20 69 66 20 4e 44 45 42 55 47 20 69 73 20 6e d if NDEBUG is n
46870 6f 74 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a ot defined..**.*
46880 2a 20 7b 48 31 37 30 38 33 7d 20 54 68 65 73 65 * {H17083} These
46890 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 routines should
468a0 20 72 65 74 75 72 6e 20 74 72 75 65 20 69 66 20 return true if
468b0 74 68 65 20 6d 75 74 65 78 20 69 6e 20 74 68 65 the mutex in the
468c0 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 ir argument.** i
468d0 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20 68 65 s held or not he
468e0 6c 64 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 ld, respectively
468f0 2c 20 62 79 20 74 68 65 20 63 61 6c 6c 69 6e 67 , by the calling
46900 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 7b thread..**.** {
46910 58 31 37 30 38 34 7d 20 54 68 65 20 69 6d 70 6c X17084} The impl
46920 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 6f ementation is no
46930 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 70 72 t required to pr
46940 6f 76 69 64 65 64 20 76 65 72 73 69 6f 6e 73 20 ovided versions
46950 6f 66 20 74 68 65 73 65 0a 2a 2a 20 72 6f 75 74 of these.** rout
46960 69 6e 65 73 20 74 68 61 74 20 61 63 74 75 61 6c ines that actual
46970 6c 79 20 77 6f 72 6b 2e 20 49 66 20 74 68 65 20 ly work. If the
46980 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 implementation d
46990 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 oes not provide
469a0 77 6f 72 6b 69 6e 67 0a 2a 2a 20 76 65 72 73 69 working.** versi
469b0 6f 6e 73 20 6f 66 20 74 68 65 73 65 20 72 6f 75 ons of these rou
469c0 74 69 6e 65 73 2c 20 69 74 20 73 68 6f 75 6c 64 tines, it should
469d0 20 61 74 20 6c 65 61 73 74 20 70 72 6f 76 69 64 at least provid
469e0 65 20 73 74 75 62 73 20 74 68 61 74 20 61 6c 77 e stubs that alw
469f0 61 79 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74 72 ays.** return tr
46a00 75 65 20 73 6f 20 74 68 61 74 20 6f 6e 65 20 64 ue so that one d
46a10 6f 65 73 20 6e 6f 74 20 67 65 74 20 73 70 75 72 oes not get spur
46a20 69 6f 75 73 20 61 73 73 65 72 74 69 6f 6e 20 66 ious assertion f
46a30 61 69 6c 75 72 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b ailures..**.** {
46a40 48 31 37 30 38 35 7d 20 49 66 20 74 68 65 20 61 H17085} If the a
46a50 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
46a60 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 e3_mutex_held()
46a70 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
46a80 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 6f r then.** the ro
46a90 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 72 65 74 utine should ret
46aa0 75 72 6e 20 31 2e 20 20 7b 45 4e 44 7d 20 54 68 urn 1. {END} Th
46ab0 69 73 20 73 65 65 6d 73 20 63 6f 75 6e 74 65 72 is seems counter
46ac0 2d 69 6e 74 75 69 74 69 76 65 20 73 69 6e 63 65 -intuitive since
46ad0 0a 2a 2a 20 63 6c 65 61 72 6c 79 20 74 68 65 20 .** clearly the
46ae0 6d 75 74 65 78 20 63 61 6e 6e 6f 74 20 62 65 20 mutex cannot be
46af0 68 65 6c 64 20 69 66 20 69 74 20 64 6f 65 73 20 held if it does
46b00 6e 6f 74 20 65 78 69 73 74 2e 20 20 42 75 74 20 not exist. But
46b10 74 68 65 0a 2a 2a 20 74 68 65 20 72 65 61 73 6f the.** the reaso
46b20 6e 20 74 68 65 20 6d 75 74 65 78 20 64 6f 65 73 n the mutex does
46b30 20 6e 6f 74 20 65 78 69 73 74 20 69 73 20 62 65 not exist is be
46b40 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 64 20 cause the build
46b50 69 73 20 6e 6f 74 0a 2a 2a 20 75 73 69 6e 67 20 is not.** using
46b60 6d 75 74 65 78 65 73 2e 20 20 41 6e 64 20 77 65 mutexes. And we
46b70 20 64 6f 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 do not want the
46b80 20 61 73 73 65 72 74 28 29 20 63 6f 6e 74 61 69 assert() contai
46b90 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 61 6c 6c ning the.** call
46ba0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 to sqlite3_mute
46bb0 78 5f 68 65 6c 64 28 29 20 74 6f 20 66 61 69 6c x_held() to fail
46bc0 2c 20 73 6f 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 , so a non-zero
46bd0 72 65 74 75 72 6e 20 69 73 0a 2a 2a 20 74 68 65 return is.** the
46be0 20 61 70 70 72 6f 70 72 69 61 74 65 20 74 68 69 appropriate thi
46bf0 6e 67 20 74 6f 20 64 6f 2e 20 20 7b 48 31 37 30 ng to do. {H170
46c00 38 36 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 86} The sqlite3_
46c10 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 0a mutex_notheld().
46c20 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f ** interface sho
46c30 75 6c 64 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 uld also return
46c40 31 20 77 68 65 6e 20 67 69 76 65 6e 20 61 20 4e 1 when given a N
46c50 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a ULL pointer..*/.
46c60 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 int sqlite3_mute
46c70 78 5f 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d x_held(sqlite3_m
46c80 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 utex*);.int sqli
46c90 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c te3_mutex_nothel
46ca0 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a d(sqlite3_mutex*
46cb0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
46cc0 45 46 3a 20 4d 75 74 65 78 20 54 79 70 65 73 20 EF: Mutex Types
46cd0 7b 48 31 37 30 30 31 7d 20 3c 48 31 37 30 30 30 {H17001} <H17000
46ce0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c >.**.** The [sql
46cf0 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 ite3_mutex_alloc
46d00 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 61 ()] interface ta
46d10 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 kes a single arg
46d20 75 6d 65 6e 74 0a 2a 2a 20 77 68 69 63 68 20 69 ument.** which i
46d30 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 s one of these i
46d40 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 nteger constants
46d50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 74 20 ..**.** The set
46d60 6f 66 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 of static mutexe
46d70 73 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f s may change fro
46d80 6d 20 6f 6e 65 20 53 51 4c 69 74 65 20 72 65 6c m one SQLite rel
46d90 65 61 73 65 20 74 6f 20 74 68 65 0a 2a 2a 20 6e ease to the.** n
46da0 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f ext. Applicatio
46db0 6e 73 20 74 68 61 74 20 6f 76 65 72 72 69 64 65 ns that override
46dc0 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 75 the built-in mu
46dd0 74 65 78 20 6c 6f 67 69 63 20 6d 75 73 74 20 62 tex logic must b
46de0 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 74 6f e.** prepared to
46df0 20 61 63 63 6f 6d 6d 6f 64 61 74 65 20 61 64 64 accommodate add
46e00 69 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d itional static m
46e10 75 74 65 78 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 utexes..*/.#defi
46e20 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f ne SQLITE_MUTEX_
46e30 46 41 53 54 20 20 20 20 20 20 20 20 20 20 20 20 FAST
46e40 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 0.#define SQLIT
46e50 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 E_MUTEX_RECURSIV
46e60 45 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 E 1.#defi
46e70 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f ne SQLITE_MUTEX_
46e80 53 54 41 54 49 43 5f 4d 41 53 54 45 52 20 20 20 STATIC_MASTER
46e90 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
46ea0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d E_MUTEX_STATIC_M
46eb0 45 4d 20 20 20 20 20 20 20 33 20 20 2f 2a 20 73 EM 3 /* s
46ec0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
46ed0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
46ee0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d E_MUTEX_STATIC_M
46ef0 45 4d 32 20 20 20 20 20 20 34 20 20 2f 2a 20 73 EM2 4 /* s
46f00 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d qlite3_release_m
46f10 65 6d 6f 72 79 28 29 20 2a 2f 0a 23 64 65 66 69 emory() */.#defi
46f20 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f ne SQLITE_MUTEX_
46f30 53 54 41 54 49 43 5f 50 52 4e 47 20 20 20 20 20 STATIC_PRNG
46f40 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 72 5 /* sqlite3_r
46f50 61 6e 64 6f 6d 28 29 20 2a 2f 0a 23 64 65 66 69 andom() */.#defi
46f60 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f ne SQLITE_MUTEX_
46f70 53 54 41 54 49 43 5f 4c 52 55 20 20 20 20 20 20 STATIC_LRU
46f80 20 36 20 20 2f 2a 20 6c 72 75 20 70 61 67 65 20 6 /* lru page
46f90 6c 69 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 list */.#define
46fa0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 SQLITE_MUTEX_STA
46fb0 54 49 43 5f 4c 52 55 32 20 20 20 20 20 20 37 20 TIC_LRU2 7
46fc0 20 2f 2a 20 6c 72 75 20 70 61 67 65 20 6c 69 73 /* lru page lis
46fd0 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t */../*.** CAPI
46fe0 33 52 45 46 3a 20 4c 6f 77 2d 4c 65 76 65 6c 20 3REF: Low-Level
46ff0 43 6f 6e 74 72 6f 6c 20 4f 66 20 44 61 74 61 62 Control Of Datab
47000 61 73 65 20 46 69 6c 65 73 20 7b 48 31 31 33 30 ase Files {H1130
47010 30 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 0} <S30800>.**.*
47020 2a 20 7b 48 31 31 33 30 31 7d 20 54 68 65 20 5b * {H11301} The [
47030 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e sqlite3_file_con
47040 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 trol()] interfac
47050 65 20 6d 61 6b 65 73 20 61 20 64 69 72 65 63 74 e makes a direct
47060 20 63 61 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 call to the.**
47070 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 xFileControl met
47080 68 6f 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c hod for the [sql
47090 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
470a0 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 object associat
470b0 65 64 0a 2a 2a 20 77 69 74 68 20 61 20 70 61 72 ed.** with a par
470c0 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 ticular database
470d0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 identified by t
470e0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
470f0 6e 74 2e 20 7b 48 31 31 33 30 32 7d 20 54 68 65 nt. {H11302} The
47100 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 .** name of the
47110 64 61 74 61 62 61 73 65 20 69 73 20 74 68 65 20 database is the
47120 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f name assigned to
47130 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 79 the database by
47140 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d the.** <a href=
47150 22 6c 61 6e 67 5f 61 74 74 61 63 68 2e 68 74 6d "lang_attach.htm
47160 6c 22 3e 41 54 54 41 43 48 3c 2f 61 3e 20 53 51 l">ATTACH</a> SQ
47170 4c 20 63 6f 6d 6d 61 6e 64 20 74 68 61 74 20 6f L command that o
47180 70 65 6e 65 64 20 74 68 65 0a 2a 2a 20 64 61 74 pened the.** dat
47190 61 62 61 73 65 2e 20 7b 48 31 31 33 30 33 7d 20 abase. {H11303}
471a0 54 6f 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 6d To control the m
471b0 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c ain database fil
471c0 65 2c 20 75 73 65 20 74 68 65 20 6e 61 6d 65 20 e, use the name
471d0 22 6d 61 69 6e 22 0a 2a 2a 20 6f 72 20 61 20 4e "main".** or a N
471e0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 7b 48 31 ULL pointer. {H1
471f0 31 33 30 34 7d 20 54 68 65 20 74 68 69 72 64 20 1304} The third
47200 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d and fourth param
47210 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 72 6f eters to this ro
47220 75 74 69 6e 65 0a 2a 2a 20 61 72 65 20 70 61 73 utine.** are pas
47230 73 65 64 20 64 69 72 65 63 74 6c 79 20 74 68 72 sed directly thr
47240 6f 75 67 68 20 74 6f 20 74 68 65 20 73 65 63 6f ough to the seco
47250 6e 64 20 61 6e 64 20 74 68 69 72 64 20 70 61 72 nd and third par
47260 61 6d 65 74 65 72 73 20 6f 66 0a 2a 2a 20 74 68 ameters of.** th
47270 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d e xFileControl m
47280 65 74 68 6f 64 2e 20 20 7b 48 31 31 33 30 35 7d ethod. {H11305}
47290 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 The return valu
472a0 65 20 6f 66 20 74 68 65 20 78 46 69 6c 65 43 6f e of the xFileCo
472b0 6e 74 72 6f 6c 0a 2a 2a 20 6d 65 74 68 6f 64 20 ntrol.** method
472c0 62 65 63 6f 6d 65 73 20 74 68 65 20 72 65 74 75 becomes the retu
472d0 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 rn value of this
472e0 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 routine..**.**
472f0 7b 48 31 31 33 30 36 7d 20 49 66 20 74 68 65 20 {H11306} If the
47300 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
47310 20 28 7a 44 62 4e 61 6d 65 29 20 64 6f 65 73 20 (zDbName) does
47320 6e 6f 74 20 6d 61 74 63 68 20 74 68 65 20 6e 61 not match the na
47330 6d 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 70 65 me of any.** ope
47340 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c n database file,
47350 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 45 52 52 then SQLITE_ERR
47360 4f 52 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 OR is returned.
47370 7b 48 31 31 33 30 37 7d 20 54 68 69 73 20 65 72 {H11307} This er
47380 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 6e ror.** code is n
47390 6f 74 20 72 65 6d 65 6d 62 65 72 65 64 20 61 6e ot remembered an
473a0 64 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 72 65 d will not be re
473b0 63 61 6c 6c 65 64 20 62 79 20 5b 73 71 6c 69 74 called by [sqlit
473c0 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 0a 2a 2a e3_errcode()].**
473d0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 or [sqlite3_err
473e0 6d 73 67 28 29 5d 2e 20 7b 41 31 31 33 30 38 7d msg()]. {A11308}
473f0 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 The underlying
47400 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 xFileControl met
47410 68 6f 64 20 6d 69 67 68 74 0a 2a 2a 20 61 6c 73 hod might.** als
47420 6f 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f o return SQLITE_
47430 45 52 52 4f 52 2e 20 20 7b 41 31 31 33 30 39 7d ERROR. {A11309}
47440 20 54 68 65 72 65 20 69 73 20 6e 6f 20 77 61 79 There is no way
47450 20 74 6f 20 64 69 73 74 69 6e 67 75 69 73 68 20 to distinguish
47460 62 65 74 77 65 65 6e 0a 2a 2a 20 61 6e 20 69 6e between.** an in
47470 63 6f 72 72 65 63 74 20 7a 44 62 4e 61 6d 65 20 correct zDbName
47480 61 6e 64 20 61 6e 20 53 51 4c 49 54 45 5f 45 52 and an SQLITE_ER
47490 52 4f 52 20 72 65 74 75 72 6e 20 66 72 6f 6d 20 ROR return from
474a0 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a the underlying.*
474b0 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d * xFileControl m
474c0 65 74 68 6f 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a ethod. {END}.**.
474d0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 ** See also: [SQ
474e0 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 LITE_FCNTL_LOCKS
474f0 54 41 54 45 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c TATE].*/.int sql
47500 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
47510 6c 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 l(sqlite3*, cons
47520 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c t char *zDbName,
47530 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 2a 29 3b int op, void*);
47540 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
47550 3a 20 54 65 73 74 69 6e 67 20 49 6e 74 65 72 66 : Testing Interf
47560 61 63 65 20 7b 48 31 31 34 30 30 7d 20 3c 53 33 ace {H11400} <S3
47570 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 0800>.**.** The
47580 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e sqlite3_test_con
47590 74 72 6f 6c 28 29 20 69 6e 74 65 72 66 61 63 65 trol() interface
475a0 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 61 64 is used to read
475b0 20 6f 75 74 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a out internal.**
475c0 20 73 74 61 74 65 20 6f 66 20 53 51 4c 69 74 65 state of SQLite
475d0 20 61 6e 64 20 74 6f 20 69 6e 6a 65 63 74 20 66 and to inject f
475e0 61 75 6c 74 73 20 69 6e 74 6f 20 53 51 4c 69 74 aults into SQLit
475f0 65 20 66 6f 72 20 74 65 73 74 69 6e 67 0a 2a 2a e for testing.**
47600 20 70 75 72 70 6f 73 65 73 2e 20 20 54 68 65 20 purposes. The
47610 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
47620 69 73 20 61 6e 20 6f 70 65 72 61 74 69 6f 6e 20 is an operation
47630 63 6f 64 65 20 74 68 61 74 20 64 65 74 65 72 6d code that determ
47640 69 6e 65 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 ines.** the numb
47650 65 72 2c 20 6d 65 61 6e 69 6e 67 2c 20 61 6e 64 er, meaning, and
47660 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 61 6c operation of al
47670 6c 20 73 75 62 73 65 71 75 65 6e 74 20 70 61 72 l subsequent par
47680 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 ameters..**.** T
47690 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 his interface is
476a0 20 6e 6f 74 20 66 6f 72 20 75 73 65 20 62 79 20 not for use by
476b0 61 70 70 6c 69 63 61 74 69 6f 6e 73 2e 20 20 49 applications. I
476c0 74 20 65 78 69 73 74 73 20 73 6f 6c 65 6c 79 0a t exists solely.
476d0 2a 2a 20 66 6f 72 20 76 65 72 69 66 79 69 6e 67 ** for verifying
476e0 20 74 68 65 20 63 6f 72 72 65 63 74 20 6f 70 65 the correct ope
476f0 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 ration of the SQ
47700 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 44 Lite library. D
47710 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 68 epending.** on h
47720 6f 77 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 ow the SQLite li
47730 62 72 61 72 79 20 69 73 20 63 6f 6d 70 69 6c 65 brary is compile
47740 64 2c 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 d, this interfac
47750 65 20 6d 69 67 68 74 20 6e 6f 74 20 65 78 69 73 e might not exis
47760 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 t..**.** The det
47770 61 69 6c 73 20 6f 66 20 74 68 65 20 6f 70 65 72 ails of the oper
47780 61 74 69 6f 6e 20 63 6f 64 65 73 2c 20 74 68 65 ation codes, the
47790 69 72 20 6d 65 61 6e 69 6e 67 73 2c 20 74 68 65 ir meanings, the
477a0 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 parameters.** t
477b0 68 65 79 20 74 61 6b 65 2c 20 61 6e 64 20 77 68 hey take, and wh
477c0 61 74 20 74 68 65 79 20 64 6f 20 61 72 65 20 61 at they do are a
477d0 6c 6c 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 ll subject to ch
477e0 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 ange without not
477f0 69 63 65 2e 0a 2a 2a 20 55 6e 6c 69 6b 65 20 6d ice..** Unlike m
47800 6f 73 74 20 6f 66 20 74 68 65 20 53 51 4c 69 74 ost of the SQLit
47810 65 20 41 50 49 2c 20 74 68 69 73 20 66 75 6e 63 e API, this func
47820 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 75 61 72 tion is not guar
47830 61 6e 74 65 65 64 20 74 6f 0a 2a 2a 20 6f 70 65 anteed to.** ope
47840 72 61 74 65 20 63 6f 6e 73 69 73 74 65 6e 74 6c rate consistentl
47850 79 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 y from one relea
47860 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a se to the next..
47870 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 */.int sqlite3_t
47880 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 69 6e 74 20 est_control(int
47890 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a op, ...);../*.**
478a0 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 69 CAPI3REF: Testi
478b0 6e 67 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 ng Interface Ope
478c0 72 61 74 69 6f 6e 20 43 6f 64 65 73 20 7b 48 31 ration Codes {H1
478d0 31 34 31 30 7d 20 3c 48 31 31 34 30 30 3e 0a 2a 1410} <H11400>.*
478e0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 *.** These const
478f0 61 6e 74 73 20 61 72 65 20 74 68 65 20 76 61 6c ants are the val
47900 69 64 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 id operation cod
47910 65 20 70 61 72 61 6d 65 74 65 72 73 20 75 73 65 e parameters use
47920 64 0a 2a 2a 20 61 73 20 74 68 65 20 66 69 72 73 d.** as the firs
47930 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 t argument to [s
47940 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 qlite3_test_cont
47950 72 6f 6c 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 rol()]..**.** Th
47960 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 ese parameters a
47970 6e 64 20 74 68 65 69 72 20 6d 65 61 6e 69 6e 67 nd their meaning
47980 73 20 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f s are subject to
47990 20 63 68 61 6e 67 65 0a 2a 2a 20 77 69 74 68 6f change.** witho
479a0 75 74 20 6e 6f 74 69 63 65 2e 20 20 54 68 65 73 ut notice. Thes
479b0 65 20 76 61 6c 75 65 73 20 61 72 65 20 66 6f 72 e values are for
479c0 20 74 65 73 74 69 6e 67 20 70 75 72 70 6f 73 65 testing purpose
479d0 73 20 6f 6e 6c 79 2e 0a 2a 2a 20 41 70 70 6c 69 s only..** Appli
479e0 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e cations should n
479f0 6f 74 20 75 73 65 20 61 6e 79 20 6f 66 20 74 68 ot use any of th
47a00 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f ese parameters o
47a10 72 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 r the.** [sqlite
47a20 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 3_test_control()
47a30 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a ] interface..*/.
47a40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
47a50 45 53 54 43 54 52 4c 5f 50 52 4e 47 5f 53 41 56 ESTCTRL_PRNG_SAV
47a60 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 E
47a70 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 5.#define SQLIT
47a80 45 5f 54 45 53 54 43 54 52 4c 5f 50 52 4e 47 5f E_TESTCTRL_PRNG_
47a90 52 45 53 54 4f 52 45 20 20 20 20 20 20 20 20 20 RESTORE
47aa0 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 6.#define SQ
47ab0 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 50 52 LITE_TESTCTRL_PR
47ac0 4e 47 5f 52 45 53 45 54 20 20 20 20 20 20 20 20 NG_RESET
47ad0 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 7.#define
47ae0 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c SQLITE_TESTCTRL
47af0 5f 42 49 54 56 45 43 5f 54 45 53 54 20 20 20 20 _BITVEC_TEST
47b00 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 8.#def
47b10 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 ine SQLITE_TESTC
47b20 54 52 4c 5f 46 41 55 4c 54 5f 49 4e 53 54 41 4c TRL_FAULT_INSTAL
47b30 4c 20 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 L 9.#
47b40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 define SQLITE_TE
47b50 53 54 43 54 52 4c 5f 42 45 4e 49 47 4e 5f 4d 41 STCTRL_BENIGN_MA
47b60 4c 4c 4f 43 5f 48 4f 4f 4b 53 20 20 20 20 20 31 LLOC_HOOKS 1
47b70 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 0../*.** CAPI3RE
47b80 46 3a 20 53 51 4c 69 74 65 20 52 75 6e 74 69 6d F: SQLite Runtim
47b90 65 20 53 74 61 74 75 73 20 7b 48 31 37 32 30 30 e Status {H17200
47ba0 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 45 58 } <S60200>.** EX
47bb0 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a PERIMENTAL.**.**
47bc0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 This interface
47bd0 69 73 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 is used to retri
47be0 65 76 65 20 72 75 6e 74 69 6d 65 20 73 74 61 74 eve runtime stat
47bf0 75 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a us information.*
47c00 2a 20 61 62 6f 75 74 20 74 68 65 20 70 72 65 66 * about the pref
47c10 6f 72 6d 61 6e 63 65 20 6f 66 20 53 51 4c 69 74 ormance of SQLit
47c20 65 2c 20 61 6e 64 20 6f 70 74 69 6f 6e 61 6c 6c e, and optionall
47c30 79 20 74 6f 20 72 65 73 65 74 20 76 61 72 69 6f y to reset vario
47c40 75 73 0a 2a 2a 20 68 69 67 68 77 61 74 65 72 20 us.** highwater
47c50 6d 61 72 6b 73 2e 20 20 54 68 65 20 66 69 72 73 marks. The firs
47c60 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e t argument is an
47c70 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 66 6f integer code fo
47c80 72 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 66 69 r.** the specifi
47c90 63 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 6d c parameter to m
47ca0 65 61 73 75 72 65 2e 20 20 52 65 63 6f 67 6e 69 easure. Recogni
47cb0 7a 65 64 20 69 6e 74 65 67 65 72 20 63 6f 64 65 zed integer code
47cc0 73 0a 2a 2a 20 61 72 65 20 6f 66 20 74 68 65 20 s.** are of the
47cd0 66 6f 72 6d 20 5b 53 51 4c 49 54 45 5f 53 54 41 form [SQLITE_STA
47ce0 54 55 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 20 TUS_MEMORY_USED
47cf0 7c 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f | SQLITE_STATUS_
47d00 2e 2e 2e 5d 2e 0a 2a 2a 20 54 68 65 20 63 75 72 ...]..** The cur
47d10 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 74 68 rent value of th
47d20 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 72 e parameter is r
47d30 65 74 75 72 6e 65 64 20 69 6e 74 6f 20 2a 70 43 eturned into *pC
47d40 75 72 72 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 68 urrent..** The h
47d50 69 67 68 65 73 74 20 72 65 63 6f 72 64 65 64 20 ighest recorded
47d60 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 value is returne
47d70 64 20 69 6e 20 2a 70 48 69 67 68 77 61 74 65 72 d in *pHighwater
47d80 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 72 65 73 . If the.** res
47d90 65 74 46 6c 61 67 20 69 73 20 74 72 75 65 2c 20 etFlag is true,
47da0 74 68 65 6e 20 74 68 65 20 68 69 67 68 65 73 74 then the highest
47db0 20 72 65 63 6f 72 64 20 76 61 6c 75 65 20 69 73 record value is
47dc0 20 72 65 73 65 74 20 61 66 74 65 72 0a 2a 2a 20 reset after.**
47dd0 2a 70 48 69 67 68 77 61 74 65 72 20 69 73 20 77 *pHighwater is w
47de0 72 69 74 74 65 6e 2e 20 53 6f 6d 65 20 70 61 72 ritten. Some par
47df0 61 6d 65 74 65 72 73 20 64 6f 20 6e 6f 74 20 72 ameters do not r
47e00 65 63 6f 72 64 20 74 68 65 20 68 69 67 68 65 73 ecord the highes
47e10 74 0a 2a 2a 20 76 61 6c 75 65 2e 20 20 46 6f 72 t.** value. For
47e20 20 74 68 6f 73 65 20 70 61 72 61 6d 65 74 65 72 those parameter
47e30 73 0a 2a 2a 20 6e 6f 74 68 69 6e 67 20 69 73 20 s.** nothing is
47e40 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 48 written into *pH
47e50 69 67 68 77 61 74 65 72 20 61 6e 64 20 74 68 65 ighwater and the
47e60 20 72 65 73 65 74 46 6c 61 67 20 69 73 20 69 67 resetFlag is ig
47e70 6e 6f 72 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 20 nored..** Other
47e80 70 61 72 61 6d 65 74 65 72 73 20 72 65 63 6f 72 parameters recor
47e90 64 20 6f 6e 6c 79 20 74 68 65 20 68 69 67 68 77 d only the highw
47ea0 61 74 65 72 20 6d 61 72 6b 20 61 6e 64 20 6e 6f ater mark and no
47eb0 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a t the current.**
47ec0 20 76 61 6c 75 65 2e 20 20 46 6f 72 20 74 68 65 value. For the
47ed0 73 65 20 6c 61 74 74 65 72 20 70 61 72 61 6d 65 se latter parame
47ee0 74 65 72 73 20 6e 6f 74 68 69 6e 67 20 69 73 20 ters nothing is
47ef0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 43 written into *pC
47f00 75 72 72 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 urrent..**.** Th
47f10 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 is routine retur
47f20 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 20 6f 6e 20 ns SQLITE_OK on
47f30 73 75 63 63 65 73 73 20 61 6e 64 20 61 20 6e 6f success and a no
47f40 6e 2d 7a 65 72 6f 0a 2a 2a 20 5b 65 72 72 6f 72 n-zero.** [error
47f50 20 63 6f 64 65 5d 20 6f 6e 20 66 61 69 6c 75 72 code] on failur
47f60 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f e..**.** This ro
47f70 75 74 69 6e 65 20 69 73 20 74 68 72 65 61 64 73 utine is threads
47f80 61 66 65 20 62 75 74 20 69 73 20 6e 6f 74 20 61 afe but is not a
47f90 74 6f 6d 69 63 2e 20 20 54 68 69 73 20 72 6f 75 tomic. This rou
47fa0 74 69 6e 65 20 63 61 6e 0a 2a 2a 20 63 61 6c 6c tine can.** call
47fb0 65 64 20 77 68 69 6c 65 20 6f 74 68 65 72 20 74 ed while other t
47fc0 68 72 65 61 64 73 20 61 72 65 20 72 75 6e 6e 69 hreads are runni
47fd0 6e 67 20 74 68 65 20 73 61 6d 65 20 6f 72 20 64 ng the same or d
47fe0 69 66 66 65 72 65 6e 74 20 53 51 4c 69 74 65 0a ifferent SQLite.
47ff0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 ** interfaces.
48000 48 6f 77 65 76 65 72 20 74 68 65 20 76 61 6c 75 However the valu
48010 65 73 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a es returned in *
48020 70 43 75 72 72 65 6e 74 20 61 6e 64 0a 2a 2a 20 pCurrent and.**
48030 2a 70 48 69 67 68 77 61 74 65 72 20 72 65 66 6c *pHighwater refl
48040 65 63 74 20 74 68 65 20 73 74 61 74 75 73 20 6f ect the status o
48050 66 20 53 51 4c 69 74 65 20 61 74 20 64 69 66 66 f SQLite at diff
48060 65 72 65 6e 74 20 70 6f 69 6e 74 73 20 69 6e 20 erent points in
48070 74 69 6d 65 0a 2a 2a 20 61 6e 64 20 69 74 20 69 time.** and it i
48080 73 20 70 6f 73 73 69 62 6c 65 20 74 68 61 74 20 s possible that
48090 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 6d another thread m
480a0 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 ight change the
480b0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 20 parameter.** in
480c0 62 65 74 77 65 65 6e 20 74 68 65 20 74 69 6d 65 between the time
480d0 73 20 77 68 65 6e 20 2a 70 43 75 72 72 65 6e 74 s when *pCurrent
480e0 20 61 6e 64 20 2a 70 48 69 67 68 77 61 74 65 72 and *pHighwater
480f0 20 61 72 65 20 77 72 69 74 74 65 6e 2e 0a 2a 2a are written..**
48100 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
48110 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 qlite3_db_status
48120 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 ()].*/.SQLITE_EX
48130 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 PERIMENTAL int s
48140 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 69 6e qlite3_status(in
48150 74 20 6f 70 2c 20 69 6e 74 20 2a 70 43 75 72 72 t op, int *pCurr
48160 65 6e 74 2c 20 69 6e 74 20 2a 70 48 69 67 68 77 ent, int *pHighw
48170 61 74 65 72 2c 20 69 6e 74 20 72 65 73 65 74 46 ater, int resetF
48180 6c 61 67 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 lag);.../*.** CA
48190 50 49 33 52 45 46 3a 20 53 74 61 74 75 73 20 50 PI3REF: Status P
481a0 61 72 61 6d 65 74 65 72 73 20 7b 48 31 37 32 35 arameters {H1725
481b0 30 7d 20 3c 48 31 37 32 30 30 3e 0a 2a 2a 20 45 0} <H17200>.** E
481c0 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a XPERIMENTAL.**.*
481d0 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 * These integer
481e0 63 6f 6e 73 74 61 6e 74 73 20 64 65 73 69 67 6e constants design
481f0 61 74 65 20 76 61 72 69 6f 75 73 20 72 75 6e 2d ate various run-
48200 74 69 6d 65 20 73 74 61 74 75 73 20 70 61 72 61 time status para
48210 6d 65 74 65 72 73 0a 2a 2a 20 74 68 61 74 20 63 meters.** that c
48220 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 62 an be returned b
48230 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 y [sqlite3_statu
48240 73 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e s()]..**.** <dl>
48250 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 .** <dt>SQLITE_S
48260 54 41 54 55 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 TATUS_MEMORY_USE
48270 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 D</dt>.** <dd>Th
48280 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 is parameter is
48290 74 68 65 20 63 75 72 72 65 6e 74 20 61 6d 6f 75 the current amou
482a0 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 20 63 68 65 nt of memory che
482b0 63 6b 65 64 20 6f 75 74 0a 2a 2a 20 75 73 69 6e cked out.** usin
482c0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f g [sqlite3_mallo
482d0 63 28 29 5d 2c 20 65 69 74 68 65 72 20 64 69 72 c()], either dir
482e0 65 63 74 6c 79 20 6f 72 20 69 6e 64 69 72 65 63 ectly or indirec
482f0 74 6c 79 2e 20 20 54 68 65 0a 2a 2a 20 66 69 67 tly. The.** fig
48300 75 72 65 20 69 6e 63 6c 75 64 65 73 20 63 61 6c ure includes cal
48310 6c 73 20 6d 61 64 65 20 74 6f 20 5b 73 71 6c 69 ls made to [sqli
48320 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 79 te3_malloc()] by
48330 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
48340 0a 2a 2a 20 61 6e 64 20 69 6e 74 65 72 6e 61 6c .** and internal
48350 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 20 62 79 memory usage by
48360 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 the SQLite libr
48370 61 72 79 2e 20 20 53 63 72 61 74 63 68 20 6d 65 ary. Scratch me
48380 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 6c mory.** controll
48390 65 64 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f ed by [SQLITE_CO
483a0 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e NFIG_SCRATCH] an
483b0 64 20 61 75 78 69 6c 69 61 72 79 20 70 61 67 65 d auxiliary page
483c0 2d 63 61 63 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 -cache.** memory
483d0 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 5b controlled by [
483e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 SQLITE_CONFIG_PA
483f0 47 45 43 41 43 48 45 5d 20 69 73 20 6e 6f 74 20 GECACHE] is not
48400 69 6e 63 6c 75 64 65 64 20 69 6e 0a 2a 2a 20 74 included in.** t
48410 68 69 73 20 70 61 72 61 6d 65 74 65 72 2e 20 20 his parameter.
48420 54 68 65 20 61 6d 6f 75 6e 74 20 72 65 74 75 72 The amount retur
48430 6e 65 64 20 69 73 20 74 68 65 20 73 75 6d 20 6f ned is the sum o
48440 66 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e f the allocation
48450 0a 2a 2a 20 73 69 7a 65 73 20 61 73 20 72 65 70 .** sizes as rep
48460 6f 72 74 65 64 20 62 79 20 74 68 65 20 78 53 69 orted by the xSi
48470 7a 65 20 6d 65 74 68 6f 64 20 69 6e 20 5b 73 71 ze method in [sq
48480 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
48490 73 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c s].</dd>.**.** <
484a0 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 dt>SQLITE_STATUS
484b0 5f 4d 41 4c 4c 4f 43 5f 53 49 5a 45 3c 2f 64 74 _MALLOC_SIZE</dt
484c0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 >.** <dd>This pa
484d0 72 61 6d 65 74 65 72 20 72 65 63 6f 72 64 73 20 rameter records
484e0 74 68 65 20 6c 61 72 67 65 73 74 20 6d 65 6d 6f the largest memo
484f0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 ry allocation re
48500 71 75 65 73 74 0a 2a 2a 20 68 61 6e 64 65 64 20 quest.** handed
48510 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c to [sqlite3_mall
48520 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 oc()] or [sqlite
48530 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 28 6f 72 3_realloc()] (or
48540 20 74 68 65 69 72 0a 2a 2a 20 69 6e 74 65 72 6e their.** intern
48550 61 6c 20 65 71 75 69 76 61 6c 65 6e 74 73 29 2e al equivalents).
48560 20 20 4f 6e 6c 79 20 74 68 65 20 76 61 6c 75 65 Only the value
48570 20 72 65 74 75 72 6e 65 64 20 69 6e 20 74 68 65 returned in the
48580 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74 65 72 20 .** *pHighwater
48590 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 parameter to [sq
485a0 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 20 lite3_status()]
485b0 69 73 20 6f 66 20 69 6e 74 65 72 65 73 74 2e 20 is of interest.
485c0 20 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 77 .** The value w
485d0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 ritten into the
485e0 2a 70 43 75 72 72 65 6e 74 20 70 61 72 61 6d 65 *pCurrent parame
485f0 74 65 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ter is undefined
48600 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
48610 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 >SQLITE_STATUS_P
48620 41 47 45 43 41 43 48 45 5f 55 53 45 44 3c 2f 64 AGECACHE_USED</d
48630 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 t>.** <dd>This p
48640 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 arameter returns
48650 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 the number of p
48660 61 67 65 73 20 75 73 65 64 20 6f 75 74 20 6f 66 ages used out of
48670 20 74 68 65 0a 2a 2a 20 5b 70 61 67 65 63 61 63 the.** [pagecac
48680 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
48690 74 6f 72 5d 20 74 68 61 74 20 77 61 73 20 63 6f tor] that was co
486a0 6e 66 69 67 75 72 65 64 20 75 73 69 6e 67 20 0a nfigured using .
486b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ** [SQLITE_CONFI
486c0 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 20 20 54 G_PAGECACHE]. T
486d0 68 65 0a 2a 2a 20 76 61 6c 75 65 20 72 65 74 75 he.** value retu
486e0 72 6e 65 64 20 69 73 20 69 6e 20 70 61 67 65 73 rned is in pages
486f0 2c 20 6e 6f 74 20 69 6e 20 62 79 74 65 73 2e 3c , not in bytes.<
48700 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
48710 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 QLITE_STATUS_PAG
48720 45 43 41 43 48 45 5f 4f 56 45 52 46 4c 4f 57 3c ECACHE_OVERFLOW<
48730 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 /dt>.** <dd>This
48740 20 70 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 parameter retur
48750 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
48760 20 62 79 74 65 73 20 6f 66 20 70 61 67 65 20 63 bytes of page c
48770 61 63 68 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 ache.** allocati
48780 6f 6e 20 77 68 69 63 68 20 63 6f 75 6c 64 20 6e on which could n
48790 6f 74 20 62 65 20 73 74 61 74 69 73 66 69 65 64 ot be statisfied
487a0 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f by the [SQLITE_
487b0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 CONFIG_PAGECACHE
487c0 5d 0a 2a 2a 20 62 75 66 66 65 72 20 61 6e 64 20 ].** buffer and
487d0 77 68 65 72 65 20 66 6f 72 63 65 64 20 74 6f 20 where forced to
487e0 6f 76 65 72 66 6c 6f 77 20 74 6f 20 5b 73 71 6c overflow to [sql
487f0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 ite3_malloc()].
48800 20 54 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 The.** returned
48810 20 76 61 6c 75 65 20 69 6e 63 6c 75 64 65 73 20 value includes
48820 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 74 68 61 74 allocations that
48830 20 6f 76 65 72 66 6c 6f 77 65 64 20 62 65 63 61 overflowed beca
48840 75 73 65 20 74 68 65 79 0a 2a 2a 20 77 68 65 72 use they.** wher
48850 65 20 74 6f 6f 20 6c 61 72 67 65 20 28 74 68 65 e too large (the
48860 79 20 77 65 72 65 20 6c 61 72 67 65 72 20 74 68 y were larger th
48870 61 6e 20 74 68 65 20 22 73 7a 22 20 70 61 72 61 an the "sz" para
48880 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c meter to.** [SQL
48890 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 ITE_CONFIG_PAGEC
488a0 41 43 48 45 5d 29 20 61 6e 64 20 61 6c 6c 6f 63 ACHE]) and alloc
488b0 61 74 69 6f 6e 73 20 74 68 61 74 20 6f 76 65 72 ations that over
488c0 66 6c 6f 77 65 64 20 62 65 63 61 75 73 65 0a 2a flowed because.*
488d0 2a 20 6e 6f 20 73 70 61 63 65 20 77 61 73 20 6c * no space was l
488e0 65 66 74 20 69 6e 20 74 68 65 20 70 61 67 65 20 eft in the page
488f0 63 61 63 68 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a cache.</dd>.**.*
48900 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 * <dt>SQLITE_STA
48910 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f 53 49 TUS_PAGECACHE_SI
48920 5a 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 ZE</dt>.** <dd>T
48930 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 his parameter re
48940 63 6f 72 64 73 20 74 68 65 20 6c 61 72 67 65 73 cords the larges
48950 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 t memory allocat
48960 69 6f 6e 20 72 65 71 75 65 73 74 0a 2a 2a 20 68 ion request.** h
48970 61 6e 64 65 64 20 74 6f 20 5b 70 61 67 65 63 61 anded to [pageca
48980 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 che memory alloc
48990 61 74 6f 72 5d 2e 20 20 4f 6e 6c 79 20 74 68 65 ator]. Only the
489a0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
489b0 69 6e 20 74 68 65 0a 2a 2a 20 2a 70 48 69 67 68 in the.** *pHigh
489c0 77 61 74 65 72 20 70 61 72 61 6d 65 74 65 72 20 water parameter
489d0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 to [sqlite3_stat
489e0 75 73 28 29 5d 20 69 73 20 6f 66 20 69 6e 74 65 us()] is of inte
489f0 72 65 73 74 2e 20 20 0a 2a 2a 20 54 68 65 20 76 rest. .** The v
48a00 61 6c 75 65 20 77 72 69 74 74 65 6e 20 69 6e 74 alue written int
48a10 6f 20 74 68 65 20 2a 70 43 75 72 72 65 6e 74 20 o the *pCurrent
48a20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 6e 64 parameter is und
48a30 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a efined.</dd>.**.
48a40 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 ** <dt>SQLITE_ST
48a50 41 54 55 53 5f 53 43 52 41 54 43 48 5f 55 53 45 ATUS_SCRATCH_USE
48a60 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 D</dt>.** <dd>Th
48a70 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 74 is parameter ret
48a80 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
48a90 6f 66 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 75 of allocations u
48aa0 73 65 64 20 6f 75 74 20 6f 66 20 74 68 65 0a 2a sed out of the.*
48ab0 2a 20 5b 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 * [scratch memor
48ac0 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e y allocator] con
48ad0 66 69 67 75 72 65 64 20 75 73 69 6e 67 0a 2a 2a figured using.**
48ae0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
48af0 53 43 52 41 54 43 48 5d 2e 20 20 54 68 65 20 76 SCRATCH]. The v
48b00 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 alue returned is
48b10 20 69 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c in allocations,
48b20 20 6e 6f 74 0a 2a 2a 20 69 6e 20 62 79 74 65 73 not.** in bytes
48b30 2e 20 20 53 69 6e 63 65 20 61 20 73 69 6e 67 6c . Since a singl
48b40 65 20 74 68 72 65 61 64 20 6d 61 79 20 6f 6e 6c e thread may onl
48b50 79 20 68 61 76 65 20 6f 6e 65 20 73 63 72 61 74 y have one scrat
48b60 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a ch allocation.**
48b70 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 61 74 20 outstanding at
48b80 74 69 6d 65 2c 20 74 68 69 73 20 70 61 72 61 6d time, this param
48b90 65 74 65 72 20 61 6c 73 6f 20 72 65 70 6f 72 74 eter also report
48ba0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
48bb0 74 68 72 65 61 64 73 0a 2a 2a 20 75 73 69 6e 67 threads.** using
48bc0 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 scratch memory
48bd0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 at the same time
48be0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
48bf0 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 >SQLITE_STATUS_S
48c00 43 52 41 54 43 48 5f 4f 56 45 52 46 4c 4f 57 3c CRATCH_OVERFLOW<
48c10 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 /dt>.** <dd>This
48c20 20 70 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 parameter retur
48c30 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
48c40 20 62 79 74 65 73 20 6f 66 20 73 63 72 61 74 63 bytes of scratc
48c50 68 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f h memory.** allo
48c60 63 61 74 69 6f 6e 20 77 68 69 63 68 20 63 6f 75 cation which cou
48c70 6c 64 20 6e 6f 74 20 62 65 20 73 74 61 74 69 73 ld not be statis
48c80 66 69 65 64 20 62 79 20 74 68 65 20 5b 53 51 4c fied by the [SQL
48c90 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 ITE_CONFIG_SCRAT
48ca0 43 48 5d 0a 2a 2a 20 62 75 66 66 65 72 20 61 6e CH].** buffer an
48cb0 64 20 77 68 65 72 65 20 66 6f 72 63 65 64 20 74 d where forced t
48cc0 6f 20 6f 76 65 72 66 6c 6f 77 20 74 6f 20 5b 73 o overflow to [s
48cd0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
48ce0 2e 20 20 54 68 65 20 76 61 6c 75 65 73 0a 2a 2a . The values.**
48cf0 20 72 65 74 75 72 6e 65 64 20 69 6e 63 6c 75 64 returned includ
48d00 65 20 6f 76 65 72 66 6c 6f 77 73 20 62 65 63 61 e overflows beca
48d10 75 73 65 20 74 68 65 20 72 65 71 75 65 73 74 65 use the requeste
48d20 64 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 77 61 73 d allocation was
48d30 20 74 6f 6f 0a 2a 2a 20 6c 61 72 67 65 72 20 28 too.** larger (
48d40 74 68 61 74 20 69 73 2c 20 62 65 63 61 75 73 65 that is, because
48d50 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 61 the requested a
48d60 6c 6c 6f 63 61 74 69 6f 6e 20 77 61 73 20 6c 61 llocation was la
48d70 72 67 65 72 20 74 68 61 6e 20 74 68 65 0a 2a 2a rger than the.**
48d80 20 22 73 7a 22 20 70 61 72 61 6d 65 74 65 72 20 "sz" parameter
48d90 74 6f 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 to [SQLITE_CONFI
48da0 47 5f 53 43 52 41 54 43 48 5d 29 20 61 6e 64 20 G_SCRATCH]) and
48db0 62 65 63 61 75 73 65 20 6e 6f 20 73 63 72 61 74 because no scrat
48dc0 63 68 20 62 75 66 66 65 72 0a 2a 2a 20 73 6c 6f ch buffer.** slo
48dd0 74 73 20 77 65 72 65 20 61 76 61 69 6c 61 62 6c ts were availabl
48de0 65 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a e..** </dd>.**.*
48df0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 * <dt>SQLITE_STA
48e00 54 55 53 5f 53 43 52 41 54 43 48 5f 53 49 5a 45 TUS_SCRATCH_SIZE
48e10 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 </dt>.** <dd>Thi
48e20 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 63 6f s parameter reco
48e30 72 64 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 rds the largest
48e40 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
48e50 6e 20 72 65 71 75 65 73 74 0a 2a 2a 20 68 61 6e n request.** han
48e60 64 65 64 20 74 6f 20 5b 73 63 72 61 74 63 68 20 ded to [scratch
48e70 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
48e80 5d 2e 20 20 4f 6e 6c 79 20 74 68 65 20 76 61 6c ]. Only the val
48e90 75 65 20 72 65 74 75 72 6e 65 64 20 69 6e 20 74 ue returned in t
48ea0 68 65 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74 65 he.** *pHighwate
48eb0 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b r parameter to [
48ec0 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 sqlite3_status()
48ed0 5d 20 69 73 20 6f 66 20 69 6e 74 65 72 65 73 74 ] is of interest
48ee0 2e 20 20 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 . .** The value
48ef0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 written into th
48f00 65 20 2a 70 43 75 72 72 65 6e 74 20 70 61 72 61 e *pCurrent para
48f10 6d 65 74 65 72 20 69 73 20 75 6e 64 65 66 69 6e meter is undefin
48f20 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c ed.</dd>.**.** <
48f30 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 dt>SQLITE_STATUS
48f40 5f 50 41 52 53 45 52 5f 53 54 41 43 4b 3c 2f 64 _PARSER_STACK</d
48f50 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 t>.** <dd>This p
48f60 61 72 61 6d 65 74 65 72 20 72 65 63 6f 72 64 73 arameter records
48f70 20 74 68 65 20 64 65 65 70 65 73 74 20 70 61 72 the deepest par
48f80 73 65 72 20 73 74 61 63 6b 2e 20 20 49 74 20 69 ser stack. It i
48f90 73 20 6f 6e 6c 79 0a 2a 2a 20 6d 65 61 6e 69 6e s only.** meanin
48fa0 67 66 75 6c 20 69 66 20 53 51 4c 69 74 65 20 69 gful if SQLite i
48fb0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 s compiled with
48fc0 5b 59 59 54 52 41 43 4b 4d 41 58 53 54 41 43 4b [YYTRACKMAXSTACK
48fd0 44 45 50 54 48 5d 2e 3c 2f 64 64 3e 0a 2a 2a 20 DEPTH].</dd>.**
48fe0 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 </dl>.**.** New
48ff0 73 74 61 74 75 73 20 70 61 72 61 6d 65 74 65 72 status parameter
49000 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 66 s may be added f
49010 72 6f 6d 20 74 69 6d 65 20 74 6f 20 74 69 6d 65 rom time to time
49020 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
49030 49 54 45 5f 53 54 41 54 55 53 5f 4d 45 4d 4f 52 ITE_STATUS_MEMOR
49040 59 5f 55 53 45 44 20 20 20 20 20 20 20 20 20 20 Y_USED
49050 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
49060 5f 53 54 41 54 55 53 5f 50 41 47 45 43 41 43 48 _STATUS_PAGECACH
49070 45 5f 55 53 45 44 20 20 20 20 20 20 20 31 0a 23 E_USED 1.#
49080 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 define SQLITE_ST
49090 41 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f 4f ATUS_PAGECACHE_O
490a0 56 45 52 46 4c 4f 57 20 20 20 32 0a 23 64 65 66 VERFLOW 2.#def
490b0 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 ine SQLITE_STATU
490c0 53 5f 53 43 52 41 54 43 48 5f 55 53 45 44 20 20 S_SCRATCH_USED
490d0 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 3.#define
490e0 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 SQLITE_STATUS_S
490f0 43 52 41 54 43 48 5f 4f 56 45 52 46 4c 4f 57 20 CRATCH_OVERFLOW
49100 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4.#define SQ
49110 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 41 4c 4c LITE_STATUS_MALL
49120 4f 43 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 OC_SIZE
49130 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 5.#define SQLIT
49140 45 5f 53 54 41 54 55 53 5f 50 41 52 53 45 52 5f E_STATUS_PARSER_
49150 53 54 41 43 4b 20 20 20 20 20 20 20 20 20 36 0a STACK 6.
49160 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
49170 54 41 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f TATUS_PAGECACHE_
49180 53 49 5a 45 20 20 20 20 20 20 20 37 0a 23 64 65 SIZE 7.#de
49190 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 fine SQLITE_STAT
491a0 55 53 5f 53 43 52 41 54 43 48 5f 53 49 5a 45 20 US_SCRATCH_SIZE
491b0 20 20 20 20 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 8../*.**
491c0 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 CAPI3REF: Datab
491d0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 53 ase Connection S
491e0 74 61 74 75 73 20 7b 48 31 37 35 30 30 7d 20 3c tatus {H17500} <
491f0 53 36 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 S60200>.** EXPER
49200 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 IMENTAL.**.** Th
49210 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 is interface is
49220 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 used to retrieve
49230 20 72 75 6e 74 69 6d 65 20 73 74 61 74 75 73 20 runtime status
49240 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 0a 2a 2a 20 information .**
49250 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 5b about a single [
49260 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
49270 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 ion]. The first
49280 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
49290 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
492a0 6e 65 63 74 69 6f 6e 20 6f 62 6a 65 63 74 20 74 nection object t
492b0 6f 20 62 65 20 69 6e 74 65 72 72 6f 67 61 74 65 o be interrogate
492c0 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 d. The second a
492d0 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 74 68 rgument.** is th
492e0 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 69 e parameter to i
492f0 6e 74 65 72 72 6f 67 61 74 65 2e 20 20 43 75 72 nterrogate. Cur
49300 72 65 6e 74 6c 79 2c 20 74 68 65 20 6f 6e 6c 79 rently, the only
49310 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 0a 2a allowed value.*
49320 2a 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 * for the second
49330 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 5b 53 parameter is [S
49340 51 4c 49 54 45 5f 44 42 53 54 41 54 55 53 5f 4c QLITE_DBSTATUS_L
49350 4f 4f 4b 41 53 49 44 45 5f 55 53 45 44 5d 2e 0a OOKASIDE_USED]..
49360 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6f 70 ** Additional op
49370 74 69 6f 6e 73 20 77 69 6c 6c 20 6c 69 6b 65 6c tions will likel
49380 79 20 61 70 70 65 61 72 20 69 6e 20 66 75 74 75 y appear in futu
49390 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 re releases of S
493a0 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 QLite..**.** The
493b0 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f current value o
493c0 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 f the requested
493d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 77 72 69 parameter is wri
493e0 74 74 65 6e 20 69 6e 74 6f 20 2a 70 43 75 72 0a tten into *pCur.
493f0 2a 2a 20 61 6e 64 20 74 68 65 20 68 69 67 68 65 ** and the highe
49400 73 74 20 69 6e 73 74 61 6e 74 61 6e 65 6f 75 73 st instantaneous
49410 20 76 61 6c 75 65 20 69 73 20 77 72 69 74 74 65 value is writte
49420 6e 20 69 6e 74 6f 20 2a 70 48 69 77 74 72 2e 20 n into *pHiwtr.
49430 20 49 66 0a 2a 2a 20 74 68 65 20 72 65 73 65 74 If.** the reset
49440 46 6c 67 20 69 73 20 74 72 75 65 2c 20 74 68 65 Flg is true, the
49450 6e 20 74 68 65 20 68 69 67 68 65 73 74 20 69 6e n the highest in
49460 73 74 61 6e 74 61 6e 65 6f 75 73 20 76 61 6c 75 stantaneous valu
49470 65 20 69 73 0a 2a 2a 20 72 65 73 65 74 20 62 61 e is.** reset ba
49480 63 6b 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 63 ck down to the c
49490 75 72 72 65 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a urrent value..**
494a0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
494b0 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d qlite3_status()]
494c0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 and [sqlite3_st
494d0 6d 74 5f 73 74 61 74 75 73 28 29 5d 2e 0a 2a 2f mt_status()]..*/
494e0 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 .SQLITE_EXPERIME
494f0 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 NTAL int sqlite3
49500 5f 64 62 5f 73 74 61 74 75 73 28 73 71 6c 69 74 _db_status(sqlit
49510 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 69 6e 74 e3*, int op, int
49520 20 2a 70 43 75 72 2c 20 69 6e 74 20 2a 70 48 69 *pCur, int *pHi
49530 77 74 72 2c 20 69 6e 74 20 72 65 73 65 74 46 6c wtr, int resetFl
49540 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 g);../*.** CAPI3
49550 52 45 46 3a 20 53 74 61 74 75 73 20 50 61 72 61 REF: Status Para
49560 6d 65 74 65 72 73 20 66 6f 72 20 64 61 74 61 62 meters for datab
49570 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 ase connections
49580 7b 48 31 37 35 32 30 7d 20 3c 48 31 37 35 30 30 {H17520} <H17500
49590 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 >.** EXPERIMENTA
495a0 4c 0a 2a 2a 0a 2a 2a 20 53 74 61 74 75 73 20 76 L.**.** Status v
495b0 65 72 62 73 20 66 6f 72 20 5b 73 71 6c 69 74 65 erbs for [sqlite
495c0 33 5f 64 62 5f 73 74 61 74 75 73 28 29 5d 2e 0a 3_db_status()]..
495d0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 **.** <dl>.** <d
495e0 74 3e 53 51 4c 49 54 45 5f 44 42 53 54 41 54 55 t>SQLITE_DBSTATU
495f0 53 5f 4c 4f 4f 4b 41 53 49 44 45 5f 55 53 45 44 S_LOOKASIDE_USED
49600 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 </dt>.** <dd>Thi
49610 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 74 75 s parameter retu
49620 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
49630 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f f lookaside memo
49640 72 79 20 73 6c 6f 74 73 20 63 75 72 72 65 6e 74 ry slots current
49650 6c 79 0a 2a 2a 20 63 68 65 63 6b 65 64 20 6f 75 ly.** checked ou
49660 74 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e t.</dd>.** </dl>
49670 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
49680 54 45 5f 44 42 53 54 41 54 55 53 5f 4c 4f 4f 4b TE_DBSTATUS_LOOK
49690 41 53 49 44 45 5f 55 53 45 44 20 20 20 20 20 30 ASIDE_USED 0
496a0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 .../*.** CAPI3RE
496b0 46 3a 20 50 72 65 70 61 72 65 64 20 53 74 61 74 F: Prepared Stat
496c0 65 6d 65 6e 74 20 53 74 61 74 75 73 20 7b 48 31 ement Status {H1
496d0 37 35 35 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 7550} <S60200>.*
496e0 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
496f0 2a 0a 2a 2a 20 45 61 63 68 20 70 72 65 70 61 72 *.** Each prepar
49700 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6d 61 69 ed statement mai
49710 6e 74 61 69 6e 73 20 76 61 72 69 6f 75 73 0a 2a ntains various.*
49720 2a 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 53 54 * [SQLITE_STMTST
49730 41 54 55 53 5f 53 4f 52 54 20 7c 20 63 6f 75 6e ATUS_SORT | coun
49740 74 65 72 73 5d 20 74 68 61 74 20 6d 65 61 73 75 ters] that measu
49750 72 65 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a re the number.**
49760 20 6f 66 20 74 69 6d 65 73 20 69 74 20 68 61 73 of times it has
49770 20 70 65 72 66 6f 72 6d 65 64 20 73 70 65 63 69 performed speci
49780 66 69 63 20 6f 70 65 72 61 74 69 6f 6e 73 2e 20 fic operations.
49790 20 54 68 65 73 65 20 63 6f 75 6e 74 65 72 73 20 These counters
497a0 63 61 6e 0a 2a 2a 20 62 65 20 75 73 65 64 20 74 can.** be used t
497b0 6f 20 6d 6f 6e 69 74 6f 72 20 74 68 65 20 70 65 o monitor the pe
497c0 72 66 6f 72 6d 61 6e 63 65 20 63 68 61 72 61 63 rformance charac
497d0 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 teristics of the
497e0 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 prepared.** sta
497f0 74 65 6d 65 6e 74 73 2e 20 20 46 6f 72 20 65 78 tements. For ex
49800 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 6e 75 ample, if the nu
49810 6d 62 65 72 20 6f 66 20 74 61 62 6c 65 20 73 74 mber of table st
49820 65 70 73 20 67 72 65 61 74 6c 79 20 65 78 63 65 eps greatly exce
49830 65 64 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 eds.** the numbe
49840 72 20 6f 66 20 74 61 62 6c 65 20 73 65 61 72 63 r of table searc
49850 68 65 73 20 6f 72 20 72 65 73 75 6c 74 20 72 6f hes or result ro
49860 77 73 2c 20 74 68 61 74 20 77 6f 75 6c 64 20 74 ws, that would t
49870 65 6e 64 20 74 6f 20 69 6e 64 69 63 61 74 65 0a end to indicate.
49880 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 65 70 ** that the prep
49890 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 ared statement i
498a0 73 20 75 73 69 6e 67 20 61 20 66 75 6c 6c 20 74 s using a full t
498b0 61 62 6c 65 20 73 63 61 6e 20 72 61 74 68 65 72 able scan rather
498c0 20 74 68 61 6e 0a 2a 2a 20 61 6e 20 69 6e 64 65 than.** an inde
498d0 78 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 x. .**.** This
498e0 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 interface is use
498f0 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 6e d to retrieve an
49900 64 20 72 65 73 65 74 20 63 6f 75 6e 74 65 72 20 d reset counter
49910 76 61 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 61 values from.** a
49920 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
49930 6d 65 6e 74 5d 2e 20 20 54 68 65 20 66 69 72 73 ment]. The firs
49940 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 t argument is th
49950 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 e prepared state
49960 6d 65 6e 74 0a 2a 2a 20 6f 62 6a 65 63 74 20 74 ment.** object t
49970 6f 20 62 65 20 69 6e 74 65 72 72 6f 67 61 74 65 o be interrogate
49980 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 d. The second a
49990 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 61 6e rgument.** is an
499a0 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 66 6f integer code fo
499b0 72 20 61 20 73 70 65 63 69 66 69 63 20 5b 53 51 r a specific [SQ
499c0 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f LITE_STMTSTATUS_
499d0 53 4f 52 54 20 7c 20 63 6f 75 6e 74 65 72 5d 0a SORT | counter].
499e0 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 6f ** to be interro
499f0 67 61 74 65 64 2e 20 0a 2a 2a 20 54 68 65 20 63 gated. .** The c
49a00 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 urrent value of
49a10 74 68 65 20 72 65 71 75 65 73 74 65 64 20 63 6f the requested co
49a20 75 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 unter is returne
49a30 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 d..** If the res
49a40 65 74 46 6c 67 20 69 73 20 74 72 75 65 2c 20 74 etFlg is true, t
49a50 68 65 6e 20 74 68 65 20 63 6f 75 6e 74 65 72 20 hen the counter
49a60 69 73 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f is reset to zero
49a70 20 61 66 74 65 72 20 74 68 69 73 0a 2a 2a 20 69 after this.** i
49a80 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 72 65 nterface call re
49a90 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 turns..**.** See
49aa0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
49ab0 73 74 61 74 75 73 28 29 5d 20 61 6e 64 20 5b 73 status()] and [s
49ac0 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 qlite3_db_status
49ad0 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 ()]..*/.SQLITE_E
49ae0 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 XPERIMENTAL int
49af0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 73 74 61 sqlite3_stmt_sta
49b00 74 75 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 tus(sqlite3_stmt
49b10 2a 2c 20 69 6e 74 20 6f 70 2c 69 6e 74 20 72 65 *, int op,int re
49b20 73 65 74 46 6c 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 setFlg);../*.**
49b30 43 41 50 49 33 52 45 46 3a 20 53 74 61 74 75 73 CAPI3REF: Status
49b40 20 50 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 Parameters for
49b50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
49b60 6e 74 73 20 7b 48 31 37 35 37 30 7d 20 3c 48 31 nts {H17570} <H1
49b70 37 35 35 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 7550>.** EXPERIM
49b80 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ENTAL.**.** Thes
49b90 65 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d e preprocessor m
49ba0 61 63 72 6f 73 20 64 65 66 69 6e 65 20 69 6e 74 acros define int
49bb0 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 eger codes that
49bc0 6e 61 6d 65 20 63 6f 75 6e 74 65 72 0a 2a 2a 20 name counter.**
49bd0 76 61 6c 75 65 73 20 61 73 73 6f 63 69 61 74 65 values associate
49be0 64 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 d with the [sqli
49bf0 74 65 33 5f 73 74 6d 74 5f 73 74 61 74 75 73 28 te3_stmt_status(
49c00 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a )] interface..**
49c10 20 54 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 The meanings of
49c20 20 74 68 65 20 76 61 72 69 6f 75 73 20 63 6f 75 the various cou
49c30 6e 74 65 72 73 20 61 72 65 20 61 73 20 66 6f 6c nters are as fol
49c40 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e lows:.**.** <dl>
49c50 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 .** <dt>SQLITE_S
49c60 54 4d 54 53 54 41 54 55 53 5f 46 55 4c 4c 53 43 TMTSTATUS_FULLSC
49c70 41 4e 5f 53 54 45 50 3c 2f 64 74 3e 0a 2a 2a 20 AN_STEP</dt>.**
49c80 3c 64 64 3e 54 68 69 73 20 69 73 20 74 68 65 20 <dd>This is the
49c90 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 number of times
49ca0 74 68 61 74 20 53 51 4c 69 74 65 20 68 61 73 20 that SQLite has
49cb0 73 74 65 70 70 65 64 20 66 6f 72 77 61 72 64 20 stepped forward
49cc0 69 6e 0a 2a 2a 20 61 20 74 61 62 6c 65 20 61 73 in.** a table as
49cd0 20 70 61 72 74 20 6f 66 20 61 20 66 75 6c 6c 20 part of a full
49ce0 74 61 62 6c 65 20 73 63 61 6e 2e 20 20 4c 61 72 table scan. Lar
49cf0 67 65 20 6e 75 6d 62 65 72 73 20 66 6f 72 20 74 ge numbers for t
49d00 68 69 73 20 63 6f 75 6e 74 65 72 0a 2a 2a 20 6d his counter.** m
49d10 61 79 20 69 6e 64 69 63 61 74 65 20 6f 70 70 6f ay indicate oppo
49d20 72 74 75 6e 69 74 69 65 73 20 66 6f 72 20 70 65 rtunities for pe
49d30 72 66 6f 72 6d 61 6e 63 65 20 69 6d 70 72 6f 76 rformance improv
49d40 65 6d 65 6e 74 20 74 68 72 6f 75 67 68 20 0a 2a ement through .*
49d50 2a 20 63 61 72 65 66 75 6c 20 75 73 65 20 6f 66 * careful use of
49d60 20 69 6e 64 69 63 65 73 2e 3c 2f 64 64 3e 0a 2a indices.</dd>.*
49d70 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
49d80 53 54 4d 54 53 54 41 54 55 53 5f 53 4f 52 54 3c STMTSTATUS_SORT<
49d90 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 /dt>.** <dd>This
49da0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
49db0 66 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e f sort operation
49dc0 73 20 74 68 61 74 20 68 61 76 65 20 6f 63 63 75 s that have occu
49dd0 72 72 65 64 2e 0a 2a 2a 20 41 20 6e 6f 6e 2d 7a rred..** A non-z
49de0 65 72 6f 20 76 61 6c 75 65 20 69 6e 20 74 68 69 ero value in thi
49df0 73 20 63 6f 75 6e 74 65 72 20 6d 61 79 20 69 6e s counter may in
49e00 64 69 63 61 74 65 20 61 6e 20 6f 70 70 6f 72 74 dicate an opport
49e10 75 6e 69 74 79 20 74 6f 0a 2a 2a 20 69 6d 70 72 unity to.** impr
49e20 6f 76 65 6d 65 6e 74 20 70 65 72 66 6f 72 6d 61 ovement performa
49e30 6e 63 65 20 74 68 72 6f 75 67 68 20 63 61 72 65 nce through care
49e40 66 75 6c 20 75 73 65 20 6f 66 20 69 6e 64 69 63 ful use of indic
49e50 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c es.</dd>.**.** <
49e60 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 /dl>.*/.#define
49e70 53 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 55 SQLITE_STMTSTATU
49e80 53 5f 46 55 4c 4c 53 43 41 4e 5f 53 54 45 50 20 S_FULLSCAN_STEP
49e90 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 1.#define SQ
49ea0 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f LITE_STMTSTATUS_
49eb0 53 4f 52 54 20 20 20 20 20 20 20 20 20 20 20 20 SORT
49ec0 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 55 6e 64 6f 20 2../*.** Undo
49ed0 74 68 65 20 68 61 63 6b 20 74 68 61 74 20 63 6f the hack that co
49ee0 6e 76 65 72 74 73 20 66 6c 6f 61 74 69 6e 67 20 nverts floating
49ef0 70 6f 69 6e 74 20 74 79 70 65 73 20 74 6f 20 69 point types to i
49f00 6e 74 65 67 65 72 20 66 6f 72 0a 2a 2a 20 62 75 nteger for.** bu
49f10 69 6c 64 73 20 6f 6e 20 70 72 6f 63 65 73 73 6f ilds on processo
49f20 72 73 20 77 69 74 68 6f 75 74 20 66 6c 6f 61 74 rs without float
49f30 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 ing point suppor
49f40 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c t..*/.#ifdef SQL
49f50 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e ITE_OMIT_FLOATIN
49f60 47 5f 50 4f 49 4e 54 0a 23 20 75 6e 64 65 66 20 G_POINT.# undef
49f70 64 6f 75 62 6c 65 0a 23 65 6e 64 69 66 0a 0a 23 double.#endif..#
49f80 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75 ifdef __cplusplu
49f90 73 0a 7d 20 20 2f 2a 20 45 6e 64 20 6f 66 20 74 s.} /* End of t
49fa0 68 65 20 27 65 78 74 65 72 6e 20 22 43 22 27 20 he 'extern "C"'
49fb0 62 6c 6f 63 6b 20 2a 2f 0a 23 65 6e 64 69 66 0a block */.#endif.
49fc0 23 65 6e 64 69 66 0a #endif.