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 35 35 20 32 30 30 39 2f 30 n,v 1.455 2009/0
05f0: 35 2f 32 34 20 32 31 3a 35 39 3a 32 38 20 64 72 5/24 21:59:28 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 52 65 71 75 69 72 65 6d 65 .**.** Requireme
0e50: 6e 74 73 3a 20 5b 48 31 30 30 31 31 5d 20 5b 48 nts: [H10011] [H
0e60: 31 30 30 31 34 5d 0a 2a 2f 0a 23 64 65 66 69 6e 10014].*/.#defin
0e70: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e e SQLITE_VERSION
0e80: 20 20 20 20 20 20 20 20 20 22 33 2e 36 2e 31 34 "3.6.14
0e90: 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ".#define SQLITE
0ea0: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 _VERSION_NUMBER
0eb0: 20 33 30 30 36 30 31 34 0a 0a 2f 2a 0a 2a 2a 20 3006014../*.**
0ec0: 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 CAPI3REF: Run-Ti
0ed0: 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 me Library Versi
0ee0: 6f 6e 20 4e 75 6d 62 65 72 73 20 7b 48 31 30 30 on Numbers {H100
0ef0: 32 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 20 20} <S60100>.**
0f00: 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 KEYWORDS: sqlite
0f10: 33 5f 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3_version.**.**
0f20: 54 68 65 73 65 20 66 65 61 74 75 72 65 73 20 70 These features p
0f30: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20 rovide the same
0f40: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 information as t
0f50: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 he [SQLITE_VERSI
0f60: 4f 4e 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 ON].** and [SQLI
0f70: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 TE_VERSION_NUMBE
0f80: 52 5d 20 23 64 65 66 69 6e 65 73 20 69 6e 20 74 R] #defines in t
0f90: 68 65 20 68 65 61 64 65 72 2c 20 62 75 74 20 61 he header, but a
0fa0: 72 65 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a re associated.**
0fb0: 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 with the librar
0fc0: 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 y instead of the
0fd0: 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 43 header file. C
0fe0: 61 75 74 69 6f 75 73 20 70 72 6f 67 72 61 6d 6d autious programm
0ff0: 65 72 73 20 6d 69 67 68 74 0a 2a 2a 20 69 6e 63 ers might.** inc
1000: 6c 75 64 65 20 61 20 63 68 65 63 6b 20 69 6e 20 lude a check in
1010: 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f their applicatio
1020: 6e 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 n to verify that
1030: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 .** sqlite3_libv
1040: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 ersion_number()
1050: 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 always returns t
1060: 68 65 20 76 61 6c 75 65 0a 2a 2a 20 5b 53 51 4c he value.** [SQL
1070: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 ITE_VERSION_NUMB
1080: 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ER]..**.** The s
1090: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
10a0: 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 n() function ret
10b0: 75 72 6e 73 20 74 68 65 20 73 61 6d 65 20 69 6e urns the same in
10c0: 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 0a formation as is.
10d0: 2a 2a 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 ** in the sqlite
10e0: 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 3_version[] stri
10f0: 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 ng constant. Th
1100: 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 e function is pr
1110: 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 75 73 ovided.** for us
1120: 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 e in DLLs since
1130: 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c DLL users usuall
1140: 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 64 69 y do not have di
1150: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 rect access to s
1160: 74 72 69 6e 67 0a 2a 2a 20 63 6f 6e 73 74 61 6e tring.** constan
1170: 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c ts within the DL
1180: 4c 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 L..**.** Require
1190: 6d 65 6e 74 73 3a 20 5b 48 31 30 30 32 31 5d 20 ments: [H10021]
11a0: 5b 48 31 30 30 32 32 5d 20 5b 48 31 30 30 32 33 [H10022] [H10023
11b0: 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 ].*/.SQLITE_EXTE
11c0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 RN const char sq
11d0: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b lite3_version[];
11e0: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
11f0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 ite3_libversion(
1200: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 void);.int sqlit
1210: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 e3_libversion_nu
1220: 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a mber(void);../*.
1230: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 ** CAPI3REF: Tes
1240: 74 20 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 t To See If The
1250: 4c 69 62 72 61 72 79 20 49 73 20 54 68 72 65 61 Library Is Threa
1260: 64 73 61 66 65 20 7b 48 31 30 31 30 30 7d 20 3c dsafe {H10100} <
1270: 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 S60100>.**.** SQ
1280: 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 Lite can be comp
1290: 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 iled with or wit
12a0: 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 hout mutexes. W
12b0: 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 hen.** the [SQLI
12c0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 TE_THREADSAFE] C
12d0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 preprocessor ma
12e0: 63 72 6f 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 cro 1 or 2, mute
12f0: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c xes.** are enabl
1300: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73 ed and SQLite is
1310: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68 threadsafe. Wh
1320: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 en the.** [SQLIT
1330: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 E_THREADSAFE] ma
1340: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 cro is 0, .** th
1350: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d e mutexes are om
1360: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20 itted. Without
1370: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20 the mutexes, it
1380: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 is not safe.** t
1390: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e o use SQLite con
13a0: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d currently from m
13b0: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 ore than one thr
13c0: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c ead..**.** Enabl
13d0: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75 ing mutexes incu
13e0: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20 rs a measurable
13f0: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 performance pena
1400: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 lty..** So if sp
1410: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 eed is of utmost
1420: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 importance, it
1430: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64 makes sense to d
1440: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 isable.** the mu
1450: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20 texes. But for
1460: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 maximum safety,
1470: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62 mutexes should b
1480: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68 e enabled..** Th
1490: 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 e default behavi
14a0: 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65 or is for mutexe
14b0: 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e s to be enabled.
14c0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 .**.** This inte
14d0: 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 rface can be use
14e0: 64 20 62 79 20 61 20 70 72 6f 67 72 61 6d 20 74 d by a program t
14f0: 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 o make sure that
1500: 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 the.** version
1510: 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 of SQLite that i
1520: 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 t is linking aga
1530: 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 inst was compile
1540: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 d with.** the de
1550: 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 sired setting of
1560: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
1570: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a EADSAFE] macro..
1580: 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 **.** This inter
1590: 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 face only report
15a0: 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 s on the compile
15b0: 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74 -time mutex sett
15c0: 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 ing.** of the [S
15d0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
15e0: 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 ] flag. If SQLi
15f0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
1600: 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 ith.** SQLITE_TH
1610: 52 45 41 44 53 41 46 45 3d 31 20 74 68 65 6e 20 READSAFE=1 then
1620: 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62 mutexes are enab
1630: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62 led by default b
1640: 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c ut.** can be ful
1650: 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 ly or partially
1660: 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 disabled using a
1670: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
1680: 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 3_config()].** w
1690: 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53 ith the verbs [S
16a0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e QLITE_CONFIG_SIN
16b0: 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c GLETHREAD], [SQL
16c0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 ITE_CONFIG_MULTI
16d0: 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b THREAD],.** or [
16e0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
16f0: 54 45 58 5d 2e 20 20 54 68 65 20 72 65 74 75 72 TEX]. The retur
1700: 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 n value of this
1710: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 0a 2a function shows.*
1720: 2a 20 6f 6e 6c 79 20 74 68 65 20 64 65 66 61 75 * only the defau
1730: 6c 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 lt compile-time
1740: 73 65 74 74 69 6e 67 2c 20 6e 6f 74 20 61 6e 79 setting, not any
1750: 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 run-time change
1760: 73 0a 2a 2a 20 74 6f 20 74 68 61 74 20 73 65 74 s.** to that set
1770: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 ting..**.** See
1780: 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d the [threading m
1790: 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 ode] documentati
17a0: 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 on for additiona
17b0: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a l information..*
17c0: 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
17d0: 73 3a 20 5b 48 31 30 31 30 31 5d 20 5b 48 31 30 s: [H10101] [H10
17e0: 31 30 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 102].*/.int sqli
17f0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 te3_threadsafe(v
1800: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 oid);../*.** CAP
1810: 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 I3REF: Database
1820: 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c Connection Handl
1830: 65 20 7b 48 31 32 30 30 30 7d 20 3c 53 34 30 32 e {H12000} <S402
1840: 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 00>.** KEYWORDS:
1850: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 {database conne
1860: 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 ction} {database
1870: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a connections}.**
1880: 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 .** Each open SQ
1890: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 Lite database is
18a0: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 represented by
18b0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
18c0: 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 instance of.** t
18d0: 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 he opaque struct
18e0: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 ure named "sqlit
18f0: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 e3". It is usef
1900: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 ul to think of a
1910: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 n sqlite3.** poi
1920: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 nter as an objec
1930: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 t. The [sqlite3
1940: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 _open()], [sqlit
1950: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e e3_open16()], an
1960: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 d.** [sqlite3_op
1970: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 en_v2()] interfa
1980: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 ces are its cons
1990: 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 tructors, and [s
19a0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a qlite3_close()].
19b0: 2a 2a 20 69 73 20 69 74 73 20 64 65 73 74 72 75 ** is its destru
19c0: 63 74 6f 72 2e 20 20 54 68 65 72 65 20 61 72 65 ctor. There are
19d0: 20 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 many other inte
19e0: 72 66 61 63 65 73 20 28 73 75 63 68 20 61 73 0a rfaces (such as.
19f0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
1a00: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 are_v2()], [sqli
1a10: 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
1a20: 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b ion()], and.** [
1a30: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d sqlite3_busy_tim
1a40: 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 eout()] to name
1a50: 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20 but three) that
1a60: 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 are methods on a
1a70: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a n.** sqlite3 obj
1a80: 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ect..*/.typedef
1a90: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73 struct sqlite3 s
1aa0: 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 qlite3;../*.** C
1ab0: 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20 API3REF: 64-Bit
1ac0: 49 6e 74 65 67 65 72 20 54 79 70 65 73 20 7b 48 Integer Types {H
1ad0: 31 30 32 30 30 7d 20 3c 53 31 30 31 31 30 3e 0a 10200} <S10110>.
1ae0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c ** KEYWORDS: sql
1af0: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 ite_int64 sqlite
1b00: 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 _uint64.**.** Be
1b10: 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20 6e cause there is n
1b20: 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d o cross-platform
1b30: 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 79 20 way to specify
1b40: 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74 64-bit integer t
1b50: 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 ypes.** SQLite i
1b60: 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 66 73 ncludes typedefs
1b70: 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e for 64-bit sign
1b80: 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 ed and unsigned
1b90: 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 integers..**.**
1ba0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 The sqlite3_int6
1bb0: 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 4 and sqlite3_ui
1bc0: 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 72 65 nt64 are the pre
1bd0: 66 65 72 72 65 64 20 74 79 70 65 20 64 65 66 69 ferred type defi
1be0: 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 nitions..** The
1bf0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 sqlite_int64 and
1c00: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 sqlite_uint64 t
1c10: 79 70 65 73 20 61 72 65 20 73 75 70 70 6f 72 74 ypes are support
1c20: 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 ed for backwards
1c30: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 .** compatibilit
1c40: 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 52 65 y only..**.** Re
1c50: 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 quirements: [H10
1c60: 32 30 31 5d 20 5b 48 31 30 32 30 32 5d 0a 2a 2f 201] [H10202].*/
1c70: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 .#ifdef SQLITE_I
1c80: 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 NT64_TYPE. type
1c90: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 def SQLITE_INT64
1ca0: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 _TYPE sqlite_int
1cb0: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 64;. typedef un
1cc0: 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e signed SQLITE_IN
1cd0: 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f T64_TYPE sqlite_
1ce0: 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 uint64;.#elif de
1cf0: 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 fined(_MSC_VER)
1d00: 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 || defined(__BOR
1d10: 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 LANDC__). typed
1d20: 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 ef __int64 sqlit
1d30: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 e_int64;. typed
1d40: 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e ef unsigned __in
1d50: 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 t64 sqlite_uint6
1d60: 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64 4;.#else. typed
1d70: 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 ef long long int
1d80: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 sqlite_int64;.
1d90: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 typedef unsigne
1da0: 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 d long long int
1db0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 sqlite_uint64;.#
1dc0: 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73 71 endif.typedef sq
1dd0: 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 lite_int64 sqlit
1de0: 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 e3_int64;.typede
1df0: 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 f sqlite_uint64
1e00: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a sqlite3_uint64;.
1e10: 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c ./*.** If compil
1e20: 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73 ing for a proces
1e30: 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66 sor that lacks f
1e40: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 loating point su
1e50: 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 pport,.** substi
1e60: 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72 tute integer for
1e70: 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e floating-point.
1e80: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 .*/.#ifdef SQLIT
1e90: 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f E_OMIT_FLOATING_
1ea0: 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 POINT.# define d
1eb0: 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e ouble sqlite3_in
1ec0: 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a t64.#endif../*.*
1ed0: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 * CAPI3REF: Clos
1ee0: 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20 43 ing A Database C
1ef0: 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 32 30 31 onnection {H1201
1f00: 30 7d 20 3c 53 33 30 31 30 30 3e 3c 53 34 30 32 0} <S30100><S402
1f10: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 00>.**.** This r
1f20: 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20 64 65 outine is the de
1f30: 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 structor for the
1f40: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 [sqlite3] objec
1f50: 74 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 t..**.** Applica
1f60: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 tions should [sq
1f70: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c lite3_finalize |
1f80: 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b finalize] all [
1f90: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1fa0: 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c nts].** and [sql
1fb0: 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 ite3_blob_close
1fc0: 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c | close] all [BL
1fd0: 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f OB handles] asso
1fe0: 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 74 ciated with.** t
1ff0: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a he [sqlite3] obj
2000: 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 ect prior to att
2010: 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 empting to close
2020: 20 74 68 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 the object..**
2030: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 The [sqlite3_nex
2040: 74 5f 73 74 6d 74 28 29 5d 20 69 6e 74 65 72 66 t_stmt()] interf
2050: 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ace can be used
2060: 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a to locate all.**
2070: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2080: 6d 65 6e 74 73 5d 20 61 73 73 6f 63 69 61 74 65 ments] associate
2090: 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 d with a [databa
20a0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 se connection] i
20b0: 66 20 64 65 73 69 72 65 64 2e 0a 2a 2a 20 54 79 f desired..** Ty
20c0: 70 69 63 61 6c 20 63 6f 64 65 20 6d 69 67 68 74 pical code might
20d0: 20 6c 6f 6f 6b 20 6c 69 6b 65 20 74 68 69 73 3a look like this:
20e0: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
20f0: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 73 71 6c 69 te><pre>.** sqli
2100: 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 3b te3_stmt *pStmt;
2110: 0a 2a 2a 20 77 68 69 6c 65 28 20 28 70 53 74 6d .** while( (pStm
2120: 74 20 3d 20 73 71 6c 69 74 65 33 5f 6e 65 78 74 t = sqlite3_next
2130: 5f 73 74 6d 74 28 64 62 2c 20 30 29 29 21 3d 30 _stmt(db, 0))!=0
2140: 20 29 7b 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 ){.**
2150: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
2160: 28 70 53 74 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a (pStmt);.** }.**
2170: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
2180: 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73 ote>.**.** If [s
2190: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 qlite3_close()]
21a0: 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 is invoked while
21b0: 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 a transaction i
21c0: 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 s open,.** the t
21d0: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 ransaction is au
21e0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c tomatically roll
21f0: 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 ed back..**.** T
2200: 68 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 he C parameter t
2210: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 o [sqlite3_close
2220: 28 43 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74 (C)] must be eit
2230: 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f her a NULL.** po
2240: 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c inter or an [sql
2250: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 ite3] object poi
2260: 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a nter obtained.**
2270: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f from [sqlite3_o
2280: 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 pen()], [sqlite3
2290: 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a _open16()], or.*
22a0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f * [sqlite3_open_
22b0: 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 v2()], and not p
22c0: 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 reviously closed
22d0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
22e0: 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 30 31 31 ents:.** [H12011
22f0: 5d 20 5b 48 31 32 30 31 32 5d 20 5b 48 31 32 30 ] [H12012] [H120
2300: 31 33 5d 20 5b 48 31 32 30 31 34 5d 20 5b 48 31 13] [H12014] [H1
2310: 32 30 31 35 5d 20 5b 48 31 32 30 31 39 5d 0a 2a 2015] [H12019].*
2320: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c /.int sqlite3_cl
2330: 6f 73 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a ose(sqlite3 *);.
2340: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 ./*.** The type
2350: 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 for a callback f
2360: 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 unction..** This
2370: 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 is legacy and d
2380: 65 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 eprecated. It i
2390: 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 s included for h
23a0: 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d istorical.** com
23b0: 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 patibility and i
23c0: 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 s not documented
23d0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 ..*/.typedef int
23e0: 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 (*sqlite3_callb
23f0: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 ack)(void*,int,c
2400: 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a har**, char**);.
2410: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2420: 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 One-Step Query
2430: 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 Execution Interf
2440: 61 63 65 20 7b 48 31 32 31 30 30 7d 20 3c 53 31 ace {H12100} <S1
2450: 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 0000>.**.** The
2460: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 sqlite3_exec() i
2470: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f nterface is a co
2480: 6e 76 65 6e 69 65 6e 74 20 77 61 79 20 6f 66 20 nvenient way of
2490: 72 75 6e 6e 69 6e 67 20 6f 6e 65 20 6f 72 20 6d running one or m
24a0: 6f 72 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 ore.** SQL state
24b0: 6d 65 6e 74 73 20 77 69 74 68 6f 75 74 20 68 61 ments without ha
24c0: 76 69 6e 67 20 74 6f 20 77 72 69 74 65 20 61 20 ving to write a
24d0: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 20 lot of C code.
24e0: 54 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 The UTF-8 encode
24f0: 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 d.** SQL stateme
2500: 6e 74 73 20 61 72 65 20 70 61 73 73 65 64 20 69 nts are passed i
2510: 6e 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 n as the second
2520: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
2530: 69 74 65 33 5f 65 78 65 63 28 29 2e 0a 2a 2a 20 ite3_exec()..**
2540: 54 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 61 The statements a
2550: 72 65 20 65 76 61 6c 75 61 74 65 64 20 6f 6e 65 re evaluated one
2560: 20 62 79 20 6f 6e 65 20 75 6e 74 69 6c 20 65 69 by one until ei
2570: 74 68 65 72 20 61 6e 20 65 72 72 6f 72 20 6f 72 ther an error or
2580: 0a 2a 2a 20 61 6e 20 69 6e 74 65 72 72 75 70 74 .** an interrupt
2590: 20 69 73 20 65 6e 63 6f 75 6e 74 65 72 65 64 2c is encountered,
25a0: 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 79 20 61 or until they a
25b0: 72 65 20 61 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 re all done. Th
25c0: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 0a e 3rd parameter.
25d0: 2a 2a 20 69 73 20 61 6e 20 6f 70 74 69 6f 6e 61 ** is an optiona
25e0: 6c 20 63 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 l callback that
25f0: 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 is invoked once
2600: 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20 for each row of
2610: 61 6e 79 20 71 75 65 72 79 0a 2a 2a 20 72 65 73 any query.** res
2620: 75 6c 74 73 20 70 72 6f 64 75 63 65 64 20 62 79 ults produced by
2630: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
2640: 6e 74 73 2e 20 20 54 68 65 20 35 74 68 20 70 61 nts. The 5th pa
2650: 72 61 6d 65 74 65 72 20 74 65 6c 6c 73 20 77 68 rameter tells wh
2660: 65 72 65 0a 2a 2a 20 74 6f 20 77 72 69 74 65 20 ere.** to write
2670: 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 any error messag
2680: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 72 es..**.** The er
2690: 72 6f 72 20 6d 65 73 73 61 67 65 20 70 61 73 73 ror message pass
26a0: 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 ed back through
26b0: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 the 5th paramete
26c0: 72 20 69 73 20 68 65 6c 64 0a 2a 2a 20 69 6e 20 r is held.** in
26d0: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 memory obtained
26e0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 from [sqlite3_ma
26f0: 6c 6c 6f 63 28 29 5d 2e 20 20 54 6f 20 61 76 6f lloc()]. To avo
2700: 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b id a memory leak
2710: 2c 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 69 6e 67 ,.** the calling
2720: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f application sho
2730: 75 6c 64 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 uld call [sqlite
2740: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 61 6e 79 3_free()] on any
2750: 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 error.** messag
2760: 65 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 e returned throu
2770: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d gh the 5th param
2780: 65 74 65 72 20 77 68 65 6e 20 69 74 20 68 61 73 eter when it has
2790: 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 0a finished using.
27a0: 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 ** the error mes
27b0: 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 sage..**.** If t
27c0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
27d0: 20 69 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 in the 2nd para
27e0: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 6f 72 meter is NULL or
27f0: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 an empty string
2800: 0a 2a 2a 20 6f 72 20 61 20 73 74 72 69 6e 67 20 .** or a string
2810: 63 6f 6e 74 61 69 6e 69 6e 67 20 6f 6e 6c 79 20 containing only
2820: 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 20 63 whitespace and c
2830: 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f omments, then no
2840: 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e SQL.** statemen
2850: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 ts are evaluated
2860: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 and the databas
2870: 65 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 e is not changed
2880: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
2890: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 te3_exec() inter
28a0: 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e face is implemen
28b0: 74 65 64 20 69 6e 20 74 65 72 6d 73 20 6f 66 0a ted in terms of.
28c0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
28d0: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 are_v2()], [sqli
28e0: 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 te3_step()], and
28f0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
2900: 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 71 ze()]..** The sq
2910: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 72 6f 75 lite3_exec() rou
2920: 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 68 69 6e tine does nothin
2930: 67 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 g to the databas
2940: 65 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 e that cannot be
2950: 20 64 6f 6e 65 0a 2a 2a 20 62 79 20 5b 73 71 6c done.** by [sql
2960: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
2970: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 )], [sqlite3_ste
2980: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 p()], and [sqlit
2990: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a e3_finalize()]..
29a0: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
29b0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 parameter to [sq
29c0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6d 75 lite3_exec()] mu
29d0: 73 74 20 62 65 20 61 6e 20 76 61 6c 69 64 20 61 st be an valid a
29e0: 6e 64 20 6f 70 65 6e 0a 2a 2a 20 5b 64 61 74 61 nd open.** [data
29f0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
2a00: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 61 74 61 ..**.** The data
2a10: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
2a20: 6d 75 73 74 20 6e 6f 74 20 62 65 20 63 6c 6f 73 must not be clos
2a30: 65 64 20 77 68 69 6c 65 0a 2a 2a 20 5b 73 71 6c ed while.** [sql
2a40: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20 ite3_exec()] is
2a50: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 running..**.** T
2a60: 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 he calling funct
2a70: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 5b ion should use [
2a80: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 sqlite3_free()]
2a90: 74 6f 20 66 72 65 65 0a 2a 2a 20 74 68 65 20 6d to free.** the m
2aa0: 65 6d 6f 72 79 20 74 68 61 74 20 2a 65 72 72 6d emory that *errm
2ab0: 73 67 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 sg is left point
2ac0: 69 6e 67 20 61 74 20 6f 6e 63 65 20 74 68 65 20 ing at once the
2ad0: 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 error.** message
2ae0: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 is no longer ne
2af0: 65 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 eded..**.** The
2b00: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 SQL statement te
2b10: 78 74 20 69 6e 20 74 68 65 20 32 6e 64 20 70 61 xt in the 2nd pa
2b20: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
2b30: 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 6d te3_exec()].** m
2b40: 75 73 74 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 ust remain uncha
2b50: 6e 67 65 64 20 77 68 69 6c 65 20 5b 73 71 6c 69 nged while [sqli
2b60: 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 te3_exec()] is r
2b70: 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 unning..**.** Re
2b80: 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
2b90: 48 31 32 31 30 31 5d 20 5b 48 31 32 31 30 32 5d H12101] [H12102]
2ba0: 20 5b 48 31 32 31 30 34 5d 20 5b 48 31 32 31 30 [H12104] [H1210
2bb0: 35 5d 20 5b 48 31 32 31 30 37 5d 20 5b 48 31 32 5] [H12107] [H12
2bc0: 31 31 30 5d 20 5b 48 31 32 31 31 33 5d 20 5b 48 110] [H12113] [H
2bd0: 31 32 31 31 36 5d 0a 2a 2a 20 5b 48 31 32 31 31 12116].** [H1211
2be0: 39 5d 20 5b 48 31 32 31 32 32 5d 20 5b 48 31 32 9] [H12122] [H12
2bf0: 31 32 35 5d 20 5b 48 31 32 31 33 31 5d 20 5b 48 125] [H12131] [H
2c00: 31 32 31 33 34 5d 20 5b 48 31 32 31 33 37 5d 20 12134] [H12137]
2c10: 5b 48 31 32 31 33 38 5d 0a 2a 2f 0a 69 6e 74 20 [H12138].*/.int
2c20: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 sqlite3_exec(.
2c30: 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 sqlite3*,
2c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2c50: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e /* An
2c60: 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a open database *
2c70: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
2c80: 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 sql,
2c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
2ca0: 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c * SQL to be eval
2cb0: 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 uated */. int (
2cc0: 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a *callback)(void*
2cd0: 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 ,int,char**,char
2ce0: 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 **), /* Callbac
2cf0: 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 k function */.
2d00: 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 void *,
2d10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2d20: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 /* 1s
2d30: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 t argument to ca
2d40: 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 llback */. char
2d50: 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 **errmsg
2d60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2d70: 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 /* Error
2d80: 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 msg written here
2d90: 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.);../*.** CA
2da0: 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 PI3REF: Result C
2db0: 6f 64 65 73 20 7b 48 31 30 32 31 30 7d 20 3c 53 odes {H10210} <S
2dc0: 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 10700>.** KEYWOR
2dd0: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 DS: SQLITE_OK {e
2de0: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f rror code} {erro
2df0: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 r codes}.** KEYW
2e00: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f ORDS: {result co
2e10: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 de} {result code
2e20: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 s}.**.** Many SQ
2e30: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 Lite functions r
2e40: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 eturn an integer
2e50: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f result code fro
2e60: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a m the set shown.
2e70: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72 ** here in order
2e80: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75 to indicates su
2e90: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 ccess or failure
2ea0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f ..**.** New erro
2eb0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 r codes may be a
2ec0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 dded in future v
2ed0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
2ee0: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 e..**.** See als
2ef0: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 o: [SQLITE_IOERR
2f00: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 _READ | extended
2f10: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a result codes].*
2f20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
2f30: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 _OK 0
2f40: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 /* Successful
2f50: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 result */./* beg
2f60: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d inning-of-error-
2f70: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 codes */.#define
2f80: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 SQLITE_ERROR
2f90: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 1 /* SQL
2fa0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 error or missing
2fb0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 database */.#de
2fc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 fine SQLITE_INTE
2fd0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 RNAL 2 /*
2fe0: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 Internal logic e
2ff0: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a rror in SQLite *
3000: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
3010: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 _PERM 3
3020: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d /* Access perm
3030: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f ission denied */
3040: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3050: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 ABORT 4
3060: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 /* Callback rou
3070: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 tine requested a
3080: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 n abort */.#defi
3090: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 ne SQLITE_BUSY
30a0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 5 /* Th
30b0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
30c0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 is locked */.#de
30d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b fine SQLITE_LOCK
30e0: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 ED 6 /*
30f0: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 A table in the d
3100: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 atabase is locke
3110: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
3120: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 ITE_NOMEM
3130: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 7 /* A malloc
3140: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 () failed */.#de
3150: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 fine SQLITE_READ
3160: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 ONLY 8 /*
3170: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 Attempt to write
3180: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 a readonly data
3190: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 base */.#define
31a0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 SQLITE_INTERRUPT
31b0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 9 /* Opera
31c0: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 tion terminated
31d0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 by sqlite3_inter
31e0: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 rupt()*/.#define
31f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 SQLITE_IOERR
3200: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 10 /* Some
3210: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f kind of disk I/
3220: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 O error occurred
3230: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
3240: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 TE_CORRUPT 1
3250: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 1 /* The datab
3260: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 ase disk image i
3270: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 s malformed */.#
3280: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f define SQLITE_NO
3290: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f TFOUND 12 /
32a0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c * NOT USED. Tabl
32b0: 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20 e or record not
32c0: 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65 found */.#define
32d0: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 SQLITE_FULL
32e0: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 13 /* Inse
32f0: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 rtion failed bec
3300: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73 ause database is
3310: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 full */.#define
3320: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e SQLITE_CANTOPEN
3330: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 14 /* Unab
3340: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 le to open the d
3350: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a atabase file */.
3360: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 #define SQLITE_P
3370: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 ROTOCOL 15
3380: 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 44 61 74 /* NOT USED. Dat
3390: 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f abase lock proto
33a0: 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 col error */.#de
33b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 fine SQLITE_EMPT
33c0: 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 Y 16 /*
33d0: 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 Database is empt
33e0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
33f0: 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 ITE_SCHEMA
3400: 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 17 /* The data
3410: 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e base schema chan
3420: 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ged */.#define S
3430: 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 QLITE_TOOBIG
3440: 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 18 /* String
3450: 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 or BLOB exceeds
3460: 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 size limit */.#
3470: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
3480: 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f NSTRAINT 19 /
3490: 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 * Abort due to c
34a0: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 onstraint violat
34b0: 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ion */.#define S
34c0: 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 QLITE_MISMATCH
34d0: 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 20 /* Data t
34e0: 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a ype mismatch */.
34f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d #define SQLITE_M
3500: 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20 ISUSE 21
3510: 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 /* Library used
3520: 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 incorrectly */.#
3530: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f define SQLITE_NO
3540: 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f LFS 22 /
3550: 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 * Uses OS featur
3560: 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 es not supported
3570: 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 on host */.#def
3580: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 ine SQLITE_AUTH
3590: 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 23 /* A
35a0: 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e uthorization den
35b0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ied */.#define S
35c0: 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 QLITE_FORMAT
35d0: 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 24 /* Auxili
35e0: 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 ary database for
35f0: 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 mat error */.#de
3600: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 fine SQLITE_RANG
3610: 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 E 25 /*
3620: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 2nd parameter to
3630: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 sqlite3_bind ou
3640: 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 t of range */.#d
3650: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 efine SQLITE_NOT
3660: 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a ADB 26 /*
3670: 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 File opened tha
3680: 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 t is not a datab
3690: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 ase file */.#def
36a0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 ine SQLITE_ROW
36b0: 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 100 /* s
36c0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 qlite3_step() ha
36d0: 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 s another row re
36e0: 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ady */.#define S
36f0: 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 QLITE_DONE
3700: 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 101 /* sqlite
3710: 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 3_step() has fin
3720: 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 ished executing
3730: 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 */./* end-of-err
3740: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a or-codes */../*.
3750: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 ** CAPI3REF: Ext
3760: 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 ended Result Cod
3770: 65 73 20 7b 48 31 30 32 32 30 7d 20 3c 53 31 30 es {H10220} <S10
3780: 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 700>.** KEYWORDS
3790: 3a 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f : {extended erro
37a0: 72 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 r code} {extende
37b0: 64 20 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a d error codes}.*
37c0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 * KEYWORDS: {ext
37d0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
37e0: 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 e} {extended res
37f0: 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a ult codes}.**.**
3800: 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 In its default
3810: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 configuration, S
3820: 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e QLite API routin
3830: 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 es return one of
3840: 20 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 26 integer.** [
3850: 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 SQLITE_OK | resu
3860: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 lt codes]. Howe
3870: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 ver, experience
3880: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d has shown that m
3890: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 any of.** these
38a0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 result codes are
38b0: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 too coarse-grai
38c0: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f ned. They do no
38d0: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 t provide as.**
38e0: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e much information
38f0: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 about problems
3900: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d as programmers m
3910: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 ight like. In a
3920: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 n effort to.** a
3930: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 ddress this, new
3940: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 er versions of S
3950: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 QLite (version 3
3960: 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 .3.8 and later)
3970: 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f include.** suppo
3980: 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 rt for additiona
3990: 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 l result codes t
39a0: 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 hat provide more
39b0: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d detailed inform
39c0: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 ation.** about e
39d0: 72 72 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e rrors. The exten
39e0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
39f0: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 are enabled or
3a00: 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 disabled.** on a
3a10: 20 70 65 72 20 64 61 74 61 62 61 73 65 20 63 6f per database co
3a20: 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 nnection basis u
3a30: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c sing the.** [sql
3a40: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 ite3_extended_re
3a50: 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 sult_codes()] AP
3a60: 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 I..**.** Some of
3a70: 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65 the available e
3a80: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
3a90: 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65 64 20 odes are listed
3aa0: 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 here..** One may
3ab0: 20 65 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 expect the numb
3ac0: 65 72 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 er of extended r
3ad0: 65 73 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c esult codes will
3ae0: 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 be expand.** ov
3af0: 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 er time. Softwa
3b00: 72 65 20 74 68 61 74 20 75 73 65 73 20 65 78 74 re that uses ext
3b10: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
3b20: 65 73 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74 es should expect
3b30: 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72 .** to see new r
3b40: 65 73 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 esult codes in f
3b50: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f uture releases o
3b60: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 f SQLite..**.**
3b70: 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 The SQLITE_OK re
3b80: 73 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e sult code will n
3b90: 65 76 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 ever be extended
3ba0: 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 . It will alway
3bb0: 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 s.** be exactly
3bc0: 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 zero..*/.#define
3bd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 SQLITE_IOERR_RE
3be0: 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 AD
3bf0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
3c00: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (1<<8)).#define
3c10: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f SQLITE_IOERR_SHO
3c20: 52 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 RT_READ (
3c30: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
3c40: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 2<<8)).#define S
3c50: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 QLITE_IOERR_WRIT
3c60: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 E (S
3c70: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 QLITE_IOERR | (3
3c80: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
3c90: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 LITE_IOERR_FSYNC
3ca0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
3cb0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c LITE_IOERR | (4<
3cc0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
3cd0: 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 ITE_IOERR_DIR_FS
3ce0: 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c YNC (SQL
3cf0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c ITE_IOERR | (5<<
3d00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
3d10: 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 TE_IOERR_TRUNCAT
3d20: 45 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 E (SQLI
3d30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 TE_IOERR | (6<<8
3d40: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
3d50: 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 E_IOERR_FSTAT
3d60: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
3d70: 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 E_IOERR | (7<<8)
3d80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
3d90: 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 _IOERR_UNLOCK
3da0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
3db0: 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 _IOERR | (8<<8))
3dc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3dd0: 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 IOERR_RDLOCK
3de0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
3df0: 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a IOERR | (9<<8)).
3e00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
3e10: 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 OERR_DELETE
3e20: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
3e30: 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a OERR | (10<<8)).
3e40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
3e50: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 OERR_BLOCKED
3e60: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
3e70: 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a OERR | (11<<8)).
3e80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
3e90: 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 OERR_NOMEM
3ea0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
3eb0: 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a OERR | (12<<8)).
3ec0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
3ed0: 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 OERR_ACCESS
3ee0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
3ef0: 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a OERR | (13<<8)).
3f00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
3f10: 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 OERR_CHECKRESERV
3f20: 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 EDLOCK (SQLITE_I
3f30: 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a OERR | (14<<8)).
3f40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
3f50: 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 OERR_LOCK
3f60: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
3f70: 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a OERR | (15<<8)).
3f80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
3f90: 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 OERR_CLOSE
3fa0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
3fb0: 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a OERR | (16<<8)).
3fc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
3fd0: 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 OERR_DIR_CLOSE
3fe0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
3ff0: 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a OERR | (17<<8)).
4000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
4010: 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 OCKED_SHAREDCACH
4020: 45 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c E (SQLITE_L
4030: 4f 43 4b 45 44 20 7c 20 28 31 3c 3c 38 29 20 29 OCKED | (1<<8) )
4040: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
4050: 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 : Flags For File
4060: 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 Open Operations
4070: 20 7b 48 31 30 32 33 30 7d 20 3c 48 31 31 31 32 {H10230} <H1112
4080: 30 3e 20 3c 48 31 32 37 30 30 3e 0a 2a 2a 0a 2a 0> <H12700>.**.*
4090: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 * These bit valu
40a0: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 es are intended
40b0: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a for use in the.*
40c0: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 * 3rd parameter
40d0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
40e0: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 open_v2()] inter
40f0: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 face and.** in t
4100: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 he 4th parameter
4110: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 to the xOpen me
4120: 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b thod of the.** [
4130: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a sqlite3_vfs] obj
4140: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ect..*/.#define
4150: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
4160: 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 ONLY 0x0
4170: 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 0000001 /* Ok f
4180: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f or sqlite3_open_
4190: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 v2() */.#define
41a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
41b0: 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 WRITE 0x0
41c0: 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 0000002 /* Ok f
41d0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f or sqlite3_open_
41e0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 v2() */.#define
41f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 SQLITE_OPEN_CREA
4200: 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 TE 0x0
4210: 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 0000004 /* Ok f
4220: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f or sqlite3_open_
4230: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 v2() */.#define
4240: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 SQLITE_OPEN_DELE
4250: 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 TEONCLOSE 0x0
4260: 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 0000008 /* VFS
4270: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 only */.#define
4280: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c SQLITE_OPEN_EXCL
4290: 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 USIVE 0x0
42a0: 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 0000010 /* VFS
42b0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 only */.#define
42c0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e SQLITE_OPEN_MAIN
42d0: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 _DB 0x0
42e0: 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 0000100 /* VFS
42f0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 only */.#define
4300: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 SQLITE_OPEN_TEMP
4310: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 _DB 0x0
4320: 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 0000200 /* VFS
4330: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 only */.#define
4340: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e SQLITE_OPEN_TRAN
4350: 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 SIENT_DB 0x0
4360: 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 0000400 /* VFS
4370: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 only */.#define
4380: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e SQLITE_OPEN_MAIN
4390: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 _JOURNAL 0x0
43a0: 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 0000800 /* VFS
43b0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 only */.#define
43c0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 SQLITE_OPEN_TEMP
43d0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 _JOURNAL 0x0
43e0: 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 0001000 /* VFS
43f0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 only */.#define
4400: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a SQLITE_OPEN_SUBJ
4410: 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 OURNAL 0x0
4420: 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 0002000 /* VFS
4430: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 only */.#define
4440: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 SQLITE_OPEN_MAST
4450: 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 ER_JOURNAL 0x0
4460: 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 0004000 /* VFS
4470: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 only */.#define
4480: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 SQLITE_OPEN_NOMU
4490: 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 TEX 0x0
44a0: 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 0008000 /* Ok f
44b0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f or sqlite3_open_
44c0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 v2() */.#define
44d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c SQLITE_OPEN_FULL
44e0: 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 MUTEX 0x0
44f0: 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 0010000 /* Ok f
4500: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f or sqlite3_open_
4510: 76 32 28 29 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 v2() */../*.** C
4520: 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 API3REF: Device
4530: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 Characteristics
4540: 7b 48 31 30 32 34 30 7d 20 3c 48 31 31 31 32 30 {H10240} <H11120
4550: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 >.**.** The xDev
4560: 69 63 65 43 61 70 61 62 69 6c 69 74 69 65 73 20 iceCapabilities
4570: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 method of the [s
4580: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
4590: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 s].** object ret
45a0: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 urns an integer
45b0: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f which is a vecto
45c0: 72 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a r of the these.*
45d0: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 * bit values exp
45e0: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 ressing I/O char
45f0: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 acteristics of t
4600: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a he mass storage.
4610: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 ** device that h
4620: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 olds the file th
4630: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f at the [sqlite3_
4640: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 io_methods].** r
4650: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 efers to..**.**
4660: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
4670: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 _ATOMIC property
4680: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 means that all
4690: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 writes of.** any
46a0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 size are atomic
46b0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
46c0: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 CAP_ATOMICnnn va
46d0: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 lues.** mean tha
46e0: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 t writes of bloc
46f0: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 ks that are nnn
4700: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e bytes in size an
4710: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 d.** are aligned
4720: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 to an address w
4730: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 hich is an integ
4740: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a er multiple of.*
4750: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 * nnn are atomic
4760: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
4770: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 CAP_SAFE_APPEND
4780: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 value means.** t
4790: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 hat when data is
47a0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 appended to a f
47b0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 ile, the data is
47c0: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 appended.** fir
47d0: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 st then the size
47e0: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 of the file is
47f0: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 extended, never
4800: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 the other.** way
4810: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 around. The SQ
4820: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 LITE_IOCAP_SEQUE
4830: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d NTIAL property m
4840: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 eans that.** inf
4850: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 ormation is writ
4860: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 ten to disk in t
4870: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 he same order as
4880: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 calls.** to xWr
4890: 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e ite()..*/.#defin
48a0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
48b0: 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 30 TOMIC 0
48c0: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e x00000001.#defin
48d0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
48e0: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 30 TOMIC512 0
48f0: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e x00000002.#defin
4900: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
4910: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 30 TOMIC1K 0
4920: 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e x00000004.#defin
4930: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
4940: 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 30 TOMIC2K 0
4950: 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e x00000008.#defin
4960: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
4970: 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 30 TOMIC4K 0
4980: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e x00000010.#defin
4990: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
49a0: 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 30 TOMIC8K 0
49b0: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e x00000020.#defin
49c0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
49d0: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 30 TOMIC16K 0
49e0: 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e x00000040.#defin
49f0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
4a00: 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 30 TOMIC32K 0
4a10: 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e x00000080.#defin
4a20: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
4a30: 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 30 TOMIC64K 0
4a40: 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e x00000100.#defin
4a50: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 e SQLITE_IOCAP_S
4a60: 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 30 AFE_APPEND 0
4a70: 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e x00000200.#defin
4a80: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 e SQLITE_IOCAP_S
4a90: 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 30 EQUENTIAL 0
4aa0: 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a x00000400../*.**
4ab0: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 CAPI3REF: File
4ac0: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b Locking Levels {
4ad0: 48 31 30 32 35 30 7d 20 3c 48 31 31 31 32 30 3e H10250} <H11120>
4ae0: 20 3c 48 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a 20 <H11310>.**.**
4af0: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 SQLite uses one
4b00: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 of these integer
4b10: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 values as the s
4b20: 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e econd.** argumen
4b30: 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 t to calls it ma
4b40: 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b kes to the xLock
4b50: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 () and xUnlock()
4b60: 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 methods.** of a
4b70: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 n [sqlite3_io_me
4b80: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a thods] object..*
4b90: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4ba0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 _LOCK_NONE
4bb0: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 0.#define SQ
4bc0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 LITE_LOCK_SHARED
4bd0: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 1.#defin
4be0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 e SQLITE_LOCK_RE
4bf0: 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 SERVED 2.#d
4c00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 efine SQLITE_LOC
4c10: 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 K_PENDING
4c20: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 3.#define SQLITE
4c30: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 _LOCK_EXCLUSIVE
4c40: 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 4../*.** CAP
4c50: 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 I3REF: Synchroni
4c60: 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 zation Type Flag
4c70: 73 20 7b 48 31 30 32 36 30 7d 20 3c 48 31 31 31 s {H10260} <H111
4c80: 32 30 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 20>.**.** When S
4c90: 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 QLite invokes th
4ca0: 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 e xSync() method
4cb0: 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 of an.** [sqlit
4cc0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f e3_io_methods] o
4cd0: 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20 bject it uses a
4ce0: 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a combination of.*
4cf0: 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 * these integer
4d00: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 values as the se
4d10: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a cond argument..*
4d20: 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 *.** When the SQ
4d30: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e LITE_SYNC_DATAON
4d40: 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c LY flag is used,
4d50: 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 it means that t
4d60: 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 he.** sync opera
4d70: 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 tion only needs
4d80: 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f to flush data to
4d90: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 mass storage.
4da0: 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 Inode.** informa
4db0: 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 tion need not be
4dc0: 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 flushed. If the
4dd0: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 lower four bits
4de0: 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 of the flag.**
4df0: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e equal SQLITE_SYN
4e00: 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d C_NORMAL, that m
4e10: 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d eans to use norm
4e20: 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e al fsync() seman
4e30: 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 tics..** If the
4e40: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 lower four bits
4e50: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e equal SQLITE_SYN
4e60: 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 C_FULL, that mea
4e70: 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 ns.** to use Mac
4e80: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c OS X style full
4e90: 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 sync instead of
4ea0: 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 66 fsync()..*/.#def
4eb0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f ine SQLITE_SYNC_
4ec0: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 NORMAL 0x
4ed0: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 00002.#define SQ
4ee0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 LITE_SYNC_FULL
4ef0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 0x00003.
4f00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
4f10: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 YNC_DATAONLY
4f20: 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 0x00010../*.**
4f30: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e CAPI3REF: OS In
4f40: 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c terface Open Fil
4f50: 65 20 48 61 6e 64 6c 65 20 7b 48 31 31 31 31 30 e Handle {H11110
4f60: 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a } <S20110>.**.**
4f70: 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c An [sqlite3_fil
4f80: 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 e] object repres
4f90: 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c ents an open fil
4fa0: 65 20 69 6e 20 74 68 65 20 4f 53 0a 2a 2a 20 69 e in the OS.** i
4fb0: 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 2e 20 nterface layer.
4fc0: 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 Individual OS i
4fd0: 6e 74 65 72 66 61 63 65 20 69 6d 70 6c 65 6d 65 nterface impleme
4fe0: 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a ntations will.**
4ff0: 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 want to subclas
5000: 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 s this object by
5010: 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 appending addit
5020: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 ional fields.**
5030: 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 for their own us
5040: 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 e. The pMethods
5050: 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e entry is a poin
5060: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 ter to an.** [sq
5070: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
5080: 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 ] object that de
5090: 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f fines methods fo
50a0: 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 r performing.**
50b0: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f I/O operations o
50c0: 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e n the open file.
50d0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
50e0: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 ct sqlite3_file
50f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 sqlite3_file;.st
5100: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c ruct sqlite3_fil
5110: 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 e {. const stru
5120: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 ct sqlite3_io_me
5130: 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b thods *pMethods;
5140: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 /* Methods for
5150: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f an open file */
5160: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .};../*.** CAPI3
5170: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 REF: OS Interfac
5180: 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d e File Virtual M
5190: 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 20 7b 48 ethods Object {H
51a0: 31 31 31 32 30 7d 20 3c 53 32 30 31 31 30 3e 0a 11120} <S20110>.
51b0: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 **.** Every file
51c0: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b opened by the [
51d0: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 sqlite3_vfs] xOp
51e0: 65 6e 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 en method popula
51f0: 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 tes an.** [sqlit
5200: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 e3_file] object
5210: 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e (or, more common
5220: 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f ly, a subclass o
5230: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 f the.** [sqlite
5240: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 3_file] object)
5250: 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 with a pointer t
5260: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 o an instance of
5270: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a this object..**
5280: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 This object def
5290: 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 ines the methods
52a0: 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d used to perform
52b0: 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 various operati
52c0: 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 ons.** against t
52d0: 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 he open file rep
52e0: 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 resented by the
52f0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f [sqlite3_file] o
5300: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 bject..**.** The
5310: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 flags argument
5320: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 to xSync may be
5330: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 one of [SQLITE_S
5340: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a YNC_NORMAL] or.*
5350: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 * [SQLITE_SYNC_F
5360: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 ULL]. The first
5370: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e choice is the n
5380: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a ormal fsync()..*
5390: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f * The second cho
53a0: 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 ice is a Mac OS
53b0: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 X style fullsync
53c0: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 . The [SQLITE_S
53d0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a YNC_DATAONLY].**
53e0: 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 flag may be ORe
53f0: 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 d in to indicate
5400: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 that only the d
5410: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a ata of the file.
5420: 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 ** and not its i
5430: 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 node needs to be
5440: 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 synced..**.** T
5450: 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 he integer value
5460: 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 s to xLock() and
5470: 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f xUnlock() are o
5480: 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a ne of.** <ul>.**
5490: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f <li> [SQLITE_LO
54a0: 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 CK_NONE],.** <li
54b0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 > [SQLITE_LOCK_S
54c0: 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 HARED],.** <li>
54d0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 [SQLITE_LOCK_RES
54e0: 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 ERVED],.** <li>
54f0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e [SQLITE_LOCK_PEN
5500: 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 DING], or.** <li
5510: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 > [SQLITE_LOCK_E
5520: 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f XCLUSIVE]..** </
5530: 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 ul>.** xLock() i
5540: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 ncreases the loc
5550: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 k. xUnlock() dec
5560: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e reases the lock.
5570: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 .** The xCheckRe
5580: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 servedLock() met
5590: 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 hod checks wheth
55a0: 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 er any database
55b0: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 connection,.** e
55c0: 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 ither in this pr
55d0: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 ocess or in some
55e0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 other process,
55f0: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 is holding a RES
5600: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e ERVED,.** PENDIN
5610: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 G, or EXCLUSIVE
5620: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 lock on the file
5630: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 . It returns tr
5640: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 ue.** if such a
5650: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 lock exists and
5660: 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e false otherwise.
5670: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 .**.** The xFile
5680: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 Control() method
5690: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e is a generic in
56a0: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c terface that all
56b0: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 ows custom.** VF
56c0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e S implementation
56d0: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f s to directly co
56e0: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 ntrol an open fi
56f0: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 le using the.**
5700: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
5710: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 ntrol()] interfa
5720: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 ce. The second
5730: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 "op" argument is
5740: 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f an.** integer o
5750: 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 pcode. The thir
5760: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 d argument is a
5770: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 generic pointer
5780: 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 intended to.** p
5790: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 oint to a struct
57a0: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e ure that may con
57b0: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f tain arguments o
57c0: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 r space in which
57d0: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 to.** write ret
57e0: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 urn values. Pot
57f0: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 ential uses for
5800: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d xFileControl() m
5810: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 ight be.** funct
5820: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 ions to enable b
5830: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 locking locks wi
5840: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 th timeouts, to
5850: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f change the.** lo
5860: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 cking strategy (
5870: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 for example to u
5880: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b se dot-file lock
5890: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a s), to inquire.*
58a0: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 * about the stat
58b0: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 us of a lock, or
58c0: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 to break stale
58d0: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 locks. The SQLi
58e0: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 te.** core reser
58f0: 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 ves all opcodes
5900: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f less than 100 fo
5910: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a r its own use..*
5920: 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 * A [SQLITE_FCNT
5930: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 L_LOCKSTATE | li
5940: 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c st of opcodes] l
5950: 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 ess than 100 is
5960: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 available..** Ap
5970: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 plications that
5980: 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 define a custom
5990: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 xFileControl met
59a0: 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f hod should use o
59b0: 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 pcodes.** greate
59c0: 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 r than 100 to av
59d0: 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a oid conflicts..*
59e0: 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 *.** The xSector
59f0: 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 Size() method re
5a00: 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 turns the sector
5a10: 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 size of the.**
5a20: 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 device that unde
5a30: 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 rlies the file.
5a40: 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 The sector size
5a50: 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d is the.** minim
5a60: 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 um write that ca
5a70: 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 n be performed w
5a80: 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e ithout disturbin
5a90: 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 g.** other bytes
5aa0: 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 in the file. T
5ab0: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 he xDeviceCharac
5ac0: 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d teristics().** m
5ad0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 ethod returns a
5ae0: 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 bit vector descr
5af0: 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 ibing behaviors
5b00: 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c of the.** underl
5b10: 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a ying device:.**.
5b20: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
5b30: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
5b40: 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 OMIC].** <li> [S
5b50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
5b60: 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b IC512].** <li> [
5b70: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
5b80: 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b MIC1K].** <li> [
5b90: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
5ba0: 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b MIC2K].** <li> [
5bb0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
5bc0: 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b MIC4K].** <li> [
5bd0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
5be0: 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b MIC8K].** <li> [
5bf0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
5c00: 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 MIC16K].** <li>
5c10: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
5c20: 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e OMIC32K].** <li>
5c30: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
5c40: 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 TOMIC64K].** <li
5c50: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
5c60: 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 SAFE_APPEND].**
5c70: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
5c80: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a AP_SEQUENTIAL].*
5c90: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 * </ul>.**.** Th
5ca0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
5cb0: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d TOMIC property m
5cc0: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 eans that all wr
5cd0: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 ites of.** any s
5ce0: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 ize are atomic.
5cf0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
5d00: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 P_ATOMICnnn valu
5d10: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 es.** mean that
5d20: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 writes of blocks
5d30: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 that are nnn by
5d40: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a tes in size and.
5d50: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 ** are aligned t
5d60: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 o an address whi
5d70: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 ch is an integer
5d80: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 multiple of.**
5d90: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 nnn are atomic.
5da0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
5db0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 P_SAFE_APPEND va
5dc0: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 lue means.** tha
5dd0: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 t when data is a
5de0: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c ppended to a fil
5df0: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 e, the data is a
5e00: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 ppended.** first
5e10: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f then the size o
5e20: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 f the file is ex
5e30: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 tended, never th
5e40: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 e other.** way a
5e50: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 round. The SQLI
5e60: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 TE_IOCAP_SEQUENT
5e70: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 IAL property mea
5e80: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 ns that.** infor
5e90: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 mation is writte
5ea0: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 n to disk in the
5eb0: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 same order as c
5ec0: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 alls.** to xWrit
5ed0: 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 e()..**.** If xR
5ee0: 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 ead() returns SQ
5ef0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 LITE_IOERR_SHORT
5f00: 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c _READ it must al
5f10: 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 so fill.** in th
5f20: 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e e unread portion
5f30: 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 s of the buffer
5f40: 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 with zeros. A V
5f50: 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 FS that.** fails
5f60: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 to zero-fill sh
5f70: 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 ort reads might
5f80: 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 seem to work. H
5f90: 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 owever,.** failu
5fa0: 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 re to zero-fill
5fb0: 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c short reads will
5fc0: 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 eventually lead
5fd0: 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 to.** database
5fe0: 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 corruption..*/.t
5ff0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
6000: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
6010: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 sqlite3_io_meth
6020: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 ods;.struct sqli
6030: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b te3_io_methods {
6040: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b . int iVersion;
6050: 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 . int (*xClose)
6060: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b (sqlite3_file*);
6070: 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 . int (*xRead)(
6080: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 sqlite3_file*, v
6090: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 oid*, int iAmt,
60a0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f sqlite3_int64 iO
60b0: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 fst);. int (*xW
60c0: 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 rite)(sqlite3_fi
60d0: 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a le*, const void*
60e0: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 , int iAmt, sqli
60f0: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 te3_int64 iOfst)
6100: 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 ;. int (*xTrunc
6110: 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ate)(sqlite3_fil
6120: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 e*, sqlite3_int6
6130: 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 4 size);. int (
6140: 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f *xSync)(sqlite3_
6150: 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 file*, int flags
6160: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 );. int (*xFile
6170: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 Size)(sqlite3_fi
6180: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 le*, sqlite3_int
6190: 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 64 *pSize);. in
61a0: 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 t (*xLock)(sqlit
61b0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a e3_file*, int);.
61c0: 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 int (*xUnlock)
61d0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
61e0: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 int);. int (*xC
61f0: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b heckReservedLock
6200: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
6210: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a int *pResOut);.
6220: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e int (*xFileCon
6230: 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 trol)(sqlite3_fi
6240: 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 le*, int op, voi
6250: 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 d *pArg);. int
6260: 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 (*xSectorSize)(s
6270: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 qlite3_file*);.
6280: 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 int (*xDeviceCh
6290: 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 aracteristics)(s
62a0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 qlite3_file*);.
62b0: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d /* Additional m
62c0: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 ethods may be ad
62d0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
62e0: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a leases */.};../*
62f0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 .** CAPI3REF: St
6300: 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 andard File Cont
6310: 72 6f 6c 20 4f 70 63 6f 64 65 73 20 7b 48 31 31 rol Opcodes {H11
6320: 33 31 30 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 310} <S30800>.**
6330: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 .** These intege
6340: 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 r constants are
6350: 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 opcodes for the
6360: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 xFileControl met
6370: 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 hod.** of the [s
6380: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
6390: 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f s] object and fo
63a0: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 r the [sqlite3_f
63b0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a ile_control()].*
63c0: 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a * interface..**.
63d0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ** The [SQLITE_F
63e0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 CNTL_LOCKSTATE]
63f0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 opcode is used f
6400: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 or debugging. T
6410: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 his.** opcode ca
6420: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f uses the xFileCo
6430: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 ntrol method to
6440: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e write the curren
6450: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 t state of.** th
6460: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b e lock (one of [
6470: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 SQLITE_LOCK_NONE
6480: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f ], [SQLITE_LOCK_
6490: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c SHARED],.** [SQL
64a0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 ITE_LOCK_RESERVE
64b0: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b D], [SQLITE_LOCK
64c0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 _PENDING], or [S
64d0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 QLITE_LOCK_EXCLU
64e0: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 SIVE]).** into a
64f0: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 n integer that t
6500: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 he pArg argument
6510: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 points to. This
6520: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 capability.** i
6530: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 s used during te
6540: 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e sting and only n
6550: 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f eeds to be suppo
6560: 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 rted when SQLITE
6570: 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 _TEST.** is defi
6580: 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ned..*/.#define
6590: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 SQLITE_FCNTL_LOC
65a0: 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 31 0a KSTATE 1.
65b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 #define SQLITE_G
65c0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 ET_LOCKPROXYFILE
65d0: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 2.#define
65e0: 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 SQLITE_SET_LOCKP
65f0: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 33 0a ROXYFILE 3.
6600: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
6610: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 AST_ERRNO
6620: 20 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 4../*.** C
6630: 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 API3REF: Mutex H
6640: 61 6e 64 6c 65 20 7b 48 31 37 31 31 30 7d 20 3c andle {H17110} <
6650: 53 32 30 31 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S20130>.**.** Th
6660: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 e mutex module w
6670: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 ithin SQLite def
6680: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 ines [sqlite3_mu
6690: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a tex] to be an.**
66a0: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 abstract type f
66b0: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 or a mutex objec
66c0: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 t. The SQLite c
66d0: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a ore never looks.
66e0: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e ** at the intern
66f0: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f al representatio
6700: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 n of an [sqlite3
6710: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c _mutex]. It onl
6720: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 y.** deals with
6730: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 pointers to the
6740: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 [sqlite3_mutex]
6750: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 object..**.** Mu
6760: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 texes are create
6770: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
6780: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e _mutex_alloc()].
6790: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
67a0: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 ct sqlite3_mutex
67b0: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a sqlite3_mutex;.
67c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
67d0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 OS Interface Ob
67e0: 6a 65 63 74 20 7b 48 31 31 31 34 30 7d 20 3c 53 ject {H11140} <S
67f0: 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 20100>.**.** An
6800: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 instance of the
6810: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 sqlite3_vfs obje
6820: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 ct defines the i
6830: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e nterface between
6840: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 .** the SQLite c
6850: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 ore and the unde
6860: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 rlying operating
6870: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 system. The "v
6880: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 fs".** in the na
6890: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 me of the object
68a0: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 stands for "vir
68b0: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d tual file system
68c0: 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c "..**.** The val
68d0: 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 ue of the iVersi
68e0: 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 on field is init
68f0: 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 ially 1 but may
6900: 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 be larger in.**
6910: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 future versions
6920: 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 of SQLite. Addi
6930: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 tional fields ma
6940: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f y be appended to
6950: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 this.** object
6960: 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f when the iVersio
6970: 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 n value is incre
6980: 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 ased. Note that
6990: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a the structure.*
69a0: 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 * of the sqlite3
69b0: 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e _vfs object chan
69c0: 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 ges in the trans
69d0: 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a action between.*
69e0: 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e * SQLite version
69f0: 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 3.5.9 and 3.6.0
6a00: 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 and yet the iVe
6a10: 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 rsion field was
6a20: 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e not.** modified.
6a30: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 .**.** The szOsF
6a40: 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 ile field is the
6a50: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 size of the sub
6a60: 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 classed [sqlite3
6a70: 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 _file].** struct
6a80: 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 ure used by this
6a90: 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d VFS. mxPathnam
6aa0: 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d e is the maximum
6ab0: 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 length of.** a
6ac0: 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 pathname in this
6ad0: 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 VFS..**.** Regi
6ae0: 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 stered sqlite3_v
6af0: 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b fs objects are k
6b00: 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 ept on a linked
6b10: 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a list formed by.*
6b20: 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e * the pNext poin
6b30: 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 ter. The [sqlit
6b40: 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 e3_vfs_register(
6b50: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 )].** and [sqlit
6b60: 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 e3_vfs_unregiste
6b70: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 r()] interfaces
6b80: 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 manage this list
6b90: 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d .** in a thread-
6ba0: 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b safe way. The [
6bb0: 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 sqlite3_vfs_find
6bc0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a ()] interface.**
6bd0: 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 searches the li
6be0: 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 st. Neither the
6bf0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 application cod
6c00: 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a e nor the VFS.**
6c10: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
6c20: 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 should use the p
6c30: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a Next pointer..**
6c40: 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 .** The pNext fi
6c50: 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 eld is the only
6c60: 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c field in the sql
6c70: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 ite3_vfs.** stru
6c80: 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 cture that SQLit
6c90: 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 e will ever modi
6ca0: 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c fy. SQLite will
6cb0: 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 only access.**
6cc0: 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 or modify this f
6cd0: 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 ield while holdi
6ce0: 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 ng a particular
6cf0: 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a static mutex..**
6d00: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
6d10: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f should never mo
6d20: 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 dify anything wi
6d30: 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 thin the sqlite3
6d40: 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f _vfs.** object o
6d50: 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 nce the object h
6d60: 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 as been register
6d70: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e ed..**.** The zN
6d80: 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 ame field holds
6d90: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
6da0: 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 VFS module. The
6db0: 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 name must.** be
6dc0: 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 unique across a
6dd0: 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a ll VFS modules..
6de0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c **.** SQLite wil
6df0: 6c 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 l guarantee that
6e00: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 the zFilename p
6e10: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 arameter to xOpe
6e20: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 n.** is either a
6e30: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 NULL pointer or
6e40: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 string obtained
6e50: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 .** from xFullPa
6e60: 74 68 6e 61 6d 65 28 29 2e 20 20 53 51 4c 69 74 thname(). SQLit
6e70: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e e further guaran
6e80: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 tees that.** the
6e90: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 string will be
6ea0: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e valid and unchan
6eb0: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 ged until xClose
6ec0: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e () is.** called.
6ed0: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 Because of the
6ee0: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 73 previous sentens
6ef0: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 e,.** the [sqlit
6f00: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 e3_file] can saf
6f10: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e ely store a poin
6f20: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 ter to the.** fi
6f30: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 lename if it nee
6f40: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 ds to remember t
6f50: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 he filename for
6f60: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 some reason..**
6f70: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 If the zFilename
6f80: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 78 4f parameter is xO
6f90: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f pen is a NULL po
6fa0: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e inter then xOpen
6fb0: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 69 74 65 20 .** must invite
6fc0: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 its own temporar
6fd0: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 y name for the f
6fe0: 69 6c 65 2e 20 20 57 68 65 6e 65 76 65 72 20 74 ile. Whenever t
6ff0: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 he .** xFilename
7000: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 parameter is NU
7010: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 LL it will also
7020: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 be the case that
7030: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 the.** flags pa
7040: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 rameter will inc
7050: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 lude [SQLITE_OPE
7060: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d N_DELETEONCLOSE]
7070: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 ..**.** The flag
7080: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f s argument to xO
7090: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 pen() includes a
70a0: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a ll bits set in.*
70b0: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 * the flags argu
70c0: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 ment to [sqlite3
70d0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 _open_v2()]. Or
70e0: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 if [sqlite3_ope
70f0: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 n()].** or [sqli
7100: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 te3_open16()] is
7110: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 used, then flag
7120: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 s includes at le
7130: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f ast.** [SQLITE_O
7140: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c PEN_READWRITE] |
7150: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 [SQLITE_OPEN_CR
7160: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f EATE]. .** If xO
7170: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 pen() opens a fi
7180: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 le read-only the
7190: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 n it sets *pOutF
71a0: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 lags to.** inclu
71b0: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f de [SQLITE_OPEN_
71c0: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 READONLY]. Othe
71d0: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 r bits in *pOutF
71e0: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e lags may be set.
71f0: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 .**.** SQLite wi
7200: 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 ll also add one
7210: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 of the following
7220: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f flags to the xO
7230: 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 pen().** call, d
7240: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 epending on the
7250: 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 object being ope
7260: 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a ned:.**.** <ul>.
7270: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
7280: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a _OPEN_MAIN_DB].*
7290: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
72a0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 OPEN_MAIN_JOURNA
72b0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c L].** <li> [SQL
72c0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 ITE_OPEN_TEMP_DB
72d0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 ].** <li> [SQLI
72e0: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 TE_OPEN_TEMP_JOU
72f0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b RNAL].** <li> [
7300: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e SQLITE_OPEN_TRAN
7310: 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 SIENT_DB].** <li
7320: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
7330: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c SUBJOURNAL].** <
7340: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
7350: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c N_MASTER_JOURNAL
7360: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a ].** </ul>.**.**
7370: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d The file I/O im
7380: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e plementation can
7390: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 use the object
73a0: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a type flags to.**
73b0: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 change the way
73c0: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 it deals with fi
73d0: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c les. For exampl
73e0: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f e, an applicatio
73f0: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e n.** that does n
7400: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 ot care about cr
7410: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 ash recovery or
7420: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d rollback might m
7430: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 ake.** the open
7440: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c of a journal fil
7450: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 e a no-op. Writ
7460: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e es to this journ
7470: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f al would.** also
7480: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 be no-ops, and
7490: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 any attempt to r
74a0: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 ead the journal
74b0: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 would return.**
74c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f SQLITE_IOERR. O
74d0: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 r the implementa
74e0: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 tion might recog
74f0: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 nize that a data
7500: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c base.** file wil
7510: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d l be doing page-
7520: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 aligned sector r
7530: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 eads and writes
7540: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f in a random.** o
7550: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 rder and set up
7560: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 its I/O subsyste
7570: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a m accordingly..*
7580: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 *.** SQLite migh
7590: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f t also add one o
75a0: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 f the following
75b0: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 flags to the xOp
75c0: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a en method:.**.**
75d0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 <ul>.** <li> [S
75e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 QLITE_OPEN_DELET
75f0: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 EONCLOSE].** <li
7600: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 > [SQLITE_OPEN_E
7610: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 XCLUSIVE].** </u
7620: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 l>.**.** The [SQ
7630: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 LITE_OPEN_DELETE
7640: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 ONCLOSE] flag me
7650: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f ans the file sho
7660: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 uld be.** delete
7670: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f d when it is clo
7680: 73 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 sed. The [SQLIT
7690: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 E_OPEN_DELETEONC
76a0: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 LOSE].** will be
76b0: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 20 64 set for TEMP d
76c0: 61 74 61 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 atabases, journa
76d0: 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f ls and for subjo
76e0: 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 urnals..**.** Th
76f0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 e [SQLITE_OPEN_E
7700: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 XCLUSIVE] flag i
7710: 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e s always used in
7720: 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 conjunction.**
7730: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 with the [SQLITE
7740: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c _OPEN_CREATE] fl
7750: 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f ag, which are bo
7760: 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 th directly.** a
7770: 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 nalogous to the
7780: 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 O_EXCL and O_CRE
7790: 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 AT flags of the
77a0: 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 POSIX open().**
77b0: 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 API. The SQLITE
77c0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 _OPEN_EXCLUSIVE
77d0: 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 flag, when paire
77e0: 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 d with the .** S
77f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
7800: 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e E, is used to in
7810: 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 dicate that file
7820: 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a should always.*
7830: 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e * be created, an
7840: 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 d that it is an
7850: 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 error if it alre
7860: 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 ady exists..** I
7870: 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 t is <i>not</i>
7880: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 used to indicate
7890: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 the file should
78a0: 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 be opened .** f
78b0: 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 or exclusive acc
78c0: 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 41 74 20 6c 65 ess..**.** At le
78d0: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 ast szOsFile byt
78e0: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 es of memory are
78f0: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 allocated by SQ
7900: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 Lite.** to hold
7910: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 the [sqlite3_fi
7920: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 le] structure pa
7930: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 ssed as the thir
7940: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f d.** argument to
7950: 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 xOpen. The xOp
7960: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e en method does n
7970: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c ot have to.** al
7980: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 locate the struc
7990: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 ture; it should
79a0: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e just fill it in.
79b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 .**.** The flags
79c0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 argument to xAc
79d0: 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 cess() may be [S
79e0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 QLITE_ACCESS_EXI
79f0: 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 STS].** to test
7a00: 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 for the existenc
7a10: 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 e of a file, or
7a20: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 [SQLITE_ACCESS_R
7a30: 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 EADWRITE] to.**
7a40: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 test whether a f
7a50: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 ile is readable
7a60: 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 and writable, or
7a70: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f [SQLITE_ACCESS_
7a80: 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 READ].** to test
7a90: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 whether a file
7aa0: 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 is at least read
7ab0: 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 able. The file
7ac0: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 can be a.** dir
7ad0: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 ectory..**.** SQ
7ae0: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 Lite will always
7af0: 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 allocate at lea
7b00: 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 st mxPathname+1
7b10: 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a bytes for the.**
7b20: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78 output buffer x
7b30: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 FullPathname. T
7b40: 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 he exact size of
7b50: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 the output buff
7b60: 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 er.** is also pa
7b70: 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 ssed as a parame
7b80: 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 ter to both met
7b90: 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 hods. If the out
7ba0: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 put buffer.** is
7bb0: 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 not large enoug
7bc0: 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f h, [SQLITE_CANTO
7bd0: 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 PEN] should be r
7be0: 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 eturned. Since t
7bf0: 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 his is.** handle
7c00: 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 d as a fatal err
7c10: 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 or by SQLite, vf
7c20: 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e s implementation
7c30: 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f s should endeavo
7c40: 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 r.** to prevent
7c50: 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 this by setting
7c60: 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 mxPathname to a
7c70: 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 sufficiently lar
7c80: 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 ge value..**.**
7c90: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 The xRandomness(
7ca0: 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61 6e 64 ), xSleep(), and
7cb0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 xCurrentTime()
7cc0: 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 interfaces.** ar
7cd0: 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 e not strictly a
7ce0: 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c part of the fil
7cf0: 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 esystem, but the
7d00: 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 y are.** include
7d10: 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 d in the VFS str
7d20: 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c ucture for compl
7d30: 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 eteness..** The
7d40: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 xRandomness() fu
7d50: 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 nction attempts
7d60: 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 to return nBytes
7d70: 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f bytes.** of goo
7d80: 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d d-quality random
7d90: 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 ness into zOut.
7da0: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 The return valu
7db0: 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 e is.** the actu
7dc0: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 al number of byt
7dd0: 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 es of randomness
7de0: 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 obtained..** Th
7df0: 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f e xSleep() metho
7e00: 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c d causes the cal
7e10: 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 ling thread to s
7e20: 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c leep for at.** l
7e30: 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 east the number
7e40: 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 of microseconds
7e50: 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43 75 72 given. The xCur
7e60: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 rentTime().** me
7e70: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a thod returns a J
7e80: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 ulian Day Number
7e90: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 for the current
7ea0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 2e 0a date and time..
7eb0: 2a 2a 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 **.*/.typedef st
7ec0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 ruct sqlite3_vfs
7ed0: 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 73 74 sqlite3_vfs;.st
7ee0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 ruct sqlite3_vfs
7ef0: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f {. int iVersio
7f00: 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a n; /*
7f10: 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69 Structure versi
7f20: 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 69 on number */. i
7f30: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 nt szOsFile;
7f40: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 /* Size
7f50: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 of subclassed sq
7f60: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 lite3_file */.
7f70: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 int mxPathname;
7f80: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 /* Maxi
7f90: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d mum file pathnam
7fa0: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 e length */. sq
7fb0: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 lite3_vfs *pNext
7fc0: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 ; /* Next r
7fd0: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f egistered VFS */
7fe0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
7ff0: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e Name; /* N
8000: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 ame of this virt
8010: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 ual file system
8020: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 */. void *pAppD
8030: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a ata; /*
8040: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c Pointer to appl
8050: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 ication-specific
8060: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 data */. int (
8070: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f *xOpen)(sqlite3_
8080: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
8090: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 *zName, sqlite3
80a0: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 _file*,.
80b0: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 int flags
80c0: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 , int *pOutFlags
80d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 );. int (*xDele
80e0: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a te)(sqlite3_vfs*
80f0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
8100: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 ame, int syncDir
8110: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 );. int (*xAcce
8120: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ss)(sqlite3_vfs*
8130: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
8140: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 ame, int flags,
8150: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 int *pResOut);.
8160: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 int (*xFullPath
8170: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 name)(sqlite3_vf
8180: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a s*, const char *
8190: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c zName, int nOut,
81a0: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 char *zOut);.
81b0: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 void *(*xDlOpen)
81c0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
81d0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 onst char *zFile
81e0: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a name);. void (*
81f0: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 xDlError)(sqlite
8200: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 3_vfs*, int nByt
8210: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 e, char *zErrMsg
8220: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 );. void (*(*xD
8230: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 lSym)(sqlite3_vf
8240: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 s*,void*, const
8250: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 char *zSymbol))(
8260: 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a void);. void (*
8270: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 xDlClose)(sqlite
8280: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 3_vfs*, void*);.
8290: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e int (*xRandomn
82a0: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ess)(sqlite3_vfs
82b0: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 *, int nByte, ch
82c0: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 ar *zOut);. int
82d0: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 (*xSleep)(sqlit
82e0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 e3_vfs*, int mic
82f0: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e roseconds);. in
8300: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 t (*xCurrentTime
8310: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
8320: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 double*);. int
8330: 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 (*xGetLastError)
8340: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 (sqlite3_vfs*, i
8350: 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f nt, char *);. /
8360: 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 * New fields may
8370: 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 be appended in
8380: 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e figure versions.
8390: 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 The iVersion.
83a0: 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 ** value will i
83b0: 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 ncrement wheneve
83c0: 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 r this happens.
83d0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.};../*.** CAP
83e0: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 I3REF: Flags for
83f0: 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53 the xAccess VFS
8400: 20 6d 65 74 68 6f 64 20 7b 48 31 31 31 39 30 7d method {H11190}
8410: 20 3c 48 31 31 31 34 30 3e 0a 2a 2a 0a 2a 2a 20 <H11140>.**.**
8420: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f These integer co
8430: 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 nstants can be u
8440: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 sed as the third
8450: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
8460: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 the xAccess met
8470: 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 hod of an [sqlit
8480: 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 e3_vfs] object.
8490: 7b 45 4e 44 7d 20 20 54 68 65 79 20 64 65 74 65 {END} They dete
84a0: 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 rmine.** what ki
84b0: 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e nd of permission
84c0: 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 s the xAccess me
84d0: 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 thod is looking
84e0: 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c for..** With SQL
84f0: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 ITE_ACCESS_EXIST
8500: 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d S, the xAccess m
8510: 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 ethod.** simply
8520: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 checks whether t
8530: 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a he file exists..
8540: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 ** With SQLITE_A
8550: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c CCESS_READWRITE,
8560: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 the xAccess met
8570: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 hod.** checks wh
8580: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 ether the file i
8590: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 s both readable
85a0: 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 0a 2a 2a and writable..**
85b0: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 With SQLITE_ACC
85c0: 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 ESS_READ, the xA
85d0: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 ccess method.**
85e0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 checks whether t
85f0: 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 he file is reada
8600: 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ble..*/.#define
8610: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 SQLITE_ACCESS_EX
8620: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e ISTS 0.#defin
8630: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f e SQLITE_ACCESS_
8640: 52 45 41 44 57 52 49 54 45 20 31 0a 23 64 65 66 READWRITE 1.#def
8650: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 ine SQLITE_ACCES
8660: 53 5f 52 45 41 44 20 20 20 20 20 20 32 0a 0a 2f S_READ 2../
8670: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 *.** CAPI3REF: I
8680: 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 nitialize The SQ
8690: 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b 48 31 Lite Library {H1
86a0: 30 31 33 30 7d 20 3c 53 32 30 30 30 30 3e 3c 53 0130} <S20000><S
86b0: 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 30100>.**.** The
86c0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
86d0: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e ize() routine in
86e0: 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a itializes the.**
86f0: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e SQLite library.
8700: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 The sqlite3_sh
8710: 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 utdown() routine
8720: 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 .** deallocates
8730: 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 any resources th
8740: 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 at were allocate
8750: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 d by sqlite3_ini
8760: 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a tialize()..**.**
8770: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 A call to sqlit
8780: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
8790: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 is an "effective
87a0: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a " call if it is.
87b0: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d ** the first tim
87c0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
87d0: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 lize() is invoke
87e0: 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 d during the lif
87f0: 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 etime of.** the
8800: 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 process, or if i
8810: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 t is the first t
8820: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 ime sqlite3_init
8830: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f ialize() is invo
8840: 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 ked.** following
8850: 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 a call to sqlit
8860: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 e3_shutdown().
8870: 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 Only an effectiv
8880: 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c e call.** of sql
8890: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
88a0: 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 ) does any initi
88b0: 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 alization. All
88c0: 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 other calls.** a
88d0: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f re harmless no-o
88e0: 70 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c ps..**.** A call
88f0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 to sqlite3_shut
8900: 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 down() is an "ef
8910: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 fective" call if
8920: 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74 it is the first
8930: 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 .** call to sqli
8940: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 te3_shutdown() s
8950: 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 ince the last sq
8960: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
8970: 28 29 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 (). Only.** an
8980: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 effective call t
8990: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f o sqlite3_shutdo
89a0: 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 wn() does any de
89b0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a initialization..
89c0: 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c ** All other cal
89d0: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 ls to sqlite3_sh
89e0: 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 utdown() are har
89f0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a mless no-ops..**
8a00: 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 .** Among other
8a10: 74 68 69 6e 67 73 2c 20 73 71 6c 69 74 65 33 5f things, sqlite3_
8a20: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 68 61 initialize() sha
8a30: 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c ll invoke.** sql
8a40: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 ite3_os_init().
8a50: 20 53 69 6d 69 6c 61 72 6c 79 2c 20 73 71 6c 69 Similarly, sqli
8a60: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a te3_shutdown().*
8a70: 2a 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 20 73 * shall invoke s
8a80: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e qlite3_os_end().
8a90: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
8aa0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
8ab0: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
8ac0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 [SQLITE_OK] on s
8ad0: 75 63 63 65 73 73 2e 0a 2a 2a 20 49 66 20 66 6f uccess..** If fo
8ae0: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 r some reason, s
8af0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
8b00: 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f e() is unable to
8b10: 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 initialize.** t
8b20: 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 he library (perh
8b30: 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 aps it is unable
8b40: 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e to allocate a n
8b50: 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 eeded resource s
8b60: 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 uch.** as a mute
8b70: 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e x) it returns an
8b80: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 [error code] ot
8b90: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 her than [SQLITE
8ba0: 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 _OK]..**.** The
8bb0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
8bc0: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 ze() routine is
8bd0: 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c called internall
8be0: 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a y by many other.
8bf0: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 ** SQLite interf
8c00: 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 aces so that an
8c10: 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 application usua
8c20: 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 lly does not nee
8c30: 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 d to.** invoke s
8c40: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
8c50: 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 e() directly. F
8c60: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c or example, [sql
8c70: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 ite3_open()].**
8c80: 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e calls sqlite3_in
8c90: 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 itialize() so th
8ca0: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 e SQLite library
8cb0: 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 will be automat
8cc0: 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 ically.** initia
8cd0: 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 lized when [sqli
8ce0: 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 te3_open()] is c
8cf0: 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 alled if it has
8d00: 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a not be initializ
8d10: 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 ed.** already.
8d20: 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 However, if SQLi
8d30: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
8d40: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ith the [SQLITE_
8d50: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a OMIT_AUTOINIT].*
8d60: 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f * compile-time o
8d70: 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 ption, then the
8d80: 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 automatic calls
8d90: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 to sqlite3_initi
8da0: 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f alize().** are o
8db0: 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 mitted and the a
8dc0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
8dd0: 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 call sqlite3_ini
8de0: 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 tialize() direct
8df0: 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 ly.** prior to u
8e00: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 sing any other S
8e10: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e QLite interface.
8e20: 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f For maximum po
8e30: 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 rtability,.** it
8e40: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
8e50: 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e that application
8e60: 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 s always invoke
8e70: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
8e80: 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 ze().** directly
8e90: 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 prior to using
8ea0: 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 any other SQLite
8eb0: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 interface. Fut
8ec0: 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 ure releases.**
8ed0: 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 of SQLite may re
8ee0: 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 quire this. In
8ef0: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 other words, the
8f00: 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 behavior exhibi
8f10: 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 ted.** when SQLi
8f20: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
8f30: 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 ith [SQLITE_OMIT
8f40: 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 _AUTOINIT] might
8f50: 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 become the.** d
8f60: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 efault behavior
8f70: 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 in some future r
8f80: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 elease of SQLite
8f90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
8fa0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f te3_os_init() ro
8fb0: 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 utine does opera
8fc0: 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 ting-system spec
8fd0: 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 ific.** initiali
8fe0: 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 zation of the SQ
8ff0: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 Lite library. T
9000: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e he sqlite3_os_en
9010: 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 d().** routine u
9020: 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 ndoes the effect
9030: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 of sqlite3_os_i
9040: 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 nit(). Typical
9050: 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d tasks.** perform
9060: 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 ed by these rout
9070: 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c ines include all
9080: 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c ocation or deall
9090: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 ocation.** of st
90a0: 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 atic resources,
90b0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f initialization o
90c0: 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c f global variabl
90d0: 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 es,.** setting u
90e0: 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c p a default [sql
90f0: 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 ite3_vfs] module
9100: 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a , or setting up.
9110: 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e ** a default con
9120: 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 figuration using
9130: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
9140: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 ()]..**.** The a
9150: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
9160: 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 d never invoke e
9170: 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 ither sqlite3_os
9180: 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 _init().** or sq
9190: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 lite3_os_end() d
91a0: 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 irectly. The ap
91b0: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 plication should
91c0: 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 only invoke.**
91d0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
91e0: 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 ze() and sqlite3
91f0: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 _shutdown(). Th
9200: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 e sqlite3_os_ini
9210: 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 t().** interface
9220: 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d is called autom
9230: 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 atically by sqli
9240: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
9250: 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f and.** sqlite3_
9260: 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c os_end() is call
9270: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 ed by sqlite3_sh
9280: 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f utdown(). Appro
9290: 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d priate.** implem
92a0: 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 entations for sq
92b0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 lite3_os_init()
92c0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 and sqlite3_os_e
92d0: 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c nd().** are buil
92e0: 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 t into SQLite wh
92f0: 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 en it is compile
9300: 64 20 66 6f 72 20 75 6e 69 78 2c 20 77 69 6e 64 d for unix, wind
9310: 6f 77 73 2c 20 6f 72 20 6f 73 2f 32 2e 0a 2a 2a ows, or os/2..**
9320: 20 57 68 65 6e 20 62 75 69 6c 74 20 66 6f 72 20 When built for
9330: 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 20 other platforms
9340: 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 (using the [SQLI
9350: 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 TE_OS_OTHER=1] c
9360: 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f ompile-time.** o
9370: 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 ption) the appli
9380: 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 cation must supp
9390: 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d ly a suitable im
93a0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 plementation for
93b0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 .** sqlite3_os_i
93c0: 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 nit() and sqlite
93d0: 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 3_os_end(). An
93e0: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 application-supp
93f0: 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e lied.** implemen
9400: 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 tation of sqlite
9410: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 3_os_init() or s
9420: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a qlite3_os_end().
9430: 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b ** must return [
9440: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 SQLITE_OK] on su
9450: 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f ccess and some o
9460: 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 ther [error code
9470: 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 ] upon.** failur
9480: 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 e..*/.int sqlite
9490: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 3_initialize(voi
94a0: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f d);.int sqlite3_
94b0: 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a shutdown(void);.
94c0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 int sqlite3_os_i
94d0: 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 nit(void);.int s
94e0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f qlite3_os_end(vo
94f0: 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 id);../*.** CAPI
9500: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 3REF: Configurin
9510: 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 g The SQLite Lib
9520: 72 61 72 79 20 7b 48 31 34 31 30 30 7d 20 3c 53 rary {H14100} <S
9530: 32 30 30 30 30 3e 3c 53 33 30 32 30 30 3e 0a 2a 20000><S30200>.*
9540: 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
9550: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
9560: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 _config() interf
9570: 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d ace is used to m
9580: 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 ake global confi
9590: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e guration.** chan
95a0: 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e ges to SQLite in
95b0: 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 order to tune S
95c0: 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 QLite to the spe
95d0: 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a cific needs of.*
95e0: 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f * the applicatio
95f0: 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 n. The default
9600: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 configuration is
9610: 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 recommended for
9620: 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 most.** applica
9630: 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 tions and so thi
9640: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 s routine is usu
9650: 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 ally not necessa
9660: 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 ry. It is.** pr
9670: 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 ovided to suppor
9680: 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 t rare applicati
9690: 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c ons with unusual
96a0: 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 needs..**.** Th
96b0: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 e sqlite3_config
96c0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
96d0: 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 not threadsafe.
96e0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
96f0: 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 .** must insure
9700: 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 that no other SQ
9710: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 Lite interfaces
9720: 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f are invoked by o
9730: 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 ther.** threads
9740: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f while sqlite3_co
9750: 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e nfig() is runnin
9760: 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c g. Furthermore,
9770: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
9780: 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 ).** may only be
9790: 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 invoked prior t
97a0: 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 o library initia
97b0: 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a lization using.*
97c0: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 * [sqlite3_initi
97d0: 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 alize()] or afte
97e0: 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 r shutdown by [s
97f0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
9800: 29 5d 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 )]..** Note, how
9810: 65 76 65 72 2c 20 74 68 61 74 20 73 71 6c 69 74 ever, that sqlit
9820: 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 e3_config() can
9830: 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 be called as par
9840: 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c t of the.** impl
9850: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e ementation of an
9860: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
9870: 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 ined [sqlite3_os
9880: 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 _init()]..**.**
9890: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
98a0: 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f nt to sqlite3_co
98b0: 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 nfig() is an int
98c0: 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f eger.** [SQLITE_
98d0: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 CONFIG_SINGLETHR
98e0: 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 EAD | configurat
98f0: 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 ion option] that
9900: 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 determines.** w
9910: 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 hat property of
9920: 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 SQLite is to be
9930: 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 configured. Sub
9940: 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 sequent argument
9950: 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 s.** vary depend
9960: 69 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51 4c 49 ing on the [SQLI
9970: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 TE_CONFIG_SINGLE
9980: 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 THREAD | configu
9990: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a ration option].*
99a0: 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 * in the first a
99b0: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 rgument..**.** W
99c0: 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 hen a configurat
99d0: 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 ion option is se
99e0: 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 t, sqlite3_confi
99f0: 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c g() returns [SQL
9a00: 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 49 66 20 74 ITE_OK]..** If t
9a10: 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b he option is unk
9a20: 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 nown or SQLite i
9a30: 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 s unable to set
9a40: 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 the option.** th
9a50: 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 en this routine
9a60: 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 returns a non-ze
9a70: 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e ro [error code].
9a80: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
9a90: 6e 74 73 3a 0a 2a 2a 20 5b 48 31 34 31 30 33 5d nts:.** [H14103]
9aa0: 20 5b 48 31 34 31 30 36 5d 20 5b 48 31 34 31 32 [H14106] [H1412
9ab0: 30 5d 20 5b 48 31 34 31 32 33 5d 20 5b 48 31 34 0] [H14123] [H14
9ac0: 31 32 36 5d 20 5b 48 31 34 31 32 39 5d 20 5b 48 126] [H14129] [H
9ad0: 31 34 31 33 32 5d 20 5b 48 31 34 31 33 35 5d 0a 14132] [H14135].
9ae0: 2a 2a 20 5b 48 31 34 31 33 38 5d 20 5b 48 31 34 ** [H14138] [H14
9af0: 31 34 31 5d 20 5b 48 31 34 31 34 34 5d 20 5b 48 141] [H14144] [H
9b00: 31 34 31 34 37 5d 20 5b 48 31 34 31 35 30 5d 20 14147] [H14150]
9b10: 5b 48 31 34 31 35 33 5d 20 5b 48 31 34 31 35 36 [H14153] [H14156
9b20: 5d 20 5b 48 31 34 31 35 39 5d 0a 2a 2a 20 5b 48 ] [H14159].** [H
9b30: 31 34 31 36 32 5d 20 5b 48 31 34 31 36 35 5d 20 14162] [H14165]
9b40: 5b 48 31 34 31 36 38 5d 0a 2a 2f 0a 53 51 4c 49 [H14168].*/.SQLI
9b50: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 TE_EXPERIMENTAL
9b60: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 int sqlite3_conf
9b70: 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f ig(int, ...);../
9b80: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
9b90: 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 onfigure databas
9ba0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 20 7b e connections {
9bb0: 48 31 34 32 30 30 7d 20 3c 53 32 30 30 30 30 3e H14200} <S20000>
9bc0: 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c .** EXPERIMENTAL
9bd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
9be0: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 e3_db_config() i
9bf0: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 nterface is used
9c00: 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 to make configu
9c10: 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 ration.** change
9c20: 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 s to a [database
9c30: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 connection]. T
9c40: 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 he interface is
9c50: 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 similar to.** [s
9c60: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
9c70: 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 except that the
9c80: 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 changes apply t
9c90: 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 o a single.** [d
9ca0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
9cb0: 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 on] (specified i
9cc0: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 n the first argu
9cd0: 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a 20 73 ment). The.** s
9ce0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
9cf0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e () interface can
9d00: 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 69 6d only be used im
9d10: 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 0a mediately after.
9d20: 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ** the database
9d30: 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 72 connection is cr
9d40: 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c eated using [sql
9d50: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a ite3_open()],.**
9d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
9d70: 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 ()], or [sqlite3
9d80: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 0a 2a _open_v2()]. .*
9d90: 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 *.** The second
9da0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
9db0: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c te3_db_config(D,
9dc0: 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a V,...) is the.*
9dd0: 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 * configuration
9de0: 76 65 72 62 20 2d 20 61 6e 20 69 6e 74 65 67 65 verb - an intege
9df0: 72 20 63 6f 64 65 20 74 68 61 74 20 69 6e 64 69 r code that indi
9e00: 63 61 74 65 73 20 77 68 61 74 0a 2a 2a 20 61 73 cates what.** as
9e10: 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 pect of the [dat
9e20: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
9e30: 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 ] is being confi
9e40: 67 75 72 65 64 2e 0a 2a 2a 20 54 68 65 20 6f 6e gured..** The on
9e50: 6c 79 20 63 68 6f 69 63 65 20 66 6f 72 20 74 68 ly choice for th
9e60: 69 73 20 76 61 6c 75 65 20 69 73 20 5b 53 51 4c is value is [SQL
9e70: 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
9e80: 4b 41 53 49 44 45 5d 2e 0a 2a 2a 20 4e 65 77 20 KASIDE]..** New
9e90: 76 65 72 62 73 20 61 72 65 20 6c 69 6b 65 6c 79 verbs are likely
9ea0: 20 74 6f 20 62 65 20 61 64 64 65 64 20 69 6e 20 to be added in
9eb0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 future releases
9ec0: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 41 64 of SQLite..** Ad
9ed0: 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e ditional argumen
9ee0: 74 73 20 64 65 70 65 6e 64 20 6f 6e 20 74 68 65 ts depend on the
9ef0: 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 verb..**.** Req
9f00: 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
9f10: 31 34 32 30 33 5d 20 5b 48 31 34 32 30 36 5d 20 14203] [H14206]
9f20: 5b 48 31 34 32 30 39 5d 20 5b 48 31 34 32 31 32 [H14209] [H14212
9f30: 5d 20 5b 48 31 34 32 31 35 5d 0a 2a 2f 0a 53 51 ] [H14215].*/.SQ
9f40: 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 LITE_EXPERIMENTA
9f50: 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 L int sqlite3_db
9f60: 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a _config(sqlite3*
9f70: 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a , int op, ...);.
9f80: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
9f90: 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 Memory Allocati
9fa0: 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48 31 30 on Routines {H10
9fb0: 31 35 35 7d 20 3c 53 32 30 31 32 30 3e 0a 2a 2a 155} <S20120>.**
9fc0: 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a EXPERIMENTAL.**
9fd0: 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 .** An instance
9fe0: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 of this object d
9ff0: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 efines the inter
a000: 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c face between SQL
a010: 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c ite.** and low-l
a020: 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f evel memory allo
a030: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e cation routines.
a040: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 .**.** This obje
a050: 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e ct is used in on
a060: 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 ly one place in
a070: 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 the SQLite inter
a080: 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 face..** A point
a090: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 er to an instanc
a0a0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 e of this object
a0b0: 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 is the argument
a0c0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
a0d0: 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 config()] when t
a0e0: 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e he configuration
a0f0: 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 option is.** [S
a100: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c QLITE_CONFIG_MAL
a110: 4c 4f 43 5d 2e 20 20 42 79 20 63 72 65 61 74 69 LOC]. By creati
a120: 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f ng an instance o
a130: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a f this object.**
a140: 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 and passing it
a150: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 to [sqlite3_conf
a160: 69 67 28 29 5d 20 64 75 72 69 6e 67 20 63 6f 6e ig()] during con
a170: 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 0a 2a figuration, an.*
a180: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 * application ca
a190: 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 n specify an alt
a1a0: 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 20 ernative memory
a1b0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 allocation subsy
a1c0: 73 74 65 6d 0a 2a 2a 20 66 6f 72 20 53 51 4c 69 stem.** for SQLi
a1d0: 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c te to use for al
a1e0: 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 l of its dynamic
a1f0: 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a memory needs..*
a200: 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 *.** Note that S
a210: 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 QLite comes with
a220: 20 61 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f a built-in memo
a230: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 ry allocator tha
a240: 74 20 69 73 0a 2a 2a 20 70 65 72 66 65 63 74 6c t is.** perfectl
a250: 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 y adequate for t
a260: 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 he overwhelming
a270: 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c majority of appl
a280: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 ications.** and
a290: 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 that this object
a2a0: 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 is only useful
a2b0: 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 to a tiny minori
a2c0: 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f ty of applicatio
a2d0: 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 ns.** with speci
a2e0: 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c alized memory al
a2f0: 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 location require
a300: 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a ments. This obj
a310: 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 ect is.** also u
a320: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 sed during testi
a330: 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 ng of SQLite in
a340: 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 order to specify
a350: 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a an alternative.
a360: 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ** memory alloca
a370: 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 tor that simulat
a380: 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 es memory out-of
a390: 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f -memory conditio
a3a0: 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 ns in.** order t
a3b0: 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 o verify that SQ
a3c0: 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 Lite recovers gr
a3d0: 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 acefully from su
a3e0: 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 ch.** conditions
a3f0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c ..**.** The xMal
a400: 6c 6f 63 2c 20 78 46 72 65 65 2c 20 61 6e 64 20 loc, xFree, and
a410: 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 73 xRealloc methods
a420: 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 must work like
a430: 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c the.** malloc(),
a440: 20 66 72 65 65 28 29 2c 20 61 6e 64 20 72 65 61 free(), and rea
a450: 6c 6c 6f 63 28 29 20 66 75 6e 63 74 69 6f 6e 73 lloc() functions
a460: 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 from the standa
a470: 72 64 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a rd library..**.*
a480: 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 * xSize should r
a490: 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 eturn the alloca
a4a0: 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 ted size of a me
a4b0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a mory allocation.
a4c0: 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 ** previously ob
a4d0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c tained from xMal
a4e0: 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e loc or xRealloc.
a4f0: 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 The allocated
a500: 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 size.** is alway
a510: 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 s at least as bi
a520: 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74 g as the request
a530: 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 ed size but may
a540: 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a be larger..**.**
a550: 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 The xRoundup me
a560: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 thod returns wha
a570: 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 t would be the a
a580: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 llocated size of
a590: 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c .** a memory all
a5a0: 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 ocation given a
a5b0: 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 particular reque
a5c0: 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 sted size. Most
a5d0: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 memory.** alloc
a5e0: 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d ators round up m
a5f0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
a600: 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 s at least to th
a610: 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a e next multiple.
a620: 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 ** of 8. Some a
a630: 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 llocators round
a640: 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d up to a larger m
a650: 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 ultiple or to a
a660: 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 0a 2a power of 2..**.*
a670: 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 * The xInit meth
a680: 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 od initializes t
a690: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
a6a0: 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 tor. (For examp
a6b0: 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 le,.** it might
a6c0: 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 allocate any req
a6d0: 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 uire mutexes or
a6e0: 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 initialize inter
a6f0: 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 nal data.** stru
a700: 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 ctures. The xSh
a710: 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 utdown method is
a720: 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 invoked (indire
a730: 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c ctly) by.** [sql
a740: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d ite3_shutdown()]
a750: 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c and should deal
a760: 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 locate any resou
a770: 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a rces acquired.**
a780: 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 by xInit. The
a790: 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 pAppData pointer
a7a0: 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 is used as the
a7b0: 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 only parameter t
a7c0: 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 o.** xInit and x
a7d0: 53 68 75 74 64 6f 77 6e 2e 0a 2a 2f 0a 74 79 70 Shutdown..*/.typ
a7e0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
a7f0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 te3_mem_methods
a800: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
a810: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 ods;.struct sqli
a820: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 te3_mem_methods
a830: 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c {. void *(*xMal
a840: 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 loc)(int);
a850: 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c /* Memory all
a860: 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e ocation function
a870: 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 */. void (*xFr
a880: 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 ee)(void*);
a890: 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 /* Free a p
a8a0: 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 rior allocation
a8b0: 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 */. void *(*xRe
a8c0: 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 alloc)(void*,int
a8d0: 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e ); /* Resize an
a8e0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 allocation */.
a8f0: 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f int (*xSize)(vo
a900: 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 id*);
a910: 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 /* Return the si
a920: 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 ze of an allocat
a930: 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 ion */. int (*x
a940: 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 Roundup)(int);
a950: 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 /* Round
a960: 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 up request size
a970: 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 to allocation s
a980: 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 ize */. int (*x
a990: 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 Init)(void*);
a9a0: 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 /* Initi
a9b0: 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 alize the memory
a9c0: 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 allocator */.
a9d0: 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e void (*xShutdown
a9e0: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f )(void*); /
a9f0: 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 * Deinitialize t
aa00: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
aa10: 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 tor */. void *p
aa20: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 AppData;
aa30: 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d /* Argum
aa40: 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 ent to xInit() a
aa50: 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a nd xShutdown() *
aa60: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.};../*.** CAPI
aa70: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 3REF: Configurat
aa80: 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 48 31 30 ion Options {H10
aa90: 31 36 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 160} <S20000>.**
aaa0: 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a EXPERIMENTAL.**
aab0: 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 .** These consta
aac0: 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 nts are the avai
aad0: 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f lable integer co
aae0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
aaf0: 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 ons that.** can
ab00: 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 be passed as the
ab10: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
ab20: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
ab30: 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 config()] interf
ab40: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 ace..**.** New c
ab50: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
ab60: 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 ions may be adde
ab70: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
ab80: 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ases of SQLite..
ab90: 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 ** Existing conf
aba0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
abb0: 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f s might be disco
abc0: 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 ntinued. Applic
abd0: 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 ations.** should
abe0: 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 check the retur
abf0: 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c n code from [sql
ac00: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 ite3_config()] t
ac10: 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 o make sure that
ac20: 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 .** the call wor
ac30: 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 ked. The [sqlit
ac40: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 e3_config()] int
ac50: 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 erface will retu
ac60: 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f rn a.** non-zero
ac70: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 [error code] if
ac80: 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 a discontinued
ac90: 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 or unsupported c
aca0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
acb0: 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 ion.** is invoke
acc0: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a d..**.** <dl>.**
acd0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
ace0: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c IG_SINGLETHREAD<
acf0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 /dt>.** <dd>Ther
ad00: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e e are no argumen
ad10: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f ts to this optio
ad20: 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 n. This option
ad30: 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 disables.** all
ad40: 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 mutexing and put
ad50: 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 s SQLite into a
ad60: 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61 mode where it ca
ad70: 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a n only be used.*
ad80: 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 * by a single th
ad90: 72 65 61 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a read.</dd>.**.**
ada0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
adb0: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f IG_MULTITHREAD</
adc0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 dt>.** <dd>There
add0: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 are no argument
ade0: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e s to this option
adf0: 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 64 . This option d
ae00: 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 isables.** mutex
ae10: 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 ing on [database
ae20: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 connection] and
ae30: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
ae40: 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a ment] objects..*
ae50: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f * The applicatio
ae60: 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 n is responsible
ae70: 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 for serializing
ae80: 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 access to.** [d
ae90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
aea0: 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 ons] and [prepar
aeb0: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 ed statements].
aec0: 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 But other mutex
aed0: 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 es.** are enable
aee0: 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 d so that SQLite
aef0: 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f will be safe to
af00: 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d use in a multi-
af10: 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 threaded.** envi
af20: 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 ronment as long
af30: 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 as no two thread
af40: 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 s attempt to use
af50: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 the same.** [da
af60: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
af70: 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 n] at the same t
af80: 69 6d 65 2e 20 20 53 65 65 20 74 68 65 20 5b 74 ime. See the [t
af90: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 0a 2a hreading mode].*
afa0: 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 * documentation
afb0: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 for additional i
afc0: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e nformation.</dd>
afd0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
afe0: 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 E_CONFIG_SERIALI
aff0: 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ZED</dt>.** <dd>
b000: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 There are no arg
b010: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f uments to this o
b020: 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 ption. This opt
b030: 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 ion enables.** a
b040: 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 ll mutexes inclu
b050: 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 ding the recursi
b060: 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e ve.** mutexes on
b070: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
b080: 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 ction] and [prep
b090: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
b0a0: 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 objects..** In t
b0b0: 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 his mode (which
b0c0: 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 is the default w
b0d0: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f hen SQLite is co
b0e0: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b mpiled with.** [
b0f0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
b100: 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 E=1]) the SQLite
b110: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 library will it
b120: 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 self serialize a
b130: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 ccess.** to [dat
b140: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
b150: 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 s] and [prepared
b160: 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 statements] so
b170: 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c that the.** appl
b180: 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 ication is free
b190: 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 to use the same
b1a0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
b1b0: 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 tion] or the.**
b1c0: 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 same [prepared s
b1d0: 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 tatement] in dif
b1e0: 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 ferent threads a
b1f0: 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e t the same time.
b200: 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 .** See the [thr
b210: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 eading mode] doc
b220: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 umentation for a
b230: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d dditional inform
b240: 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a ation.</dd>.**.*
b250: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
b260: 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a FIG_MALLOC</dt>.
b270: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 ** <dd>This opti
b280: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
b290: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
b2a0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
b2b0: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 an.** instance
b2c0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
b2d0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 mem_methods] str
b2e0: 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 ucture. The arg
b2f0: 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a ument specifies.
b300: 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c ** alternative l
b310: 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 ow-level memory
b320: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 allocation routi
b330: 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 nes to be used i
b340: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 n place of.** th
b350: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
b360: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 ion routines bui
b370: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c lt into SQLite.<
b380: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
b390: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
b3a0: 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c MALLOC</dt>.** <
b3b0: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 dd>This option t
b3c0: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
b3d0: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 gument which is
b3e0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a a pointer to an.
b3f0: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 ** instance of t
b400: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f he [sqlite3_mem_
b410: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 methods] structu
b420: 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 re. The [sqlite
b430: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 3_mem_methods].*
b440: 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 * structure is f
b450: 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 illed with the c
b460: 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 urrently defined
b470: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
b480: 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 on routines..**
b490: 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 This option can
b4a0: 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c be used to overl
b4b0: 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 oad the default
b4c0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
b4d0: 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 n.** routines wi
b4e0: 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 th a wrapper tha
b4f0: 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 t simulations me
b500: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
b510: 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 failure or.** tr
b520: 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 acks memory usag
b530: 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 3c e, for example.<
b540: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
b550: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d QLITE_CONFIG_MEM
b560: 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c STATUS</dt>.** <
b570: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 dd>This option t
b580: 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 akes single argu
b590: 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 ment of type int
b5a0: 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 , interpreted as
b5b0: 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 a .** boolean,
b5c0: 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 which enables or
b5d0: 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f disables the co
b5e0: 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f llection of memo
b5f0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a ry allocation .*
b600: 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 57 68 * statistics. Wh
b610: 65 6e 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 en disabled, the
b620: 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 following SQLit
b630: 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 e interfaces bec
b640: 6f 6d 65 20 0a 2a 2a 20 6e 6f 6e 2d 6f 70 65 72 ome .** non-oper
b650: 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 ational:.** <u
b660: 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 l>.** <li> [sq
b670: 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 lite3_memory_use
b680: 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b d()].** <li> [
b690: 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 sqlite3_memory_h
b6a0: 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 ighwater()].**
b6b0: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 <li> [sqlite3_s
b6c0: 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 oft_heap_limit()
b6d0: 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c ].** <li> [sql
b6e0: 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a ite3_status()].*
b6f0: 2a 20 20 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 * </ul>.** </d
b700: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
b710: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 ITE_CONFIG_SCRAT
b720: 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 CH</dt>.** <dd>T
b730: 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 his option speci
b740: 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 fies a static me
b750: 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 mory buffer that
b760: 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 SQLite can use
b770: 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d for.** scratch m
b780: 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72 emory. There ar
b790: 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 e three argument
b7a0: 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f s: A pointer to
b7b0: 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20 74 68 65 the memory, the
b7c0: 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 .** size of each
b7d0: 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 scratch buffer
b7e0: 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 (sz), and the nu
b7f0: 6d 62 65 72 20 6f 66 20 62 75 66 66 65 72 73 20 mber of buffers
b800: 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 (N). The sz.**
b810: 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 argument must be
b820: 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 a multiple of 1
b830: 36 2e 20 54 68 65 20 73 7a 20 70 61 72 61 6d 65 6. The sz parame
b840: 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 ter should be a
b850: 66 65 77 20 62 79 74 65 73 0a 2a 2a 20 6c 61 72 few bytes.** lar
b860: 67 65 72 20 74 68 61 6e 20 74 68 65 20 61 63 74 ger than the act
b870: 75 61 6c 20 73 63 72 61 74 63 68 20 73 70 61 63 ual scratch spac
b880: 65 20 72 65 71 75 69 72 65 64 20 64 75 65 20 69 e required due i
b890: 6e 74 65 72 6e 61 6c 20 6f 76 65 72 68 65 61 64 nternal overhead
b8a0: 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 0a 2a ..** The first.*
b8b0: 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c * argument shoul
b8c0: 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c d point to an al
b8d0: 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c location of at l
b8e0: 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 east sz*N bytes
b8f0: 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 of memory..** SQ
b900: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f Lite will use no
b910: 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 more than one s
b920: 63 72 61 74 63 68 20 62 75 66 66 65 72 20 61 74 cratch buffer at
b930: 20 6f 6e 63 65 20 70 65 72 20 74 68 72 65 61 64 once per thread
b940: 2c 20 73 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 , so.** N should
b950: 20 62 65 20 73 65 74 20 74 6f 20 74 68 65 20 65 be set to the e
b960: 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 xpected maximum
b970: 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 number of thread
b980: 73 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 70 61 s. The sz.** pa
b990: 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 rameter should b
b9a0: 65 20 36 20 74 69 6d 65 73 20 74 68 65 20 73 69 e 6 times the si
b9b0: 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 ze of the larges
b9c0: 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 t database page
b9d0: 73 69 7a 65 2e 0a 2a 2a 20 53 63 72 61 74 63 68 size..** Scratch
b9e0: 20 62 75 66 66 65 72 73 20 61 72 65 20 75 73 65 buffers are use
b9f0: 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 d as part of the
ba00: 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65 20 6f btree balance o
ba10: 70 65 72 61 74 69 6f 6e 2e 20 20 49 66 0a 2a 2a peration. If.**
ba20: 20 54 68 65 20 62 74 72 65 65 20 62 61 6c 61 6e The btree balan
ba30: 63 65 72 20 6e 65 65 64 73 20 61 64 64 69 74 69 cer needs additi
ba40: 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 62 65 79 6f onal memory beyo
ba50: 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 nd what is provi
ba60: 64 65 64 20 62 79 0a 2a 2a 20 73 63 72 61 74 63 ded by.** scratc
ba70: 68 20 62 75 66 66 65 72 73 20 6f 72 20 69 66 20 h buffers or if
ba80: 6e 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 65 no scratch buffe
ba90: 72 20 73 70 61 63 65 20 69 73 20 73 70 65 63 69 r space is speci
baa0: 66 69 65 64 2c 20 74 68 65 6e 20 53 51 4c 69 74 fied, then SQLit
bab0: 65 0a 2a 2a 20 67 6f 65 73 20 74 6f 20 5b 73 71 e.** goes to [sq
bac0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
bad0: 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 to obtain the me
bae0: 6d 6f 72 79 20 69 74 20 6e 65 65 64 73 2e 3c 2f mory it needs.</
baf0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
bb00: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 LITE_CONFIG_PAGE
bb10: 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 CACHE</dt>.** <d
bb20: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 d>This option sp
bb30: 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 ecifies a static
bb40: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 memory buffer t
bb50: 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 hat SQLite can u
bb60: 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 se for.** the da
bb70: 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68 tabase page cach
bb80: 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75 e with the defau
bb90: 6c 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d lt page cache im
bba0: 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a plemenation. .*
bbb0: 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 * This configura
bbc0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 tion should not
bbd0: 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 be used if an ap
bbe0: 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
bbf0: 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 page.** cache i
bc00: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 mplementation is
bc10: 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 loaded using th
bc20: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
bc30: 50 43 41 43 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a PCACHE option..*
bc40: 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 * There are thre
bc50: 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 e arguments to t
bc60: 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f his option: A po
bc70: 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 inter to the.**
bc80: 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 memory, the size
bc90: 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75 of each page bu
bca0: 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 ffer (sz), and t
bcb0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 he number of pag
bcc0: 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 es (N)..** The s
bcd0: 7a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 z argument must
bce0: 62 65 20 61 20 70 6f 77 65 72 20 6f 66 20 74 77 be a power of tw
bcf0: 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e o between 512 an
bd00: 64 20 33 32 37 36 38 2e 20 20 54 68 65 20 66 69 d 32768. The fi
bd10: 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 rst.** argument
bd20: 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 should point to
bd30: 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 an allocation of
bd40: 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 at least sz*N b
bd50: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a ytes of memory..
bd60: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 ** SQLite will u
bd70: 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 se the memory pr
bd80: 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69 ovided by the fi
bd90: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
bda0: 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d satisfy its.** m
bdb0: 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 emory needs for
bdc0: 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 the first N page
bdd0: 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74 s that it adds t
bde0: 6f 20 63 61 63 68 65 2e 20 20 49 66 20 61 64 64 o cache. If add
bdf0: 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 itional.** page
be00: 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 cache memory is
be10: 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 needed beyond wh
be20: 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 at is provided b
be30: 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 y this option, t
be40: 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f hen.** SQLite go
be50: 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d es to [sqlite3_m
be60: 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 alloc()] for the
be70: 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 additional stor
be80: 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 age space..** Th
be90: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
bea0: 20 6d 69 67 68 74 20 75 73 65 20 6f 6e 65 20 6f might use one o
beb0: 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 4e 20 r more of the N
bec0: 62 75 66 66 65 72 73 20 74 6f 20 68 6f 6c 64 20 buffers to hold
bed0: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 63 63 6f 75 .** memory accou
bee0: 6e 74 69 6e 67 20 69 6e 66 6f 72 6d 61 74 69 6f nting informatio
bef0: 6e 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c n. </dd>.**.** <
bf00: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
bf10: 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 _HEAP</dt>.** <d
bf20: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 d>This option sp
bf30: 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 ecifies a static
bf40: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 memory buffer t
bf50: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 hat SQLite will
bf60: 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f use.** for all o
bf70: 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 f its dynamic me
bf80: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
bf90: 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f needs beyond tho
bfa0: 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 se provided.** f
bfb0: 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f or by [SQLITE_CO
bfc0: 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e NFIG_SCRATCH] an
bfd0: 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 d [SQLITE_CONFIG
bfe0: 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 _PAGECACHE]..**
bff0: 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 There are three
c000: 61 72 67 75 6d 65 6e 74 73 3a 20 41 20 70 6f 69 arguments: A poi
c010: 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f nter to the memo
c020: 72 79 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 6f ry, the number o
c030: 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 f.** bytes in th
c040: 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c e memory buffer,
c050: 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d and the minimum
c060: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 allocation size
c070: 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 66 69 72 . If.** the fir
c080: 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 st pointer (the
c090: 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 memory pointer)
c0a0: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 is NULL, then SQ
c0b0: 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 Lite reverts.**
c0c0: 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 to using its def
c0d0: 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ault memory allo
c0e0: 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 cator (the syste
c0f0: 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 m malloc() imple
c100: 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 mentation),.** u
c110: 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 ndoing any prior
c120: 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b invocation of [
c130: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 SQLITE_CONFIG_MA
c140: 4c 4c 4f 43 5d 2e 20 20 49 66 20 74 68 65 0a 2a LLOC]. If the.*
c150: 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 * memory pointer
c160: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 is not NULL and
c170: 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f either [SQLITE_
c180: 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 ENABLE_MEMSYS3]
c190: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e or.** [SQLITE_EN
c1a0: 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 ABLE_MEMSYS5] ar
c1b0: 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 e defined, then
c1c0: 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 the alternative
c1d0: 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 memory.** alloca
c1e0: 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 tor is engaged t
c1f0: 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 o handle all of
c200: 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 SQLites memory a
c210: 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e llocation needs.
c220: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
c230: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
c240: 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TEX</dt>.** <dd>
c250: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
c260: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
c270: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 ent which is a p
c280: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 ointer to an.**
c290: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 instance of the
c2a0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d [sqlite3_mutex_m
c2b0: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 ethods] structur
c2c0: 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 e. The argument
c2d0: 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c specifies.** al
c2e0: 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 ternative low-le
c2f0: 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e vel mutex routin
c300: 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e es to be used in
c310: 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 place.** the mu
c320: 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 tex routines bui
c330: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c lt into SQLite.<
c340: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
c350: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
c360: 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 MUTEX</dt>.** <d
c370: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 d>This option ta
c380: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 kes a single arg
c390: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 ument which is a
c3a0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a pointer to an.*
c3b0: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 * instance of th
c3c0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 e [sqlite3_mutex
c3d0: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 _methods] struct
c3e0: 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 ure. The.** [sq
c3f0: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 lite3_mutex_meth
c400: 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 ods].** structur
c410: 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 e is filled with
c420: 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 the currently d
c430: 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 efined mutex rou
c440: 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f tines..** This o
c450: 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 ption can be use
c460: 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 d to overload th
c470: 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 e default mutex
c480: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f allocation.** ro
c490: 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 utines with a wr
c4a0: 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 apper used to tr
c4b0: 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 ack mutex usage
c4c0: 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a for performance.
c4d0: 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 ** profiling or
c4e0: 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 testing, for exa
c4f0: 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a mple.</dd>.**.**
c500: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
c510: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 IG_LOOKASIDE</dt
c520: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 >.** <dd>This op
c530: 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 tion takes two a
c540: 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 rguments that de
c550: 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 termine the defa
c560: 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c ult.** memory al
c570: 6c 63 61 74 69 6f 6e 20 6c 6f 6f 6b 61 73 69 64 lcation lookasid
c580: 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e 20 e optimization.
c590: 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
c5a0: 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 ent is the.** si
c5b0: 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 ze of each looka
c5c0: 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 side buffer slot
c5d0: 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 and the second
c5e0: 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 is the number of
c5f0: 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 .** slots alloca
c600: 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 ted to each data
c610: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e base connection.
c620: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
c630: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
c640: 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 ACHE</dt>.** <dd
c650: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b >This option tak
c660: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
c670: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 ment which is a
c680: 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e pointer to.** an
c690: 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 [sqlite3_pcache
c6a0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 _methods] object
c6b0: 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 . This object s
c6c0: 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e 74 pecifies the int
c6d0: 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 erface.** to a c
c6e0: 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 ustom page cache
c6f0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e implementation.
c700: 20 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 SQLite makes a
c710: 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 copy of the.**
c720: 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20 object and uses
c730: 69 74 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 it for page cach
c740: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
c750: 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ions.</dd>.**.**
c760: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
c770: 49 47 5f 47 45 54 50 43 41 43 48 45 3c 2f 64 74 IG_GETPCACHE</dt
c780: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 >.** <dd>This op
c790: 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e tion takes a sin
c7a0: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 gle argument whi
c7b0: 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 ch is a pointer
c7c0: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 to an.** [sqlite
c7d0: 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3_pcache_methods
c7e0: 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 ] object. SQLit
c7f0: 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65 20 e copies of the
c800: 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 current.** page
c810: 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 cache implementa
c820: 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f tion into that o
c830: 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a bject.</dd>.**.*
c840: 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 * </dl>.*/.#defi
c850: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
c860: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 _SINGLETHREAD 1
c870: 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 /* nil */.#def
c880: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
c890: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 G_MULTITHREAD
c8a0: 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 2 /* nil */.#de
c8b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
c8c0: 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 IG_SERIALIZED
c8d0: 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 3 /* nil */.#d
c8e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
c8f0: 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 FIG_MALLOC
c900: 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 4 /* sqlite3_
c910: 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a mem_methods* */.
c920: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
c930: 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 ONFIG_GETMALLOC
c940: 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 5 /* sqlite
c950: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 3_mem_methods* *
c960: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
c970: 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 _CONFIG_SCRATCH
c980: 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 6 /* void
c990: 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e *, int sz, int N
c9a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
c9b0: 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 TE_CONFIG_PAGECA
c9c0: 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f CHE 7 /* vo
c9d0: 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 id*, int sz, int
c9e0: 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 N */.#define SQ
c9f0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 LITE_CONFIG_HEAP
ca00: 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 8 /*
ca10: 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 void*, int nByte
ca20: 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 , int min */.#de
ca30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
ca40: 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 IG_MEMSTATUS
ca50: 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 9 /* boolean *
ca60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
ca70: 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 _CONFIG_MUTEX
ca80: 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 10 /* sqli
ca90: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 te3_mutex_method
caa0: 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 s* */.#define SQ
cab0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
cac0: 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 UTEX 11 /*
cad0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 sqlite3_mutex_me
cae0: 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 thods* */./* pre
caf0: 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 viously SQLITE_C
cb00: 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 ONFIG_CHUNKALLOC
cb10: 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 12 which is now
cb20: 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 unused. */ .#de
cb30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
cb40: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 IG_LOOKASIDE
cb50: 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 13 /* int int *
cb60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
cb70: 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 _CONFIG_PCACHE
cb80: 20 20 20 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 14 /* sqli
cb90: 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f te3_pcache_metho
cba0: 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ds* */.#define S
cbb0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
cbc0: 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a PCACHE 15 /*
cbd0: 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f sqlite3_pcache_
cbe0: 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 0a 2f 2a 0a methods* */../*.
cbf0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e ** CAPI3REF: Con
cc00: 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f figuration Optio
cc10: 6e 73 20 7b 48 31 30 31 37 30 7d 20 3c 53 32 30 ns {H10170} <S20
cc20: 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 000>.** EXPERIME
cc30: 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 NTAL.**.** These
cc40: 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 constants are t
cc50: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 he available int
cc60: 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 eger configurati
cc70: 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a on options that.
cc80: 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 ** can be passed
cc90: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 as the second a
cca0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b rgument to the [
ccb0: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
ccc0: 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a g()] interface..
ccd0: 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 **.** New config
cce0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 uration options
ccf0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 may be added in
cd00: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 future releases
cd10: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 of SQLite..** Ex
cd20: 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 isting configura
cd30: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 tion options mig
cd40: 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 ht be discontinu
cd50: 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e ed. Application
cd60: 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 s.** should chec
cd70: 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 k the return cod
cd80: 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f e from [sqlite3_
cd90: 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 db_config()] to
cda0: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a make sure that.*
cdb0: 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 * the call worke
cdc0: 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 d. The [sqlite3
cdd0: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e _db_config()] in
cde0: 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 terface will ret
cdf0: 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 urn a.** non-zer
ce00: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 o [error code] i
ce10: 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 f a discontinued
ce20: 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 or unsupported
ce30: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
ce40: 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b tion.** is invok
ce50: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a ed..**.** <dl>.*
ce60: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 * <dt>SQLITE_DBC
ce70: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c ONFIG_LOOKASIDE<
ce80: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 /dt>.** <dd>This
ce90: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 option takes th
cea0: 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 ree additional a
ceb0: 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 rguments that de
cec0: 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 termine the .**
ced0: 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 [lookaside memor
cee0: 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e y allocator] con
cef0: 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 figuration for t
cf00: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
cf10: 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 nection]..** The
cf20: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
cf30: 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d (the third param
cf40: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 eter to [sqlite3
cf50: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 _db_config()] is
cf60: 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f a.** pointer to
cf70: 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 a memory buffer
cf80: 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b to use for look
cf90: 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 20 20 54 aside memory. T
cfa0: 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 he first.** argu
cfb0: 6d 65 6e 74 20 6d 61 79 20 62 65 20 4e 55 4c 4c ment may be NULL
cfc0: 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 in which case S
cfd0: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 QLite will alloc
cfe0: 61 74 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 ate the lookasid
cff0: 65 0a 2a 2a 20 62 75 66 66 65 72 20 69 74 73 65 e.** buffer itse
d000: 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 lf using [sqlite
d010: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 3_malloc()]. Th
d020: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
d030: 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 t is the.** size
d040: 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 of each lookasi
d050: 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 de buffer slot a
d060: 6e 64 20 74 68 65 20 74 68 69 72 64 20 61 72 67 nd the third arg
d070: 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d ument is the num
d080: 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e ber of.** slots.
d090: 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 The size of th
d0a0: 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 e buffer in the
d0b0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d first argument m
d0c0: 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74 ust be greater t
d0d0: 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 han.** or equal
d0e0: 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f to the product o
d0f0: 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 f the second and
d100: 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 third arguments
d110: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 .</dd>.**.** </d
d120: 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 l>.*/.#define SQ
d130: 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f LITE_DBCONFIG_LO
d140: 4f 4b 41 53 49 44 45 20 20 20 20 31 30 30 31 20 OKASIDE 1001
d150: 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e /* void* int in
d160: 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 t */.../*.** CAP
d170: 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 I3REF: Enable Or
d180: 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 Disable Extende
d190: 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b d Result Codes {
d1a0: 48 31 32 32 30 30 7d 20 3c 53 31 30 37 30 30 3e H12200} <S10700>
d1b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
d1c0: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 e3_extended_resu
d1d0: 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 lt_codes() routi
d1e0: 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 ne enables or di
d1f0: 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 sables the.** [e
d200: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
d210: 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 odes] feature of
d220: 20 53 51 4c 69 74 65 2e 20 54 68 65 20 65 78 74 SQLite. The ext
d230: 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 ended result.**
d240: 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c codes are disabl
d250: 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f ed by default fo
d260: 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d r historical com
d270: 70 61 74 69 62 69 6c 69 74 79 20 63 6f 6e 73 69 patibility consi
d280: 64 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a derations..**.**
d290: 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
d2a0: 2a 20 5b 48 31 32 32 30 31 5d 20 5b 48 31 32 32 * [H12201] [H122
d2b0: 30 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 02].*/.int sqlit
d2c0: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 e3_extended_resu
d2d0: 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 lt_codes(sqlite3
d2e0: 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a *, int onoff);..
d2f0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
d300: 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 Last Insert Rowi
d310: 64 20 7b 48 31 32 32 32 30 7d 20 3c 53 31 30 37 d {H12220} <S107
d320: 30 30 3e 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 00>.**.** Each e
d330: 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 ntry in an SQLit
d340: 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e e table has a un
d350: 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e ique 64-bit sign
d360: 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 ed.** integer ke
d370: 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f y called the [RO
d380: 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 WID | "rowid"].
d390: 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 The rowid is alw
d3a0: 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a ays available.**
d3b0: 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 as an undeclare
d3c0: 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 d column named R
d3d0: 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 OWID, OID, or _R
d3e0: 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 OWID_ as long as
d3f0: 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 those.** names
d400: 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 are not also use
d410: 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 d by explicitly
d420: 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 declared columns
d430: 2e 20 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c . If.** the tabl
d440: 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f e has a column o
d450: 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 f type [INTEGER
d460: 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 PRIMARY KEY] the
d470: 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a n that column.**
d480: 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 is another alia
d490: 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e s for the rowid.
d4a0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
d4b0: 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ine returns the
d4c0: 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d [rowid] of the m
d4d0: 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 ost recent.** su
d4e0: 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 ccessful [INSERT
d4f0: 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 ] into the datab
d500: 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 ase from the [da
d510: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
d520: 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 n].** in the fir
d530: 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 st argument. If
d540: 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b no successful [
d550: 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 INSERT]s.** have
d560: 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f ever occurred o
d570: 6e 20 74 68 61 74 20 64 61 74 61 62 61 73 65 20 n that database
d580: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f connection, zero
d590: 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
d5a0: 0a 2a 2a 20 49 66 20 61 6e 20 5b 49 4e 53 45 52 .** If an [INSER
d5b0: 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e T] occurs within
d5c0: 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e a trigger, then
d5d0: 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 the [rowid] of
d5e0: 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 the inserted.**
d5f0: 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 row is returned
d600: 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 by this routine
d610: 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 as long as the t
d620: 72 69 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e rigger is runnin
d630: 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 g..** But once t
d640: 68 65 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 he trigger termi
d650: 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 nates, the value
d660: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 returned by thi
d670: 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 s routine.** rev
d680: 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 erts to the last
d690: 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 value inserted
d6a0: 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 before the trigg
d6b0: 65 72 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 er fired..**.**
d6c0: 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 An [INSERT] that
d6d0: 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 fails due to a
d6e0: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 constraint viola
d6f0: 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a tion is not a.**
d700: 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 successful [INS
d710: 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f ERT] and does no
d720: 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c t change the val
d730: 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 ue returned by t
d740: 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 his.** routine.
d750: 20 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 Thus INSERT OR
d760: 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 FAIL, INSERT OR
d770: 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f IGNORE, INSERT O
d780: 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 R ROLLBACK,.** a
d790: 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f nd INSERT OR ABO
d7a0: 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 RT make no chang
d7b0: 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e es to the return
d7c0: 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a value of this.*
d7d0: 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 * routine when t
d7e0: 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 heir insertion f
d7f0: 61 69 6c 73 2e 20 20 57 68 65 6e 20 49 4e 53 45 ails. When INSE
d800: 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a RT OR REPLACE.**
d810: 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f encounters a co
d820: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 nstraint violati
d830: 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 on, it does not
d840: 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e fail. The.** IN
d850: 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 SERT continues t
d860: 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 o completion aft
d870: 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 er deleting rows
d880: 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 that caused.**
d890: 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 the constraint p
d8a0: 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 roblem so INSERT
d8b0: 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c OR REPLACE will
d8c0: 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a always change.*
d8d0: 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c * the return val
d8e0: 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 ue of this inter
d8f0: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 face..**.** For
d900: 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 the purposes of
d910: 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e this routine, an
d920: 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e [INSERT] is con
d930: 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 sidered to.** be
d940: 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e successful even
d950: 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 if it is subseq
d960: 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 uently rolled ba
d970: 63 6b 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 ck..**.** Requir
d980: 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 ements:.** [H122
d990: 32 31 5d 20 5b 48 31 32 32 32 33 5d 0a 2a 2a 0a 21] [H12223].**.
d9a0: 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 ** If a separate
d9b0: 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 thread performs
d9c0: 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 a new [INSERT]
d9d0: 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 on the same.** d
d9e0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
d9f0: 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 on while the [sq
da00: 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 lite3_last_inser
da10: 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 t_rowid()].** fu
da20: 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e nction is runnin
da30: 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 g and thus chang
da40: 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 es the last inse
da50: 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 rt [rowid],.** t
da60: 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 hen the value re
da70: 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
da80: 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 e3_last_insert_r
da90: 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e owid()] is.** un
daa0: 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 predictable and
dab0: 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 might not equal
dac0: 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f either the old o
dad0: 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 r the new.** las
dae0: 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d t insert [rowid]
daf0: 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 ..*/.sqlite3_int
db00: 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 64 sqlite3_last_
db10: 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c insert_rowid(sql
db20: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ite3*);../*.** C
db30: 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 API3REF: Count T
db40: 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 he Number Of Row
db50: 73 20 4d 6f 64 69 66 69 65 64 20 7b 48 31 32 32 s Modified {H122
db60: 34 30 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 40} <S10600>.**.
db70: 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e ** This function
db80: 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
db90: 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 ber of database
dba0: 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63 rows that were c
dbb0: 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 hanged.** or ins
dbc0: 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 erted or deleted
dbd0: 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 by the most rec
dbe0: 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 ently completed
dbf0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a SQL statement.**
dc00: 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 on the [databas
dc10: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 e connection] sp
dc20: 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66 ecified by the f
dc30: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a irst parameter..
dc40: 2a 2a 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 ** Only changes
dc50: 74 68 61 74 20 61 72 65 20 64 69 72 65 63 74 6c that are directl
dc60: 79 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 y specified by t
dc70: 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 he [INSERT], [UP
dc80: 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 DATE],.** or [DE
dc90: 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 LETE] statement
dca0: 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 are counted. Au
dcb0: 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 xiliary changes
dcc0: 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 caused by.** tri
dcd0: 67 67 65 72 73 20 61 72 65 20 6e 6f 74 20 63 6f ggers are not co
dce0: 75 6e 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b unted. Use the [
dcf0: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 sqlite3_total_ch
dd00: 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f anges()] functio
dd10: 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 n.** to find the
dd20: 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 total number of
dd30: 20 63 68 61 6e 67 65 73 20 69 6e 63 6c 75 64 69 changes includi
dd40: 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 ng changes cause
dd50: 64 20 62 79 20 74 72 69 67 67 65 72 73 2e 0a 2a d by triggers..*
dd60: 2a 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 *.** Changes to
dd70: 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 a view that are
dd80: 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20 simulated by an
dd90: 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 [INSTEAD OF trig
dda0: 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 ger].** are not
ddb0: 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 counted. Only r
ddc0: 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65 eal table change
ddd0: 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a s are counted..*
dde0: 2a 0a 2a 2a 20 41 20 22 72 6f 77 20 63 68 61 6e *.** A "row chan
ddf0: 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 ge" is a change
de00: 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 to a single row
de10: 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c of a single tabl
de20: 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 e.** caused by a
de30: 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 n INSERT, DELETE
de40: 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 , or UPDATE stat
de50: 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 ement. Rows tha
de60: 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 t.** are changed
de70: 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73 as side effects
de80: 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f of [REPLACE] co
de90: 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 nstraint resolut
dea0: 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b ion,.** rollback
deb0: 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 , ABORT processi
dec0: 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d ng, [DROP TABLE]
ded0: 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 , or by any othe
dee0: 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 r.** mechanisms
def0: 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 do not count as
df00: 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 direct row chang
df10: 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 es..**.** A "tri
df20: 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 gger context" is
df30: 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 a scope of exec
df40: 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e ution that begin
df50: 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 s and.** ends wi
df60: 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 th the script of
df70: 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 a [CREATE TRIGG
df80: 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a ER | trigger]. .
df90: 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 ** Most SQL stat
dfa0: 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 ements are.** ev
dfb0: 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 aluated outside
dfc0: 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 of any trigger.
dfd0: 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f This is the "to
dfe0: 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 p level".** trig
dff0: 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 ger context. If
e000: 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73 a trigger fires
e010: 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 from the top le
e020: 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 vel, a.** new tr
e030: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 igger context is
e040: 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 entered for the
e050: 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 duration of tha
e060: 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 t one.** trigger
e070: 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63 . Subtriggers c
e080: 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 reate subcontext
e090: 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 s for their dura
e0a0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c tion..**.** Call
e0b0: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 ing [sqlite3_exe
e0c0: 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 c()] or [sqlite3
e0d0: 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 _step()] recursi
e0e0: 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 vely does.** not
e0f0: 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 create a new tr
e100: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a igger context..*
e110: 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 *.** This functi
e120: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e on returns the n
e130: 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 umber of direct
e140: 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 row changes in t
e150: 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e he.** most recen
e160: 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 t INSERT, UPDATE
e170: 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 , or DELETE stat
e180: 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 ement within the
e190: 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 same.** trigger
e1a0: 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 context..**.**
e1b0: 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 Thus, when calle
e1c0: 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c d from the top l
e1d0: 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 evel, this funct
e1e0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a ion returns the.
e1f0: 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 ** number of cha
e200: 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 nges in the most
e210: 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 recent INSERT,
e220: 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 UPDATE, or DELET
e230: 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f E.** that also o
e240: 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74 ccurred at the t
e250: 6f 70 20 6c 65 76 65 6c 2e 20 20 57 69 74 68 69 op level. Withi
e260: 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20 n the body of a
e270: 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 trigger,.** the
e280: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 sqlite3_changes(
e290: 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 ) interface can
e2a0: 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e be called to fin
e2b0: 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a d the number of.
e2c0: 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 ** changes in th
e2d0: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 e most recently
e2e0: 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 completed INSERT
e2f0: 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c , UPDATE, or DEL
e300: 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 ETE.** statement
e310: 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 within the body
e320: 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72 69 of the same tri
e330: 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 gger..** However
e340: 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74 , the number ret
e350: 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 urned does not i
e360: 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a nclude changes.*
e370: 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 62 74 * caused by subt
e380: 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 74 68 riggers since th
e390: 6f 73 65 20 68 61 76 65 20 74 68 65 69 72 20 6f ose have their o
e3a0: 77 6e 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a wn context..**.*
e3b0: 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b * See also the [
e3c0: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 sqlite3_total_ch
e3d0: 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 anges()] interfa
e3e0: 63 65 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 63 ce and the.** [c
e3f0: 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 ount_changes pra
e400: 67 6d 61 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 gma]..**.** Requ
e410: 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
e420: 32 32 34 31 5d 20 5b 48 31 32 32 34 33 5d 0a 2a 2241] [H12243].*
e430: 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 *.** If a separa
e440: 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 te thread makes
e450: 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 changes on the s
e460: 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e ame database con
e470: 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 nection.** while
e480: 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 [sqlite3_change
e490: 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 s()] is running
e4a0: 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 then the value r
e4b0: 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e eturned.** is un
e4c0: 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 predictable and
e4d0: 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a not meaningful..
e4e0: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 */.int sqlite3_c
e4f0: 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 hanges(sqlite3*)
e500: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
e510: 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 F: Total Number
e520: 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 Of Rows Modified
e530: 20 7b 48 31 32 32 36 30 7d 20 3c 53 31 30 36 30 {H12260} <S1060
e540: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 0>.**.** This fu
e550: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 nction returns t
e560: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 he number of row
e570: 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 changes caused
e580: 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 by [INSERT],.**
e590: 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c [UPDATE] or [DEL
e5a0: 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 ETE] statements
e5b0: 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 since the [datab
e5c0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
e5d0: 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 54 was opened..** T
e5e0: 68 65 20 63 6f 75 6e 74 20 69 6e 63 6c 75 64 65 he count include
e5f0: 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 20 66 72 s all changes fr
e600: 6f 6d 20 61 6c 6c 20 0a 2a 2a 20 5b 43 52 45 41 om all .** [CREA
e610: 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 TE TRIGGER | tri
e620: 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 2e 20 gger] contexts.
e630: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 However,.** the
e640: 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 count does not
e650: 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 include changes
e660: 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e used to implemen
e670: 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 t [REPLACE] cons
e680: 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 traints,.** do r
e690: 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 ollbacks or ABOR
e6a0: 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 T processing, or
e6b0: 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 [DROP TABLE] pr
e6c0: 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a ocessing. The.*
e6d0: 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 * count does not
e6e0: 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 include rows of
e6f0: 20 76 69 65 77 73 20 74 68 61 74 20 66 69 72 65 views that fire
e700: 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 an [INSTEAD OF
e710: 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f trigger],.** tho
e720: 75 67 68 20 69 66 20 74 68 65 20 49 4e 53 54 45 ugh if the INSTE
e730: 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61 AD OF trigger ma
e740: 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69 kes changes of i
e750: 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 ts own, those ch
e760: 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f anges .** are co
e770: 75 6e 74 65 64 2e 0a 2a 2a 20 54 68 65 20 63 68 unted..** The ch
e780: 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 anges are counte
e790: 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 d as soon as the
e7a0: 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 statement that
e7b0: 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 0a 2a 2a makes them is.**
e7c0: 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e completed (when
e7d0: 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 the statement h
e7e0: 61 6e 64 6c 65 20 69 73 20 70 61 73 73 65 64 20 andle is passed
e7f0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 to [sqlite3_rese
e800: 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 t()] or.** [sqli
e810: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 te3_finalize()])
e820: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
e830: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 the [sqlite3_ch
e840: 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 anges()] interfa
e850: 63 65 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 63 ce and the.** [c
e860: 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 ount_changes pra
e870: 67 6d 61 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 gma]..**.** Requ
e880: 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
e890: 32 32 36 31 5d 20 5b 48 31 32 32 36 33 5d 0a 2a 2261] [H12263].*
e8a0: 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 *.** If a separa
e8b0: 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 te thread makes
e8c0: 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 changes on the s
e8d0: 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e ame database con
e8e0: 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 nection.** while
e8f0: 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f [sqlite3_total_
e900: 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 changes()] is ru
e910: 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 nning then the v
e920: 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 alue.** returned
e930: 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c is unpredictabl
e940: 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e e and not meanin
e950: 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c gful..*/.int sql
e960: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
e970: 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f es(sqlite3*);../
e980: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 *.** CAPI3REF: I
e990: 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d nterrupt A Long-
e9a0: 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 20 7b 48 Running Query {H
e9b0: 31 32 32 37 30 7d 20 3c 53 33 30 35 30 30 3e 0a 12270} <S30500>.
e9c0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 **.** This funct
e9d0: 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 ion causes any p
e9e0: 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 ending database
e9f0: 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f operation to abo
ea00: 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e rt and.** return
ea10: 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 at its earliest
ea20: 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 opportunity. Th
ea30: 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 is routine is ty
ea40: 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 pically.** calle
ea50: 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f d in response to
ea60: 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 a user action s
ea70: 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 uch as pressing
ea80: 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 "Cancel".** or C
ea90: 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 trl-C where the
eaa0: 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e user wants a lon
eab0: 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f g query operatio
eac0: 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d n to halt.** imm
ead0: 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 ediately..**.**
eae0: 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 It is safe to ca
eaf0: 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 ll this routine
eb00: 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 from a thread di
eb10: 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 fferent from the
eb20: 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 .** thread that
eb30: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e is currently run
eb40: 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 ning the databas
eb50: 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 e operation. Bu
eb60: 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 t it.** is not s
eb70: 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 afe to call this
eb80: 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 routine with a
eb90: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
eba0: 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 tion] that.** is
ebb0: 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 closed or might
ebc0: 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 close before sq
ebd0: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
ebe0: 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a ) returns..**.**
ebf0: 20 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 If an SQL opera
ec00: 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 tion is very nea
ec10: 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 rly finished at
ec20: 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a the time when.**
ec30: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
ec40: 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 pt() is called,
ec50: 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f then it might no
ec60: 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 t have an opport
ec70: 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 unity.** to be i
ec80: 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d nterrupted and m
ec90: 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f ight continue to
eca0: 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a completion..**.
ecb0: 2a 2a 20 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 ** An SQL operat
ecc0: 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 ion that is inte
ecd0: 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 rrupted will ret
ece0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 urn [SQLITE_INTE
ecf0: 52 52 55 50 54 5d 2e 0a 2a 2a 20 49 66 20 74 68 RRUPT]..** If th
ed00: 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 e interrupted SQ
ed10: 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 L operation is a
ed20: 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 n INSERT, UPDATE
ed30: 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 , or DELETE.** t
ed40: 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e hat is inside an
ed50: 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 explicit transa
ed60: 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 ction, then the
ed70: 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 entire transacti
ed80: 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f on.** will be ro
ed90: 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 lled back automa
eda0: 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 tically..**.** T
edb0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 he sqlite3_inter
edc0: 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 rupt(D) call is
edd0: 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 in effect until
ede0: 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 all currently ru
edf0: 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 nning.** SQL sta
ee00: 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 tements on [data
ee10: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
ee20: 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 41 6e D complete. An
ee30: 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d y new SQL statem
ee40: 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 ents.** that are
ee50: 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 started after t
ee60: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 he sqlite3_inter
ee70: 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 rupt() call and
ee80: 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 before the .** r
ee90: 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 unning statement
eea0: 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 s reaches zero a
eeb0: 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 re interrupted a
eec0: 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 s if they had be
eed0: 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 en.** running pr
eee0: 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ior to the sqlit
eef0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 e3_interrupt() c
ef00: 61 6c 6c 2e 20 20 4e 65 77 20 53 51 4c 20 73 74 all. New SQL st
ef10: 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 atements.** that
ef20: 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 are started aft
ef30: 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 er the running s
ef40: 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 tatement count r
ef50: 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a eaches zero are.
ef60: 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 ** not effected
ef70: 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 by the sqlite3_i
ef80: 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 41 nterrupt()..** A
ef90: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
efa0: 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 _interrupt(D) th
efb0: 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 at occurs when t
efc0: 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e here are no runn
efd0: 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 ing.** SQL state
efe0: 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 ments is a no-op
eff0: 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 and has no effe
f000: 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d ct on SQL statem
f010: 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 ents.** that are
f020: 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 started after t
f030: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 he sqlite3_inter
f040: 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 rupt() call retu
f050: 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 rns..**.** Requi
f060: 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 rements:.** [H12
f070: 32 37 31 5d 20 5b 48 31 32 32 37 32 5d 0a 2a 2a 271] [H12272].**
f080: 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 .** If the datab
f090: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 ase connection c
f0a0: 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c loses while [sql
f0b0: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
f0c0: 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 ].** is running
f0d0: 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 then bad things
f0e0: 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 will likely happ
f0f0: 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 en..*/.void sqli
f100: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 te3_interrupt(sq
f110: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 lite3*);../*.**
f120: 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d CAPI3REF: Determ
f130: 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 ine If An SQL St
f140: 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c atement Is Compl
f150: 65 74 65 20 7b 48 31 30 35 31 30 7d 20 3c 53 37 ete {H10510} <S7
f160: 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 0200>.**.** Thes
f170: 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 e routines are u
f180: 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d seful during com
f190: 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 mand-line input
f1a0: 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 to determine if
f1b0: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 the.** currently
f1c0: 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 entered text se
f1d0: 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f ems to form a co
f1e0: 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 mplete SQL state
f1f0: 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 ment or.** if ad
f200: 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 ditional input i
f210: 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 s needed before
f220: 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 sending the text
f230: 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 into.** SQLite
f240: 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 54 68 for parsing. Th
f250: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 ese routines ret
f260: 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 urn 1 if the inp
f270: 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 ut string.** app
f280: 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d ears to be a com
f290: 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d plete SQL statem
f2a0: 65 6e 74 2e 20 20 41 20 73 74 61 74 65 6d 65 6e ent. A statemen
f2b0: 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 t is judged to b
f2c0: 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 e.** complete if
f2d0: 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 it ends with a
f2e0: 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 semicolon token
f2f0: 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 and is not a pre
f300: 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c fix of a.** well
f310: 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 -formed CREATE T
f320: 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 RIGGER statement
f330: 2e 20 20 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 . Semicolons th
f340: 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 at are embedded
f350: 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 within.** string
f360: 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f literals or quo
f370: 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e ted identifier n
f380: 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 ames or comments
f390: 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 are not.** inde
f3a0: 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 pendent tokens (
f3b0: 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 they are part of
f3c0: 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 the token in wh
f3d0: 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 ich they are.**
f3e0: 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 embedded) and th
f3f0: 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 us do not count
f400: 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 as a statement t
f410: 65 72 6d 69 6e 61 74 6f 72 2e 20 20 57 68 69 74 erminator. Whit
f420: 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f espace.** and co
f430: 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c mments that foll
f440: 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d ow the final sem
f450: 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 icolon are ignor
f460: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ed..**.** These
f470: 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
f480: 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 0 if the stateme
f490: 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 nt is incomplete
f4a0: 2e 20 20 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 . If a.** memor
f4b0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 y allocation fai
f4c0: 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f ls, then SQLITE_
f4d0: 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 NOMEM is returne
f4e0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 d..**.** These r
f4f0: 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 outines do not p
f500: 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 arse the SQL sta
f510: 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 tements thus.**
f520: 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 will not detect
f530: 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e syntactically in
f540: 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a correct SQL..**.
f550: 2a 2a 20 49 66 20 53 51 4c 69 74 65 20 68 61 73 ** If SQLite has
f560: 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 not been initia
f570: 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c lized using [sql
f580: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
f590: 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 )] prior .** to
f5a0: 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 invoking sqlite3
f5b0: 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 _complete16() th
f5c0: 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 en sqlite3_initi
f5d0: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b alize() is invok
f5e0: 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 ed.** automatica
f5f0: 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 lly by sqlite3_c
f600: 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 omplete16(). If
f610: 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 that initializa
f620: 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 tion fails,.** t
f630: 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 hen the return v
f640: 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 alue from sqlite
f650: 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 3_complete16() w
f660: 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a ill be non-zero.
f670: 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 ** regardless of
f680: 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
f690: 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 the input SQL is
f6a0: 20 63 6f 6d 70 6c 65 74 65 2e 0a 2a 2a 0a 2a 2a complete..**.**
f6b0: 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b Requirements: [
f6c0: 48 31 30 35 31 31 5d 20 5b 48 31 30 35 31 32 5d H10511] [H10512]
f6d0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 .**.** The input
f6e0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d to [sqlite3_com
f6f0: 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 plete()] must be
f700: 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 a zero-terminat
f710: 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 ed.** UTF-8 stri
f720: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e ng..**.** The in
f730: 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f put to [sqlite3_
f740: 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 complete16()] mu
f750: 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 st be a zero-ter
f760: 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 minated.** UTF-1
f770: 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 6 string in nati
f780: 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a ve byte order..*
f790: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f /.int sqlite3_co
f7a0: 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 mplete(const cha
f7b0: 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c r *sql);.int sql
f7c0: 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 ite3_complete16(
f7d0: 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 const void *sql)
f7e0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
f7f0: 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61 F: Register A Ca
f800: 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 llback To Handle
f810: 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 SQLITE_BUSY Err
f820: 6f 72 73 20 7b 48 31 32 33 31 30 7d 20 3c 53 34 ors {H12310} <S4
f830: 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 0400>.**.** This
f840: 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 routine sets a
f850: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
f860: 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 n that might be
f870: 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 invoked whenever
f880: 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 .** an attempt i
f890: 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 s made to open a
f8a0: 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 database table
f8b0: 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 that another thr
f8c0: 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 ead.** or proces
f8d0: 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a s has locked..**
f8e0: 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79 20 .** If the busy
f8f0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c callback is NULL
f900: 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 , then [SQLITE_B
f910: 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f USY] or [SQLITE_
f920: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a IOERR_BLOCKED].*
f930: 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d * is returned im
f940: 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 mediately upon e
f950: 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 ncountering the
f960: 6c 6f 63 6b 2e 20 49 66 20 74 68 65 20 62 75 73 lock. If the bus
f970: 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 y callback.** is
f980: 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 not NULL, then
f990: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c the callback wil
f9a0: 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 l be invoked wit
f9b0: 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e h two arguments.
f9c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 .**.** The first
f9d0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
f9e0: 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f handler is a co
f9f0: 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 py of the void*
fa00: 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a pointer which.**
fa10: 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72 is the third ar
fa20: 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 gument to sqlite
fa30: 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 3_busy_handler()
fa40: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 . The second ar
fa50: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 gument to.** the
fa60: 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 handler callbac
fa70: 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 k is the number
fa80: 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 of times that th
fa90: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 e busy handler h
faa0: 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b as.** been invok
fab0: 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b ed for this lock
fac0: 69 6e 67 20 65 76 65 6e 74 2e 20 20 49 66 20 74 ing event. If t
fad0: 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 he.** busy callb
fae0: 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 ack returns 0, t
faf0: 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 hen no additiona
fb00: 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d l attempts are m
fb10: 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 ade to.** access
fb20: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e the database an
fb30: 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 d [SQLITE_BUSY]
fb40: 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 or [SQLITE_IOERR
fb50: 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 _BLOCKED] is ret
fb60: 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 urned..** If the
fb70: 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
fb80: 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e s non-zero, then
fb90: 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 another attempt
fba0: 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f .** is made to o
fbb0: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 pen the database
fbc0: 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 for reading and
fbd0: 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 the cycle repea
fbe0: 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 ts..**.** The pr
fbf0: 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 esence of a busy
fc00: 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f handler does no
fc10: 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 t guarantee that
fc20: 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f it will be invo
fc30: 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 ked.** when ther
fc40: 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e e is lock conten
fc50: 74 69 6f 6e 2e 20 49 66 20 53 51 4c 69 74 65 20 tion. If SQLite
fc60: 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 determines that
fc70: 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 invoking the bus
fc80: 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 y.** handler cou
fc90: 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 ld result in a d
fca0: 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c eadlock, it will
fcb0: 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 go ahead and re
fcc0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 turn [SQLITE_BUS
fcd0: 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 Y].** or [SQLITE
fce0: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 _IOERR_BLOCKED]
fcf0: 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b instead of invok
fd00: 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e ing the busy han
fd10: 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 dler..** Conside
fd20: 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 r a scenario whe
fd30: 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 re one process i
fd40: 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 s holding a read
fd50: 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 lock that.** it
fd60: 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 is trying to pr
fd70: 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 omote to a reser
fd80: 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 ved lock and.**
fd90: 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 a second process
fda0: 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 is holding a re
fdb0: 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 served lock that
fdc0: 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a it is trying.**
fdd0: 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 to promote to a
fde0: 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b n exclusive lock
fdf0: 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f . The first pro
fe00: 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 cess cannot proc
fe10: 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 eed.** because i
fe20: 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 t is blocked by
fe30: 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 the second and t
fe40: 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 he second proces
fe50: 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 s cannot.** proc
fe60: 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 eed because it i
fe70: 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 s blocked by the
fe80: 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 first. If both
fe90: 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e processes.** in
fea0: 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 voke the busy ha
feb0: 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 ndlers, neither
fec0: 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 will make any pr
fed0: 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f ogress. Therefo
fee0: 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 re,.** SQLite re
fef0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 turns [SQLITE_BU
ff00: 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 SY] for the firs
ff10: 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e t process, hopin
ff20: 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 g that this.** w
ff30: 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 ill induce the f
ff40: 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 irst process to
ff50: 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 release its read
ff60: 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a lock and allow.
ff70: 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 ** the second pr
ff80: 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 ocess to proceed
ff90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 ..**.** The defa
ffa0: 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 ult busy callbac
ffb0: 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a k is NULL..**.**
ffc0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 The [SQLITE_BUS
ffd0: 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 Y] error is conv
ffe0: 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 erted to [SQLITE
fff0: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a _IOERR_BLOCKED].
10000 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 ** when SQLite i
10010 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 s in the middle
10020 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 of a large trans
10030 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c action where all
10040 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 the.** changes
10050 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 will not fit int
10060 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 o the in-memory
10070 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 cache. SQLite w
10080 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 ill.** already h
10090 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c old a RESERVED l
100a0 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 ock on the datab
100b0 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 ase file, but it
100c0 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f needs.** to pro
100d0 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 mote this lock t
100e0 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 o EXCLUSIVE so t
100f0 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c hat it can spill
10100 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 cache.** pages
10110 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 into the databas
10120 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 e file without h
10130 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e arm to concurren
10140 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 49 t.** readers. I
10150 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 f it is unable t
10160 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f o promote the lo
10170 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d ck, then the in-
10180 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 memory.** cache
10190 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 will be left in
101a0 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 an inconsistent
101b0 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 state and so the
101c0 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 error.** code i
101d0 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 s promoted from
101e0 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 the relatively b
101f0 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 enign [SQLITE_BU
10200 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f SY] to.** the mo
10210 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 re severe [SQLIT
10220 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d E_IOERR_BLOCKED]
10230 2e 20 20 54 68 69 73 20 65 72 72 6f 72 20 63 6f . This error co
10240 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 de promotion.**
10250 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 forces an automa
10260 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 tic rollback of
10270 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 the changes. Se
10280 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 e the.** <a href
10290 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f ="/cvstrac/wiki?
102a0 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c p=CorruptionFoll
102b0 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e owingBusyError">
102c0 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f .** CorruptionFo
102d0 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 llowingBusyError
102e0 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 </a> wiki page f
102f0 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 or a discussion
10300 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 of why.** this i
10310 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a s important..**.
10320 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c ** There can onl
10330 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 y be a single bu
10340 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e sy handler defin
10350 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b ed for each.** [
10360 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
10370 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 ion]. Setting a
10380 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 new busy handle
10390 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 r clears any.**
103a0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 previously set h
103b0 61 6e 64 6c 65 72 2e 20 20 4e 6f 74 65 20 74 68 andler. Note th
103c0 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 at calling [sqli
103d0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 te3_busy_timeout
103e0 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f ()].** will also
103f0 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 set or clear th
10400 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a e busy handler..
10410 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 **.** The busy c
10420 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e allback should n
10430 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 ot take any acti
10440 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 ons which modify
10450 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 the.** database
10460 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 connection that
10470 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 invoked the bus
10480 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 y handler. Any
10490 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 such actions.**
104a0 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 result in undefi
104b0 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a ned behavior..**
104c0 20 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 .** Requirement
104d0 73 3a 0a 2a 2a 20 5b 48 31 32 33 31 31 5d 20 5b s:.** [H12311] [
104e0 48 31 32 33 31 32 5d 20 5b 48 31 32 33 31 34 5d H12312] [H12314]
104f0 20 5b 48 31 32 33 31 36 5d 20 5b 48 31 32 33 31 [H12316] [H1231
10500 38 5d 0a 2a 2a 0a 2a 2a 20 41 20 62 75 73 79 20 8].**.** A busy
10510 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 handler must not
10520 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 close the datab
10530 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase connection.*
10540 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 * or [prepared s
10550 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 tatement] that i
10560 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 nvoked the busy
10570 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 handler..*/.int
10580 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e sqlite3_busy_han
10590 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 dler(sqlite3*, i
105a0 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 nt(*)(void*,int)
105b0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a , void*);../*.**
105c0 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 CAPI3REF: Set A
105d0 20 42 75 73 79 20 54 69 6d 65 6f 75 74 20 7b 48 Busy Timeout {H
105e0 31 32 33 34 30 7d 20 3c 53 34 30 34 31 30 3e 0a 12340} <S40410>.
105f0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
10600 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 ne sets a [sqlit
10610 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 e3_busy_handler
10620 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 | busy handler]
10630 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 that sleeps.** f
10640 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61 or a specified a
10650 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 mount of time wh
10660 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f en a table is lo
10670 63 6b 65 64 2e 20 20 54 68 65 20 68 61 6e 64 6c cked. The handl
10680 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 er.** will sleep
10690 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 multiple times
106a0 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 until at least "
106b0 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 ms" milliseconds
106c0 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 of sleeping.**
106d0 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 have accumulated
106e0 2e 20 7b 48 31 32 33 34 33 7d 20 41 66 74 65 72 . {H12343} After
106f0 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e "ms" millisecon
10700 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a ds of sleeping,.
10710 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 ** the handler r
10720 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 eturns 0 which c
10730 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 auses [sqlite3_s
10740 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e tep()] to return
10750 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 .** [SQLITE_BUSY
10760 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 ] or [SQLITE_IOE
10770 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a RR_BLOCKED]..**.
10780 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 ** Calling this
10790 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 routine with an
107a0 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 argument less th
107b0 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a an or equal to z
107c0 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 ero.** turns off
107d0 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 all busy handle
107e0 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 rs..**.** There
107f0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 can only be a si
10800 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 ngle busy handle
10810 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c r for a particul
10820 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 ar.** [database
10830 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 connection] any
10840 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 any given moment
10850 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 . If another bu
10860 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 sy handler.** wa
10870 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e s defined (usin
10880 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f g [sqlite3_busy_
10890 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f handler()]) prio
108a0 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 r to calling.**
108b0 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 this routine, th
108c0 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 at other busy ha
108d0 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 ndler is cleared
108e0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
108f0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 33 34 31 ents:.** [H12341
10900 5d 20 5b 48 31 32 33 34 33 5d 20 5b 48 31 32 33 ] [H12343] [H123
10910 34 34 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 44].*/.int sqlit
10920 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 e3_busy_timeout(
10930 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 sqlite3*, int ms
10940 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
10950 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 EF: Convenience
10960 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e Routines For Run
10970 6e 69 6e 67 20 51 75 65 72 69 65 73 20 7b 48 31 ning Queries {H1
10980 32 33 37 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2370} <S10000>.*
10990 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a *.** Definition:
109a0 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 A <b>result tab
109b0 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 le</b> is memory
109c0 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 data structure
109d0 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a created by the.*
109e0 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 * [sqlite3_get_t
109f0 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 able()] interfac
10a00 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 e. A result tab
10a10 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a le records the.*
10a20 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 * complete query
10a30 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e results from on
10a40 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 e or more querie
10a50 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 s..**.** The tab
10a60 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 le conceptually
10a70 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 has a number of
10a80 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 rows and columns
10a90 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 . But.** these
10aa0 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 numbers are not
10ab0 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 part of the resu
10ac0 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e lt table itself.
10ad0 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 These.** numbe
10ae0 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 rs are obtained
10af0 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 separately. Let
10b00 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 N be the number
10b10 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 of rows.** and
10b20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 M be the number
10b30 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a of columns..**.*
10b40 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 * A result table
10b50 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 is an array of
10b60 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f pointers to zero
10b70 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d -terminated UTF-
10b80 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 8 strings..** Th
10b90 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 ere are (N+1)*M
10ba0 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 elements in the
10bb0 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 array. The firs
10bc0 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 t M pointers poi
10bd0 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 nt.** to zero-te
10be0 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 rminated strings
10bf0 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 that contain t
10c00 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 he names of the
10c10 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 columns..** The
10c20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 remaining entrie
10c30 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 s all point to q
10c40 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e uery results. N
10c50 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c ULL values resul
10c60 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 t.** in NULL poi
10c70 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 nters. All othe
10c80 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 r values are in
10c90 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f their UTF-8 zero
10ca0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 -terminated.** s
10cb0 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 tring representa
10cc0 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 tion as returned
10cd0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c by [sqlite3_col
10ce0 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a umn_text()]..**.
10cf0 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c ** A result tabl
10d00 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 e might consist
10d10 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d of one or more m
10d20 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
10d30 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 s..** It is not
10d40 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 safe to pass a r
10d50 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 esult table dire
10d60 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 ctly to [sqlite3
10d70 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 _free()]..** A r
10d80 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 esult table shou
10d90 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 ld be deallocate
10da0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
10db0 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a _free_table()]..
10dc0 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61 6d **.** As an exam
10dd0 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c ple of the resul
10de0 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 t table format,
10df0 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 suppose a query
10e00 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 result.** is as
10e10 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c follows:.**.** <
10e20 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
10e30 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 .** Name
10e40 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 | Age.**
10e50 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d ---------
10e60 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a --------------.*
10e70 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 * Alice
10e80 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 | 43.**
10e90 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 Bob
10ea0 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 | 28.** C
10eb0 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a indy | 21.
10ec0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
10ed0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 quote>.**.** The
10ee0 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d re are two colum
10ef0 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 n (M==2) and thr
10f00 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 ee rows (N==3).
10f10 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 Thus the.** res
10f20 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 ult table has 8
10f30 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 entries. Suppos
10f40 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 e the result tab
10f50 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 le is stored.**
10f60 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 in an array name
10f70 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 s azResult. The
10f80 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 n azResult holds
10f90 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a this content:.*
10fa0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
10fb0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 ><pre>.**
10fc0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d azResult[0]
10fd0 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 = "Name";.**
10fe0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
10ff0 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 1;1] = "Age";.**
11000 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
11010 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 [2] = "Alice
11020 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
11030 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 esult[3] = "
11040 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 43";.** a
11050 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d zResult[4] =
11060 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 "Bob";.**
11070 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 azResult[5
11080 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 ] = "28";.**
11090 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
110a0 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a ;6] = "Cindy";.*
110b0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
110c0 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b t[7] = "21";
110d0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
110e0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 kquote>.**.** Th
110f0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 e sqlite3_get_ta
11100 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 ble() function e
11110 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 valuates one or
11120 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f more.** semicolo
11130 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 n-separated SQL
11140 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 statements in th
11150 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 e zero-terminate
11160 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e d UTF-8.** strin
11170 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 g of its 2nd par
11180 61 6d 65 74 65 72 2e 20 20 49 74 20 72 65 74 75 ameter. It retu
11190 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 rns a result tab
111a0 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 le to the.** poi
111b0 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 nter given in it
111c0 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e s 3rd parameter.
111d0 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 .**.** After the
111e0 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f calling functio
111f0 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 n has finished u
11200 73 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2c sing the result,
11210 20 69 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 70 61 it should.** pa
11220 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 ss the pointer t
11230 6f 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 o the result tab
11240 6c 65 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 le to sqlite3_fr
11250 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 ee_table() in or
11260 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 der to.** releas
11270 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 e the memory tha
11280 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 t was malloced.
11290 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 Because of the
112a0 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 way the.** [sqli
112b0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 te3_malloc()] ha
112c0 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c ppens within sql
112d0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
112e0 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a , the calling.**
112f0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e function must n
11300 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b ot try to call [
11310 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 sqlite3_free()]
11320 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a directly. Only.
11330 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ** [sqlite3_free
11340 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c _table()] is abl
11350 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 e to release the
11360 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 memory properly
11370 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a and safely..**.
11380 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 ** The sqlite3_g
11390 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 et_table() inter
113a0 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e face is implemen
113b0 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 ted as a wrapper
113c0 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 around.** [sqli
113d0 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 te3_exec()]. Th
113e0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 e sqlite3_get_ta
113f0 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f ble() routine do
11400 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 es not have acce
11410 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 ss.** to any int
11420 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 ernal data struc
11430 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e tures of SQLite.
11440 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 It uses only t
11450 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 he public.** int
11460 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 erface defined h
11470 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 ere. As a conse
11480 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 quence, errors t
11490 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 hat occur in the
114a0 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 .** wrapper laye
114b0 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 r outside of the
114c0 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 internal [sqlit
114d0 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 e3_exec()] call
114e0 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 are not.** refle
114f0 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 cted in subseque
11500 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c nt calls to [sql
11510 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 ite3_errcode()]
11520 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d or [sqlite3_errm
11530 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 sg()]..**.** Req
11540 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
11550 31 32 33 37 31 5d 20 5b 48 31 32 33 37 33 5d 20 12371] [H12373]
11560 5b 48 31 32 33 37 34 5d 20 5b 48 31 32 33 37 36 [H12374] [H12376
11570 5d 20 5b 48 31 32 33 37 39 5d 20 5b 48 31 32 33 ] [H12379] [H123
11580 38 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 82].*/.int sqlit
11590 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 e3_get_table(.
115a0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
115b0 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e /* An open
115c0 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 database */. c
115d0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c onst char *zSql,
115e0 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 /* SQL to b
115f0 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 e evaluated */.
11600 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 char ***pazResu
11610 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 lt, /* Result
11620 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a s of the query *
11630 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 /. int *pnRow,
11640 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d /* Num
11650 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f ber of result ro
11660 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 ws written here
11670 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 */. int *pnColu
11680 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 mn, /* Nu
11690 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 mber of result c
116a0 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 olumns written h
116b0 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a ere */. char **
116c0 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f pzErrmsg /
116d0 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 * Error msg writ
116e0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 ten here */.);.v
116f0 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 oid sqlite3_free
11700 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 _table(char **re
11710 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 sult);../*.** CA
11720 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 PI3REF: Formatte
11730 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e d String Printin
11740 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 37 g Functions {H17
11750 34 30 30 7d 20 3c 53 37 30 30 30 30 3e 3c 53 32 400} <S70000><S2
11760 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 0000>.**.** Thes
11770 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 e routines are w
11780 6f 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 orkalikes of the
11790 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 "printf()" fami
117a0 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a ly of functions.
117b0 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e ** from the stan
117c0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a dard C library..
117d0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
117e0 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 3_mprintf() and
117f0 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 sqlite3_vmprintf
11800 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 () routines writ
11810 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c e their.** resul
11820 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f ts into memory o
11830 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
11840 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e lite3_malloc()].
11850 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 .** The strings
11860 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 returned by thes
11870 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 e two routines s
11880 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 hould be.** rele
11890 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 ased by [sqlite3
118a0 5f 66 72 65 65 28 29 5d 2e 20 20 42 6f 74 68 20 _free()]. Both
118b0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
118c0 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 a.** NULL pointe
118d0 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 r if [sqlite3_ma
118e0 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c lloc()] is unabl
118f0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e e to allocate en
11900 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 ough.** memory t
11910 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c o hold the resul
11920 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a ting string..**.
11930 2a 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e ** In sqlite3_sn
11940 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 printf() routine
11950 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 is similar to "
11960 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d snprintf()" from
11970 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 .** the standard
11980 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 C library. The
11990 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 result is writt
119a0 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 en into the.** b
119b0 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 uffer supplied a
119c0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 s the second par
119d0 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a ameter whose siz
119e0 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a e is given by.**
119f0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
11a00 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 eter. Note that
11a10 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 the order of the
11a20 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 .** first two pa
11a30 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 rameters is reve
11a40 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e rsed from snprin
11a50 74 66 28 29 2e 20 20 54 68 69 73 20 69 73 20 61 tf(). This is a
11a60 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 n.** historical
11a70 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 accident that ca
11a80 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 nnot be fixed wi
11a90 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a thout breaking.*
11aa0 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 * backwards comp
11ab0 61 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65 atibility. Note
11ac0 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 also that sqlit
11ad0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a e3_snprintf().**
11ae0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
11af0 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 er to its buffer
11b00 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 instead of the
11b10 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 number of.** cha
11b20 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 racters actually
11b30 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 written into th
11b40 65 20 62 75 66 66 65 72 2e 20 20 57 65 20 61 64 e buffer. We ad
11b50 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 mit that.** the
11b60 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 number of charac
11b70 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 ters written wou
11b80 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 ld be a more use
11b90 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 ful return.** va
11ba0 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f lue but we canno
11bb0 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 t change the imp
11bc0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 lementation of s
11bd0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
11be0 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 ).** now without
11bf0 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 breaking compat
11c00 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 ibility..**.** A
11c10 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 s long as the bu
11c20 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 ffer size is gre
11c30 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 ater than zero,
11c40 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
11c50 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 ().** guarantees
11c60 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 that the buffer
11c70 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d is always zero-
11c80 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 terminated. The
11c90 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 first.** parame
11ca0 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 ter "n" is the t
11cb0 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 otal size of the
11cc0 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 buffer, includi
11cd0 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 ng space for.**
11ce0 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 the zero termina
11cf0 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e tor. So the lon
11d00 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 gest string that
11d10 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 can be complete
11d20 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 ly.** written wi
11d30 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 ll be n-1 charac
11d40 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ters..**.** Thes
11d50 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 e routines all i
11d60 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 mplement some ad
11d70 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 ditional formatt
11d80 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 ing.** options t
11d90 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 hat are useful f
11da0 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 or constructing
11db0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a SQL statements..
11dc0 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 ** All of the us
11dd0 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 ual printf() for
11de0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 matting options
11df0 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 apply. In addit
11e00 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 ion, there.** is
11e10 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c are "%q", "%Q",
11e20 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e and "%z" option
11e30 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 s..**.** The %q
11e40 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b option works lik
11e50 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 e %s in that it
11e60 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 substitutes a nu
11e70 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ll-terminated.**
11e80 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 string from the
11e90 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 argument list.
11ea0 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 But %q also dou
11eb0 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 bles every '\''
11ec0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 character..** %q
11ed0 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 is designed for
11ee0 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 use inside a st
11ef0 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 ring literal. B
11f00 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 y doubling each
11f10 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 '\''.** characte
11f20 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61 r it escapes tha
11f30 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 t character and
11f40 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 allows it to be
11f50 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a inserted into.**
11f60 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a the string..**.
11f70 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 ** For example,
11f80 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e assume the strin
11f90 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 g variable zText
11fa0 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 contains text a
11fb0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a s follows:.**.**
11fc0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
11fd0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 e>.** char *zTe
11fe0 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 xt = "It's a hap
11ff0 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 py day!";.** </p
12000 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
12010 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 .**.** One can u
12020 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 se this text in
12030 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 an SQL statement
12040 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a as follows:.**.
12050 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
12060 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a pre>.** char *z
12070 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 SQL = sqlite3_mp
12080 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e rintf("INSERT IN
12090 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 TO table VALUES(
120a0 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a '%q')", zText);.
120b0 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 ** sqlite3_exec
120c0 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c (db, zSQL, 0, 0,
120d0 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 0);.** sqlite3
120e0 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 _free(zSQL);.**
120f0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
12100 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 te>.**.** Becaus
12110 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 e the %q format
12120 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 string is used,
12130 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 the '\'' charact
12140 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 er in zText.** i
12150 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 s escaped and th
12160 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 e SQL generated
12170 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a is as follows:.*
12180 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
12190 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 ><pre>.** INSER
121a0 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 T INTO table1 VA
121b0 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61 LUES('It''s a ha
121c0 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f ppy day!').** </
121d0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
121e0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 >.**.** This is
121f0 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 correct. Had we
12200 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 used %s instead
12210 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 of %q, the gene
12220 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 rated SQL.** wou
12230 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c ld have looked l
12240 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 ike this:.**.**
12250 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
12260 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 >.** INSERT INT
12270 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 O table1 VALUES(
12280 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 'It's a happy da
12290 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c y!');.** </pre><
122a0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
122b0 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 ** This second e
122c0 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c xample is an SQL
122d0 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 syntax error.
122e0 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c As a general rul
122f0 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 e you should.**
12300 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e always use %q in
12310 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e stead of %s when
12320 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 inserting text
12330 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 into a string li
12340 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 teral..**.** The
12350 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 %Q option works
12360 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 like %q except
12370 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e it also adds sin
12380 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e gle quotes aroun
12390 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 d.** the outside
123a0 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 of the total st
123b0 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 ring. Additiona
123c0 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 lly, if the para
123d0 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 meter in the.**
123e0 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 argument list is
123f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
12400 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 %Q substitutes
12410 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 the text "NULL"
12420 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 (without.** sing
12430 6c 65 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c le quotes) in pl
12440 61 63 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70 ace of the %Q op
12450 74 69 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65 tion. So, for e
12460 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c xample, one coul
12470 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c d say:.**.** <bl
12480 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
12490 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 * char *zSQL =
124a0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
124b0 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 "INSERT INTO tab
124c0 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 le VALUES(%Q)",
124d0 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 zText);.** sqli
124e0 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 te3_exec(db, zSQ
124f0 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 L, 0, 0, 0);.**
12500 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 sqlite3_free(zS
12510 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f QL);.** </pre></
12520 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
12530 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 * The code above
12540 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 will render a c
12550 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 orrect SQL state
12560 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c ment in the zSQL
12570 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 .** variable eve
12580 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 n if the zText v
12590 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c ariable is a NUL
125a0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a L pointer..**.**
125b0 20 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 The "%z" format
125c0 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b ting option work
125d0 73 20 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 s exactly like "
125e0 25 73 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 %s" with the.**
125f0 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 addition that af
12600 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 ter the string h
12610 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 as been read and
12620 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 copied into.**
12630 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c the result, [sql
12640 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 ite3_free()] is
12650 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e called on the in
12660 70 75 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44 put string. {END
12670 7d 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d }.**.** Requirem
12680 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 34 30 33 ents:.** [H17403
12690 5d 20 5b 48 31 37 34 30 36 5d 20 5b 48 31 37 34 ] [H17406] [H174
126a0 30 37 5d 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 07].*/.char *sql
126b0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e ite3_mprintf(con
126c0 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 st char*,...);.c
126d0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 har *sqlite3_vmp
126e0 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 rintf(const char
126f0 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 *, va_list);.cha
12700 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 r *sqlite3_snpri
12710 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f ntf(int,char*,co
12720 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b nst char*, ...);
12730 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
12740 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 : Memory Allocat
12750 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 20 7b 48 ion Subsystem {H
12760 31 37 33 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 17300} <S20000>.
12770 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 **.** The SQLite
12780 20 63 6f 72 65 20 20 75 73 65 73 20 74 68 65 73 core uses thes
12790 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 e three routines
127a0 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 for all of its
127b0 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 own.** internal
127c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
127d0 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 n needs. "Core"
127e0 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 in the previous
127f0 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 sentence.** does
12800 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 not include ope
12810 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 rating-system sp
12820 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 ecific VFS imple
12830 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a mentation. The.
12840 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 ** Windows VFS u
12850 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f ses native mallo
12860 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 c() and free() f
12870 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f or some operatio
12880 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ns..**.** The sq
12890 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 lite3_malloc() r
128a0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 outine returns a
128b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c pointer to a bl
128c0 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 ock.** of memory
128d0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 at least N byte
128e0 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 s in length, whe
128f0 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 re N is the para
12900 6d 65 74 65 72 2e 0a 2a 2a 20 49 66 20 73 71 6c meter..** If sql
12910 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 ite3_malloc() is
12920 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 unable to obtai
12930 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 n sufficient fre
12940 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 e.** memory, it
12950 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 returns a NULL p
12960 6f 69 6e 74 65 72 2e 20 20 49 66 20 74 68 65 20 ointer. If the
12970 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a parameter N to.*
12980 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 * sqlite3_malloc
12990 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 () is zero or ne
129a0 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 gative then sqli
129b0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 te3_malloc() ret
129c0 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 urns.** a NULL p
129d0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 ointer..**.** Ca
129e0 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 lling sqlite3_fr
129f0 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e ee() with a poin
12a00 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 ter previously r
12a10 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 eturned.** by sq
12a20 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f lite3_malloc() o
12a30 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f r sqlite3_reallo
12a40 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 c() releases tha
12a50 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 t memory so.** t
12a60 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 hat it might be
12a70 72 65 75 73 65 64 2e 20 20 54 68 65 20 73 71 6c reused. The sql
12a80 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 ite3_free() rout
12a90 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f ine is.** a no-o
12aa0 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 p if is called w
12ab0 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 ith a NULL point
12ac0 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e er. Passing a N
12ad0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 ULL pointer.** t
12ae0 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 o sqlite3_free()
12af0 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 is harmless. A
12b00 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 fter being freed
12b10 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 , memory.** shou
12b20 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 ld neither be re
12b30 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 ad nor written.
12b40 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 Even reading pr
12b50 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a eviously freed.*
12b60 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 * memory might r
12b70 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 esult in a segme
12b80 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 ntation fault or
12b90 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 other severe er
12ba0 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 ror..** Memory c
12bb0 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 orruption, a seg
12bc0 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c mentation fault,
12bd0 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 or other severe
12be0 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 error.** might
12bf0 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 result if sqlite
12c00 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 3_free() is call
12c10 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 ed with a non-NU
12c20 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a LL pointer that.
12c30 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 ** was not obtai
12c40 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 ned from sqlite3
12c50 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c _malloc() or sql
12c60 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a ite3_realloc()..
12c70 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
12c80 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 3_realloc() inte
12c90 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 rface attempts t
12ca0 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 o resize a.** pr
12cb0 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ior memory alloc
12cc0 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c ation to be at l
12cd0 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 east N bytes, wh
12ce0 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 ere N is the.**
12cf0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
12d00 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c . The memory al
12d10 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 location to be r
12d20 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 esized is the fi
12d30 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 rst.** parameter
12d40 2e 20 20 49 66 20 74 68 65 20 66 69 72 73 74 20 . If the first
12d50 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
12d60 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a ite3_realloc().*
12d70 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e * is a NULL poin
12d80 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 ter then its beh
12d90 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 avior is identic
12da0 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a al to calling.**
12db0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
12dc0 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 N) where N is th
12dd0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
12de0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 er to sqlite3_re
12df0 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66 20 74 alloc()..** If t
12e00 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
12e10 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 ter to sqlite3_r
12e20 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f ealloc() is zero
12e30 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 or.** negative
12e40 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f then the behavio
12e50 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 r is exactly the
12e60 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 same as calling
12e70 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 .** sqlite3_free
12e80 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74 (P) where P is t
12e90 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
12ea0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 er to sqlite3_re
12eb0 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 73 71 6c 69 alloc()..** sqli
12ec0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 te3_realloc() re
12ed0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
12ee0 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f to a memory allo
12ef0 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 cation.** of at
12f00 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e least N bytes in
12f10 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 size or NULL if
12f20 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f sufficient memo
12f30 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c ry is unavailabl
12f40 65 2e 0a 2a 2a 20 49 66 20 4d 20 69 73 20 74 68 e..** If M is th
12f50 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 e size of the pr
12f60 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 ior allocation,
12f70 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 then min(N,M) by
12f80 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 tes.** of the pr
12f90 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 ior allocation a
12fa0 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 re copied into t
12fb0 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 he beginning of
12fc0 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a buffer returned.
12fd0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 ** by sqlite3_re
12fe0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 alloc() and the
12ff0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e prior allocation
13000 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 is freed..** If
13010 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
13020 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c () returns NULL,
13030 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 then the prior
13040 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 allocation.** is
13050 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a not freed..**.*
13060 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 * The memory ret
13070 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
13080 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 _malloc() and sq
13090 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a lite3_realloc().
130a0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 ** is always ali
130b0 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 gned to at least
130c0 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 an 8 byte bound
130d0 61 72 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a ary. {END}.**.**
130e0 20 54 68 65 20 64 65 66 61 75 6c 74 20 69 6d 70 The default imp
130f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 lementation of t
13100 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
13110 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 75 tion subsystem u
13120 73 65 73 0a 2a 2a 20 74 68 65 20 6d 61 6c 6c 6f ses.** the mallo
13130 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 c(), realloc() a
13140 6e 64 20 66 72 65 65 28 29 20 70 72 6f 76 69 64 nd free() provid
13150 65 64 20 62 79 20 74 68 65 20 73 74 61 6e 64 61 ed by the standa
13160 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a rd C library..**
13170 20 7b 48 31 37 33 38 32 7d 20 48 6f 77 65 76 65 {H17382} Howeve
13180 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 r, if SQLite is
13190 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 compiled with th
131a0 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 45 4d 4f e.** SQLITE_MEMO
131b0 52 59 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f RY_SIZE=<i>NNN</
131c0 69 3e 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f i> C preprocesso
131d0 72 20 6d 61 63 72 6f 20 28 77 68 65 72 65 20 3c r macro (where <
131e0 69 3e 4e 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69 73 20 i>NNN</i>.** is
131f0 61 6e 20 69 6e 74 65 67 65 72 29 2c 20 74 68 65 an integer), the
13200 6e 20 53 51 4c 69 74 65 20 63 72 65 61 74 65 20 n SQLite create
13210 61 20 73 74 61 74 69 63 20 61 72 72 61 79 20 6f a static array o
13220 66 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 3c 69 f at least.** <i
13230 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 74 65 73 20 69 >NNN</i> bytes i
13240 6e 20 73 69 7a 65 20 61 6e 64 20 75 73 65 73 20 n size and uses
13250 74 68 61 74 20 61 72 72 61 79 20 66 6f 72 20 61 that array for a
13260 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 ll of its dynami
13270 63 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f c.** memory allo
13280 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 cation needs. {E
13290 4e 44 7d 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 ND} Additional
132a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
132b0 20 6f 70 74 69 6f 6e 73 0a 2a 2a 20 6d 61 79 20 options.** may
132c0 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 be added in futu
132d0 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a re releases..**.
132e0 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 ** In SQLite ver
132f0 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 sion 3.5.0 and 3
13300 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 .5.1, it was pos
13310 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a sible to define.
13320 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d ** the SQLITE_OM
13330 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 IT_MEMORY_ALLOCA
13340 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 TION which would
13350 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 cause the built
13360 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 -in.** implement
13370 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 ation of these r
13380 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d outines to be om
13390 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 itted. That cap
133a0 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f ability.** is no
133b0 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 longer provided
133c0 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e . Only built-in
133d0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
133e0 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a rs can be used..
133f0 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 **.** The Window
13400 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c s OS interface l
13410 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 ayer calls.** th
13420 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 e system malloc(
13430 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 ) and free() dir
13440 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 ectly when conve
13450 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d rting.** filenam
13460 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 es between the U
13470 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 TF-8 encoding us
13480 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 ed by SQLite.**
13490 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c and whatever fil
134a0 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 ename encoding i
134b0 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 s used by the pa
134c0 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 rticular Windows
134d0 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e .** installation
134e0 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 . Memory alloca
134f0 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 tion errors are
13500 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a detected, but.**
13510 20 74 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 they are report
13520 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 ed back as [SQLI
13530 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a TE_CANTOPEN] or.
13540 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 ** [SQLITE_IOERR
13550 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 ] rather than [S
13560 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a QLITE_NOMEM]..**
13570 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
13580 3a 0a 2a 2a 20 5b 48 31 37 33 30 33 5d 20 5b 48 :.** [H17303] [H
13590 31 37 33 30 34 5d 20 5b 48 31 37 33 30 35 5d 20 17304] [H17305]
135a0 5b 48 31 37 33 30 36 5d 20 5b 48 31 37 33 31 30 [H17306] [H17310
135b0 5d 20 5b 48 31 37 33 31 32 5d 20 5b 48 31 37 33 ] [H17312] [H173
135c0 31 35 5d 20 5b 48 31 37 33 31 38 5d 0a 2a 2a 20 15] [H17318].**
135d0 5b 48 31 37 33 32 31 5d 20 5b 48 31 37 33 32 32 [H17321] [H17322
135e0 5d 20 5b 48 31 37 33 32 33 5d 0a 2a 2a 0a 2a 2a ] [H17323].**.**
135f0 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 The pointer arg
13600 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 uments to [sqlit
13610 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b e3_free()] and [
13620 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
13630 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 )].** must be ei
13640 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 ther NULL or els
13650 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 e pointers obtai
13660 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 ned from a prior
13670 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f .** invocation o
13680 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f f [sqlite3_mallo
13690 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 c()] or [sqlite3
136a0 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 _realloc()] that
136b0 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 have.** not yet
136c0 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a been released..
136d0 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 **.** The applic
136e0 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 ation must not r
136f0 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 ead or write any
13700 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c part of.** a bl
13710 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 ock of memory af
13720 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 ter it has been
13730 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a released using.*
13740 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 * [sqlite3_free(
13750 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 )] or [sqlite3_r
13760 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f ealloc()]..*/.vo
13770 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c id *sqlite3_mall
13780 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 oc(int);.void *s
13790 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 qlite3_realloc(v
137a0 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 oid*, int);.void
137b0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f sqlite3_free(vo
137c0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 id*);../*.** CAP
137d0 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c I3REF: Memory Al
137e0 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 locator Statisti
137f0 63 73 20 7b 48 31 37 33 37 30 7d 20 3c 53 33 30 cs {H17370} <S30
13800 32 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 210>.**.** SQLit
13810 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 e provides these
13820 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 two interfaces
13830 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e for reporting on
13840 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f the status.** o
13850 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
13860 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 alloc()], [sqlit
13870 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 e3_free()], and
13880 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
13890 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c ()].** routines,
138a0 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 which form the
138b0 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 built-in memory
138c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 allocation subsy
138d0 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 stem..**.** Requ
138e0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
138f0 37 33 37 31 5d 20 5b 48 31 37 33 37 33 5d 20 5b 7371] [H17373] [
13900 48 31 37 33 37 34 5d 20 5b 48 31 37 33 37 35 5d H17374] [H17375]
13910 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 .*/.sqlite3_int6
13920 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 4 sqlite3_memory
13930 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c _used(void);.sql
13940 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 ite3_int64 sqlit
13950 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
13960 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 ter(int resetFla
13970 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 g);../*.** CAPI3
13980 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 REF: Pseudo-Rand
13990 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 om Number Genera
139a0 74 6f 72 20 7b 48 31 37 33 39 30 7d 20 3c 53 32 tor {H17390} <S2
139b0 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 0000>.**.** SQLi
139c0 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 te contains a hi
139d0 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 gh-quality pseud
139e0 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 o-random number
139f0 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 generator (PRNG)
13a00 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 used to.** sele
13a10 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 ct random [ROWID
13a20 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 | ROWIDs] when
13a30 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 inserting new re
13a40 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 cords into a tab
13a50 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 le that.** alrea
13a60 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 dy uses the larg
13a70 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f est possible [RO
13a80 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 WID]. The PRNG
13a90 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 is also used for
13aa0 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e .** the build-in
13ab0 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 random() and ra
13ac0 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 ndomblob() SQL f
13ad0 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 unctions. This
13ae0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 interface allows
13af0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 .** applications
13b00 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 to access the s
13b10 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 ame PRNG for oth
13b20 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a er purposes..**.
13b30 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 ** A call to thi
13b40 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 s routine stores
13b50 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 N bytes of rand
13b60 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 omness into buff
13b70 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 er P..**.** The
13b80 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 first time this
13b90 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b routine is invok
13ba0 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 ed (either inter
13bb0 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 nally or by.** t
13bc0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 he application)
13bd0 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 the PRNG is seed
13be0 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e ed using randomn
13bf0 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 ess obtained.**
13c00 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d from the xRandom
13c10 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 ness method of t
13c20 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 he default [sqli
13c30 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e te3_vfs] object.
13c40 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73 75 62 73 65 .** On all subse
13c50 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e quent invocation
13c60 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 s, the pseudo-ra
13c70 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 ndomness is gene
13c80 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 rated.** interna
13c90 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 lly and without
13ca0 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 recourse to the
13cb0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 [sqlite3_vfs] xR
13cc0 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 andomness.** met
13cd0 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 hod..**.** Requi
13ce0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 rements:.** [H17
13cf0 33 39 32 5d 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 392].*/.void sql
13d00 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 ite3_randomness(
13d10 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b int N, void *P);
13d20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
13d30 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 : Compile-Time A
13d40 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c uthorization Cal
13d50 6c 62 61 63 6b 73 20 7b 48 31 32 35 30 30 7d 20 lbacks {H12500}
13d60 3c 53 37 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S70100>.**.** T
13d70 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 his routine regi
13d80 73 74 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a sters a authoriz
13d90 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 er callback with
13da0 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a a particular.**
13db0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
13dc0 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 ction], supplied
13dd0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
13de0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 gument..** The a
13df0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
13e00 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 ck is invoked as
13e10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
13e20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c are being compil
13e30 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 ed.** by [sqlite
13e40 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 3_prepare()] or
13e50 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 its variants [sq
13e60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
13e70 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
13e80 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e _prepare16()] an
13e90 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 d [sqlite3_prepa
13ea0 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 41 74 20 re16_v2()]. At
13eb0 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 various.** point
13ec0 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d s during the com
13ed0 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 pilation process
13ee0 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 , as logic is be
13ef0 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 ing created.** t
13f00 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 o perform variou
13f10 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 s actions, the a
13f20 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
13f30 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f ck is invoked to
13f40 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 .** see if those
13f50 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c actions are all
13f60 6f 77 65 64 2e 20 20 54 68 65 20 61 75 74 68 6f owed. The autho
13f70 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 rizer callback s
13f80 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 hould.** return
13f90 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 [SQLITE_OK] to a
13fa0 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c llow the action,
13fb0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d [SQLITE_IGNORE]
13fc0 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 to disallow the
13fd0 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 .** specific act
13fe0 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 ion but allow th
13ff0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
14000 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 to continue to b
14010 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f e.** compiled, o
14020 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 r [SQLITE_DENY]
14030 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 to cause the ent
14040 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ire SQL statemen
14050 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 t to be.** rejec
14060 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f ted with an erro
14070 72 2e 20 20 49 66 20 74 68 65 20 61 75 74 68 6f r. If the autho
14080 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 rizer callback r
14090 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 eturns.** any va
140a0 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b lue other than [
140b0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 SQLITE_IGNORE],
140c0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 [SQLITE_OK], or
140d0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a [SQLITE_DENY].**
140e0 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 then the [sqlit
140f0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
14100 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 or equivalent c
14110 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 all that trigger
14120 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 ed.** the author
14130 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 izer will fail w
14140 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 ith an error mes
14150 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e sage..**.** When
14160 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 the callback re
14170 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b turns [SQLITE_OK
14180 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 ], that means th
14190 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 e operation.** r
141a0 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 equested is ok.
141b0 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 When the callba
141c0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ck returns [SQLI
141d0 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a TE_DENY], the.**
141e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
141f0 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 e_v2()] or equiv
14200 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 alent call that
14210 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a triggered the.**
14220 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c authorizer will
14230 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 fail with an er
14240 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c ror message expl
14250 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 aining that.** a
14260 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e ccess is denied.
14270 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 .**.** The firs
14280 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 t parameter to t
14290 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
142a0 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 llback is a copy
142b0 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a of the third.**
142c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
142d0 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 e sqlite3_set_au
142e0 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 thorizer() inter
142f0 66 61 63 65 2e 20 54 68 65 20 73 65 63 6f 6e 64 face. The second
14300 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f parameter.** to
14310 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 the callback is
14320 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c an integer [SQL
14330 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f ITE_COPY | actio
14340 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 n code] that spe
14350 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 cifies.** the pa
14360 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 rticular action
14370 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 to be authorized
14380 2e 20 54 68 65 20 74 68 69 72 64 20 74 68 72 6f . The third thro
14390 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 ugh sixth parame
143a0 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 ters.** to the c
143b0 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f allback are zero
143c0 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 -terminated stri
143d0 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e ngs that contain
143e0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 additional.** d
143f0 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 etails about the
14400 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 action to be au
14410 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 thorized..**.**
14420 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f If the action co
14430 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 de is [SQLITE_RE
14440 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 AD].** and the c
14450 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
14460 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 [SQLITE_IGNORE]
14470 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 then the.** [pre
14480 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
14490 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f statement is co
144a0 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 nstructed to sub
144b0 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c stitute.** a NUL
144c0 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 L value in place
144d0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f of the table co
144e0 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 lumn that would
144f0 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 have.** been rea
14500 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d d if [SQLITE_OK]
14510 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e had been return
14520 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 ed. The [SQLITE
14530 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 _IGNORE].** retu
14540 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 rn can be used t
14550 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 o deny an untrus
14560 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 ted user access
14570 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a to individual.**
14580 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 columns of a ta
14590 62 6c 65 2e 0a 2a 2a 20 49 66 20 74 68 65 20 61 ble..** If the a
145a0 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 ction code is [S
145b0 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e QLITE_DELETE] an
145c0 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 d the callback r
145d0 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 eturns.** [SQLIT
145e0 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 E_IGNORE] then t
145f0 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 he [DELETE] oper
14600 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 ation proceeds b
14610 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 ut the.** [trunc
14620 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e ate optimization
14630 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e ] is disabled an
14640 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 d all rows are d
14650 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 eleted individua
14660 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 lly..**.** An au
14670 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 thorizer is used
14680 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 when [sqlite3_p
14690 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 repare | prepari
146a0 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 ng].** SQL state
146b0 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e ments from an un
146c0 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 trusted source,
146d0 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 to ensure that t
146e0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
146f0 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 s.** do not try
14700 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 to access data t
14710 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f hey are not allo
14720 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 wed to see, or t
14730 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a hat they do not.
14740 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 ** try to execut
14750 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 e malicious stat
14760 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 ements that dama
14770 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e ge the database.
14780 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 For.** example
14790 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e , an application
147a0 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 may allow a use
147b0 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 r to enter arbit
147c0 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 rary.** SQL quer
147d0 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 ies for evaluati
147e0 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 on by a database
147f0 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 . But the appli
14800 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e cation does.** n
14810 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 ot want the user
14820 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d to be able to m
14830 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 ake arbitrary ch
14840 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 anges to the.**
14850 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 database. An au
14860 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 thorizer could t
14870 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c hen be put in pl
14880 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a ace while the.**
14890 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 user-entered SQ
148a0 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 L is being [sqli
148b0 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 te3_prepare | pr
148c0 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 epared] that.**
148d0 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 disallows everyt
148e0 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c hing except [SEL
148f0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e ECT] statements.
14900 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 .**.** Applicati
14910 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f ons that need to
14920 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f process SQL fro
14930 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 m untrusted sour
14940 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 ces.** might als
14950 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 o consider lower
14960 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d ing resource lim
14970 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 its using [sqlit
14980 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 e3_limit()].** a
14990 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 nd limiting data
149a0 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 base size using
149b0 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f the [max_page_co
149c0 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a unt] [PRAGMA].**
149d0 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 in addition to
149e0 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 using an authori
149f0 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 zer..**.** Only
14a00 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 a single authori
14a10 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c zer can be in pl
14a20 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 ace on a databas
14a30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
14a40 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 at a time. Each
14a50 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
14a60 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 _set_authorizer
14a70 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a overrides the.**
14a80 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20 previous call.
14a90 20 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 Disable the aut
14aa0 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 horizer by insta
14ab0 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c lling a NULL cal
14ac0 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 lback..** The au
14ad0 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 thorizer is disa
14ae0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e bled by default.
14af0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f .**.** The autho
14b00 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d rizer callback m
14b10 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 ust not do anyth
14b20 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f ing that will mo
14b30 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 dify.** the data
14b40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
14b50 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 that invoked the
14b60 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
14b70 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 back..** Note th
14b80 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 at [sqlite3_prep
14b90 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 are_v2()] and [s
14ba0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 qlite3_step()] b
14bb0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 oth modify their
14bc0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
14bd0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 nections for the
14be0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 meaning of "mod
14bf0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 ify" in this par
14c00 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 57 68 agraph..**.** Wh
14c10 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 en [sqlite3_prep
14c20 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 are_v2()] is use
14c30 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 d to prepare a s
14c40 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a tatement, the.**
14c50 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 statement might
14c60 20 62 65 20 72 65 70 72 65 70 61 72 65 64 20 64 be reprepared d
14c70 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 uring [sqlite3_s
14c80 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 tep()] due to a
14c90 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 .** schema chang
14ca0 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 e. Hence, the a
14cb0 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
14cc0 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 d ensure that th
14cd0 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 e.** correct aut
14ce0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
14cf0 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 remains in plac
14d00 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 e during the [sq
14d10 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a lite3_step()]..*
14d20 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 *.** Note that t
14d30 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
14d40 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
14d50 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a d only during.**
14d60 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
14d70 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 e()] or its vari
14d80 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 ants. Authoriza
14d90 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 tion is not.** p
14da0 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 erformed during
14db0 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 statement evalua
14dc0 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 tion in [sqlite3
14dd0 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 _step()], unless
14de0 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e .** as stated in
14df0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 the previous pa
14e00 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 ragraph, sqlite3
14e10 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a _step() invokes.
14e20 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 ** sqlite3_prepa
14e30 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 re_v2() to repre
14e40 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 pare a statement
14e50 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 after a schema
14e60 63 68 61 6e 67 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 change..**.** Re
14e70 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
14e80 48 31 32 35 30 31 5d 20 5b 48 31 32 35 30 32 5d H12501] [H12502]
14e90 20 5b 48 31 32 35 30 33 5d 20 5b 48 31 32 35 30 [H12503] [H1250
14ea0 34 5d 20 5b 48 31 32 35 30 35 5d 20 5b 48 31 32 4] [H12505] [H12
14eb0 35 30 36 5d 20 5b 48 31 32 35 30 37 5d 20 5b 48 506] [H12507] [H
14ec0 31 32 35 31 30 5d 0a 2a 2a 20 5b 48 31 32 35 31 12510].** [H1251
14ed0 31 5d 20 5b 48 31 32 35 31 32 5d 20 5b 48 31 32 1] [H12512] [H12
14ee0 35 32 30 5d 20 5b 48 31 32 35 32 31 5d 20 5b 48 520] [H12521] [H
14ef0 31 32 35 32 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 12522].*/.int sq
14f00 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
14f10 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a izer(. sqlite3*
14f20 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 ,. int (*xAuth)
14f30 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 (void*,int,const
14f40 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 char*,const cha
14f50 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 r*,const char*,c
14f60 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 onst char*),. v
14f70 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 oid *pUserData.)
14f80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
14f90 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 F: Authorizer Re
14fa0 74 75 72 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 turn Codes {H125
14fb0 39 30 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 90} <H12500>.**.
14fc0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f ** The [sqlite3_
14fd0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c set_authorizer |
14fe0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
14ff0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d back function] m
15000 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 ust.** return ei
15010 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d ther [SQLITE_OK]
15020 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 or one of these
15030 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 two constants i
15040 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 n order.** to si
15050 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 gnal SQLite whet
15060 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 her or not the a
15070 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 ction is permitt
15080 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 ed. See the.**
15090 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 [sqlite3_set_aut
150a0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 horizer | author
150b0 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 izer documentati
150c0 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e on] for addition
150d0 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f al.** informatio
150e0 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 n..*/.#define SQ
150f0 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 LITE_DENY 1
15100 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c /* Abort the SQL
15110 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 statement with
15120 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 an error */.#def
15130 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 ine SQLITE_IGNOR
15140 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 E 2 /* Don't a
15150 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 llow access, but
15160 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 don't generate
15170 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a an error */../*.
15180 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 ** CAPI3REF: Aut
15190 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 horizer Action C
151a0 6f 64 65 73 20 7b 48 31 32 35 35 30 7d 20 3c 48 odes {H12550} <H
151b0 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 12500>.**.** The
151c0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
151d0 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 thorizer()] inte
151e0 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 rface registers
151f0 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 a callback funct
15200 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 ion.** that is i
15210 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 nvoked to author
15220 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 ize certain SQL
15230 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e statement action
15240 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e s. The.** secon
15250 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 d parameter to t
15260 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 he callback is a
15270 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 n integer code t
15280 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a hat specifies.**
15290 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 what action is
152a0 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 being authorized
152b0 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 . These are the
152c0 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 integer action
152d0 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 codes that.** th
152e0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
152f0 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 lback may be pas
15300 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 sed..**.** These
15310 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c action code val
15320 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 ues signify what
15330 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 kind of operati
15340 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 on is to be.** a
15350 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 uthorized. The
15360 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 3rd and 4th para
15370 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 meters to the au
15380 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 thorization.** c
15390 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
153a0 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 will be paramet
153b0 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 ers or NULL depe
153c0 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f nding on which o
153d0 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 f these.** codes
153e0 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 is used as the
153f0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
15400 2e 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d . The 5th param
15410 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 eter to the.** a
15420 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
15430 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f ck is the name o
15440 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 f the database (
15450 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a "main", "temp",.
15460 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c ** etc.) if appl
15470 69 63 61 62 6c 65 2e 20 20 54 68 65 20 36 74 68 icable. The 6th
15480 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
15490 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
154a0 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 lback.** is the
154b0 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 name of the inne
154c0 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f r-most trigger o
154d0 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 r view that is r
154e0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a esponsible for.*
154f0 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 * the access att
15500 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 empt or NULL if
15510 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 this access atte
15520 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 mpt is directly
15530 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 from.** top-leve
15540 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a l SQL code..**.*
15550 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
15560 2a 2a 20 5b 48 31 32 35 35 31 5d 20 5b 48 31 32 ** [H12551] [H12
15570 35 35 32 5d 20 5b 48 31 32 35 35 33 5d 20 5b 48 552] [H12553] [H
15580 31 32 35 35 34 5d 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 12554].*/./*****
15590 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
155a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
155b0 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a ****** 3rd *****
155c0 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a ******* 4th ****
155d0 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 *******/.#define
155e0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 SQLITE_CREATE_I
155f0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 NDEX 1
15600 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 /* Index Name
15610 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 Table Name
15620 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
15630 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 SQLITE_CREATE_TA
15640 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 BLE 2
15650 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
15660 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
15670 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
15680 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d QLITE_CREATE_TEM
15690 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 P_INDEX 3
156a0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 /* Index Name
156b0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
156c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
156d0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 LITE_CREATE_TEMP
156e0 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f _TABLE 4 /
156f0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
15700 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
15710 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
15720 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f ITE_CREATE_TEMP_
15730 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a TRIGGER 5 /*
15740 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 Trigger Name
15750 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
15760 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
15770 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 TE_CREATE_TEMP_V
15780 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 IEW 6 /*
15790 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 View Name
157a0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
157b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
157c0 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 E_CREATE_TRIGGER
157d0 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 7 /* T
157e0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 rigger Name T
157f0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
15800 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
15810 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 _CREATE_VIEW
15820 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 8 /* Vi
15830 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 ew Name NU
15840 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
15850 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
15860 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 DELETE
15870 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 9 /* Tab
15880 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
15890 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
158a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
158b0 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 ROP_INDEX
158c0 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 10 /* Inde
158d0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c x Name Tabl
158e0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
158f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
15900 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 OP_TABLE
15910 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 11 /* Table
15920 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
15930 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
15940 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
15950 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 P_TEMP_INDEX
15960 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 12 /* Index
15970 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 Name Table
15980 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
15990 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
159a0 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 _TEMP_TABLE
159b0 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 13 /* Table N
159c0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
159d0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
159e0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
159f0 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 TEMP_TRIGGER
15a00 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 14 /* Trigger
15a10 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 Name Table Na
15a20 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
15a30 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
15a40 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 EMP_VIEW 1
15a50 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 5 /* View Name
15a60 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
15a70 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
15a80 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 e SQLITE_DROP_TR
15a90 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 IGGER 16
15aa0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 /* Trigger Na
15ab0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 me Table Name
15ac0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
15ad0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 SQLITE_DROP_VIE
15ae0 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 W 17
15af0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 /* View Name
15b00 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
15b10 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
15b20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 SQLITE_INSERT
15b30 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 18
15b40 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
15b50 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
15b60 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
15b70 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 QLITE_PRAGMA
15b80 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 19
15b90 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 /* Pragma Name
15ba0 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 1st arg or NU
15bb0 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 LL */.#define SQ
15bc0 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 LITE_READ
15bd0 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 20 /
15be0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
15bf0 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 Column Name
15c00 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
15c10 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 ITE_SELECT
15c20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 21 /*
15c30 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
15c40 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
15c50 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
15c60 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 TE_TRANSACTION
15c70 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 22 /*
15c80 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 Operation
15c90 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
15ca0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
15cb0 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 E_UPDATE
15cc0 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 23 /* T
15cd0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 able Name C
15ce0 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a olumn Name *
15cf0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
15d00 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 _ATTACH
15d10 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 24 /* Fi
15d20 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 lename NU
15d30 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
15d40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
15d50 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 DETACH
15d60 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 25 /* Dat
15d70 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c abase Name NUL
15d80 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
15d90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
15da0 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 LTER_TABLE
15db0 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 26 /* Data
15dc0 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c base Name Tabl
15dd0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
15de0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 define SQLITE_RE
15df0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 INDEX
15e00 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 27 /* Index
15e10 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
15e20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
15e30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 efine SQLITE_ANA
15e40 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 LYZE
15e50 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 28 /* Table
15e60 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
15e70 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
15e80 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
15e90 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 TE_VTABLE
15ea0 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 29 /* Table N
15eb0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 ame Module
15ec0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 Name */.#def
15ed0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
15ee0 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 VTABLE
15ef0 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 30 /* Table Na
15f00 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e me Module N
15f10 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 ame */.#defi
15f20 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 ne SQLITE_FUNCTI
15f30 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 ON 3
15f40 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 1 /* NULL
15f50 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 Function
15f60 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e Name */.#defin
15f70 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 e SQLITE_SAVEPOI
15f80 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 NT 32
15f90 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 /* Operation
15fa0 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 Savepoint
15fb0 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 Name */.#define
15fc0 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 SQLITE_COPY
15fd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 0
15fe0 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 /* No longer u
15ff0 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 sed */../*.** CA
16000 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 PI3REF: Tracing
16010 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 And Profiling Fu
16020 6e 63 74 69 6f 6e 73 20 7b 48 31 32 32 38 30 7d nctions {H12280}
16030 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 20 45 58 50 <S60400>.** EXP
16040 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 ERIMENTAL.**.**
16050 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
16060 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b egister callback
16070 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 functions that
16080 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a can be used for.
16090 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 ** tracing and p
160a0 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 rofiling the exe
160b0 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 cution of SQL st
160c0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 atements..**.**
160d0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e The callback fun
160e0 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 ction registered
160f0 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 by sqlite3_trac
16100 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 e() is invoked a
16110 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d t.** various tim
16120 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 es when an SQL s
16130 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e tatement is bein
16140 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 g run by [sqlite
16150 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 3_step()]..** Th
16160 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 e callback retur
16170 6e 73 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 ns a UTF-8 rende
16180 72 69 6e 67 20 6f 66 20 74 68 65 20 53 51 4c 20 ring of the SQL
16190 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 0a 2a statement text.*
161a0 2a 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 * as the stateme
161b0 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 nt first begins
161c0 65 78 65 63 75 74 69 6e 67 2e 20 20 41 64 64 69 executing. Addi
161d0 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 tional callbacks
161e0 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 occur.** as eac
161f0 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 h triggered subp
16200 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 rogram is entere
16210 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b d. The callback
16220 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a s for triggers.*
16230 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d * contain a UTF-
16240 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 8 SQL comment th
16250 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 at identifies th
16260 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a e trigger..**.**
16270 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 The callback fu
16280 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 nction registere
16290 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f d by sqlite3_pro
162a0 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 file() is invoke
162b0 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c d.** as each SQL
162c0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 statement finis
162d0 68 65 73 2e 20 20 54 68 65 20 70 72 6f 66 69 6c hes. The profil
162e0 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 e callback conta
162f0 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 ins.** the origi
16300 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 nal statement te
16310 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 xt and an estima
16320 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b te of wall-clock
16330 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 time.** of how
16340 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d long that statem
16350 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e ent took to run.
16360 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
16370 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 38 31 5d nts:.** [H12281]
16380 20 5b 48 31 32 32 38 32 5d 20 5b 48 31 32 32 38 [H12282] [H1228
16390 33 5d 20 5b 48 31 32 32 38 34 5d 20 5b 48 31 32 3] [H12284] [H12
163a0 32 38 35 5d 20 5b 48 31 32 32 38 37 5d 20 5b 48 285] [H12287] [H
163b0 31 32 32 38 38 5d 20 5b 48 31 32 32 38 39 5d 0a 12288] [H12289].
163c0 2a 2a 20 5b 48 31 32 32 39 30 5d 0a 2a 2f 0a 53 ** [H12290].*/.S
163d0 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 QLITE_EXPERIMENT
163e0 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 AL void *sqlite3
163f0 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c _trace(sqlite3*,
16400 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 void(*xTrace)(v
16410 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a oid*,const char*
16420 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 ), void*);.SQLIT
16430 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 E_EXPERIMENTAL v
16440 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f oid *sqlite3_pro
16450 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 file(sqlite3*,.
16460 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 void(*xProfile
16470 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 )(void*,const ch
16480 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 ar*,sqlite3_uint
16490 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 64), void*);../*
164a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 .** CAPI3REF: Qu
164b0 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c ery Progress Cal
164c0 6c 62 61 63 6b 73 20 7b 48 31 32 39 31 30 7d 20 lbacks {H12910}
164d0 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S60400>.**.** T
164e0 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 his routine conf
164f0 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62 61 63 igures a callbac
16500 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 k function - the
16510 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 63 61 6c .** progress cal
16520 6c 62 61 63 6b 20 2d 20 74 68 61 74 20 69 73 20 lback - that is
16530 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 invoked periodic
16540 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 ally during long
16550 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c .** running call
16560 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 s to [sqlite3_ex
16570 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f ec()], [sqlite3_
16580 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b step()] and.** [
16590 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
165a0 65 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d 70 6c e()]. An exampl
165b0 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a e use for this.*
165c0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 * interface is t
165d0 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 o keep a GUI upd
165e0 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 ated during a la
165f0 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a rge query..**.**
16600 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 If the progress
16610 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
16620 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 s non-zero, the
16630 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 operation is.**
16640 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 interrupted. Th
16650 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 is feature can b
16660 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d e used to implem
16670 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c ent a.** "Cancel
16680 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 " button on a GU
16690 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f I progress dialo
166a0 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 g box..**.** The
166b0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 progress handle
166c0 72 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e r must not do an
166d0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c ything that will
166e0 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 modify.** the d
166f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
16700 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 on that invoked
16710 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e the progress han
16720 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 dler..** Note th
16730 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 at [sqlite3_prep
16740 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 are_v2()] and [s
16750 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 qlite3_step()] b
16760 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 oth modify their
16770 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
16780 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 nections for the
16790 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 meaning of "mod
167a0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 ify" in this par
167b0 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 agraph..**.** Re
167c0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
167d0 48 31 32 39 31 31 5d 20 5b 48 31 32 39 31 32 5d H12911] [H12912]
167e0 20 5b 48 31 32 39 31 33 5d 20 5b 48 31 32 39 31 [H12913] [H1291
167f0 34 5d 20 5b 48 31 32 39 31 35 5d 20 5b 48 31 32 4] [H12915] [H12
16800 39 31 36 5d 20 5b 48 31 32 39 31 37 5d 20 5b 48 916] [H12917] [H
16810 31 32 39 31 38 5d 0a 2a 2a 0a 2a 2f 0a 76 6f 69 12918].**.*/.voi
16820 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 d sqlite3_progre
16830 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 ss_handler(sqlit
16840 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 e3*, int, int(*)
16850 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b (void*), void*);
16860 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
16870 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 : Opening A New
16880 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 Database Connect
16890 69 6f 6e 20 7b 48 31 32 37 30 30 7d 20 3c 53 34 ion {H12700} <S4
168a0 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 0200>.**.** Thes
168b0 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 e routines open
168c0 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 an SQLite databa
168d0 73 65 20 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 se file whose na
168e0 6d 65 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 me is given by t
168f0 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 he.** filename a
16900 72 67 75 6d 65 6e 74 2e 20 54 68 65 20 66 69 6c rgument. The fil
16910 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 ename argument i
16920 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 s interpreted as
16930 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 UTF-8 for.** sq
16940 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 lite3_open() and
16950 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
16960 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 () and as UTF-16
16970 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 in the native b
16980 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 yte.** order for
16990 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 sqlite3_open16(
169a0 29 2e 20 41 20 5b 64 61 74 61 62 61 73 65 20 63 ). A [database c
169b0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c onnection] handl
169c0 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 e is usually.**
169d0 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 returned in *ppD
169e0 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 b, even if an er
169f0 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 ror occurs. The
16a00 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 only exception
16a10 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 is that.** if SQ
16a20 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 Lite is unable t
16a30 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 o allocate memor
16a40 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 y to hold the [s
16a50 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a qlite3] object,.
16a60 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 ** a NULL will b
16a70 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a e written into *
16a80 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 ppDb instead of
16a90 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
16aa0 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 [sqlite3].** ob
16ab0 6a 65 63 74 2e 20 49 66 20 74 68 65 20 64 61 74 ject. If the dat
16ac0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 abase is opened
16ad0 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 (and/or created)
16ae0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 successfully, t
16af0 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f hen.** [SQLITE_O
16b00 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 K] is returned.
16b10 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 Otherwise an [e
16b20 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 rror code] is re
16b30 74 75 72 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20 turned. The.**
16b40 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 [sqlite3_errmsg(
16b50 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 )] or [sqlite3_e
16b60 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 rrmsg16()] routi
16b70 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 nes can be used
16b80 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 to obtain.** an
16b90 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 English language
16ba0 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 description of
16bb0 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a the error..**.**
16bc0 20 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 The default enc
16bd0 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 oding for the da
16be0 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 tabase will be U
16bf0 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 TF-8 if.** sqlit
16c00 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c e3_open() or sql
16c10 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 ite3_open_v2() i
16c20 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 s called and.**
16c30 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 UTF-16 in the na
16c40 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 tive byte order
16c50 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 if sqlite3_open1
16c60 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 6() is used..**.
16c70 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f ** Whether or no
16c80 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 t an error occur
16c90 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 s when it is ope
16ca0 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a ned, resources.*
16cb0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 * associated wit
16cc0 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 h the [database
16cd0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 connection] hand
16ce0 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c le should be rel
16cf0 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 eased by.** pass
16d00 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 ing it to [sqlit
16d10 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e e3_close()] when
16d20 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 it is no longer
16d30 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a required..**.**
16d40 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 The sqlite3_ope
16d50 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 n_v2() interface
16d60 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 works like sqli
16d70 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 te3_open().** ex
16d80 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 cept that it acc
16d90 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f epts two additio
16da0 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 nal parameters f
16db0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f or additional co
16dc0 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 ntrol.** over th
16dd0 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 e new database c
16de0 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 onnection. The
16df0 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 flags parameter
16e00 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a can take one of.
16e10 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 ** the following
16e20 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f three values, o
16e30 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e ptionally combin
16e40 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 ed with the .**
16e50 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d [SQLITE_OPEN_NOM
16e60 55 54 45 58 5d 20 6f 72 20 5b 53 51 4c 49 54 45 UTEX] or [SQLITE
16e70 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d _OPEN_FULLMUTEX]
16e80 20 66 6c 61 67 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 flags:.**.** <d
16e90 6c 3e 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 l>.** <dt>[SQLIT
16ea0 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d E_OPEN_READONLY]
16eb0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
16ec0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
16ed0 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 ned in read-only
16ee0 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 mode. If the d
16ef0 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 atabase does not
16f00 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 .** already exis
16f10 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 t, an error is r
16f20 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a eturned.</dd>.**
16f30 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f .** <dt>[SQLITE_
16f40 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c OPEN_READWRITE]<
16f50 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
16f60 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e database is open
16f70 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 ed for reading a
16f80 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f nd writing if po
16f90 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 ssible, or readi
16fa0 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 ng.** only if th
16fb0 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 e file is write
16fc0 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 protected by the
16fd0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 operating syste
16fe0 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a m. In either.**
16ff0 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61 case the databa
17000 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 se must already
17010 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 exist, otherwise
17020 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 an error is ret
17030 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a urned.</dd>.**.*
17040 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 * <dt>[SQLITE_OP
17050 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 EN_READWRITE] |
17060 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 [SQLITE_OPEN_CRE
17070 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 ATE]</dt>.** <dd
17080 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 >The database is
17090 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 opened for read
170a0 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c ing and writing,
170b0 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 73 20 and is creates
170c0 69 74 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 it if.** it does
170d0 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 not already exi
170e0 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 st. This is the
170f0 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 behavior that is
17100 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 always used for
17110 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e .** sqlite3_open
17120 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f () and sqlite3_o
17130 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 0a 2a 2a pen16().</dd>.**
17140 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 </dl>.**.** If
17150 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 the 3rd paramete
17160 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 r to sqlite3_ope
17170 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e n_v2() is not on
17180 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 e of the.** comb
17190 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 inations shown a
171a0 62 6f 76 65 20 6f 72 20 6f 6e 65 20 6f 66 20 74 bove or one of t
171b0 68 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 he combinations
171c0 73 68 6f 77 6e 20 61 62 6f 76 65 20 63 6f 6d 62 shown above comb
171d0 69 6e 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 ined.** with the
171e0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f [SQLITE_OPEN_NO
171f0 4d 55 54 45 58 5d 20 6f 72 20 5b 53 51 4c 49 54 MUTEX] or [SQLIT
17200 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 E_OPEN_FULLMUTEX
17210 5d 20 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 6e ] flags,.** then
17220 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
17230 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
17240 2a 20 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 * If the [SQLITE
17250 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 _OPEN_NOMUTEX] f
17260 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e lag is set, then
17270 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
17280 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e nnection.** open
17290 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 s in the multi-t
172a0 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 hread [threading
172b0 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 mode] as long a
172c0 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 s the single-thr
172d0 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 ead.** mode has
172e0 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 not been set at
172f0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 compile-time or
17300 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 49 66 20 start-time. If
17310 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f the.** [SQLITE_O
17320 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 PEN_FULLMUTEX] f
17330 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 lag is set then
17340 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
17350 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a nection opens.**
17360 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a in the serializ
17370 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ed [threading mo
17380 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c de] unless singl
17390 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 e-thread was.**
173a0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 previously selec
173b0 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 ted at compile-t
173c0 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d ime or start-tim
173d0 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 e..**.** If the
173e0 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 filename is ":me
173f0 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 mory:", then a p
17400 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 rivate, temporar
17410 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 y in-memory data
17420 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 base.** is creat
17430 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 ed for the conne
17440 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d ction. This in-
17450 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 memory database
17460 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e will vanish when
17470 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 .** the database
17480 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 connection is c
17490 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 losed. Future v
174a0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
174b0 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 e might.** make
174c0 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 use of additiona
174d0 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 l special filena
174e0 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 mes that begin w
174f0 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 ith the ":" char
17500 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 acter..** It is
17510 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 recommended that
17520 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 when a database
17530 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c filename actual
17540 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 ly does begin wi
17550 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 th.** a ":" char
17560 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 acter you should
17570 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 prefix the file
17580 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 name with a path
17590 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 name such as.**
175a0 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d "./" to avoid am
175b0 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 biguity..**.** I
175c0 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 f the filename i
175d0 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e s an empty strin
175e0 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 g, then a privat
175f0 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 e, temporary.**
17600 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 on-disk database
17610 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 will be created
17620 2e 20 20 54 68 69 73 20 70 72 69 76 61 74 65 20 . This private
17630 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 database will be
17640 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c .** automaticall
17650 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f y deleted as soo
17660 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 n as the databas
17670 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
17680 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 closed..**.** Th
17690 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
176a0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 er to sqlite3_op
176b0 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e en_v2() is the n
176c0 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 ame of the.** [s
176d0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
176e0 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 ct that defines
176f0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 the operating sy
17700 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 stem interface t
17710 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 hat.** the new d
17720 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
17730 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 on should use.
17740 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 If the fourth pa
17750 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 rameter is.** a
17760 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 NULL pointer the
17770 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 n the default [s
17780 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
17790 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a ct is used..**.*
177a0 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e * <b>Note to Win
177b0 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 dows users:</b>
177c0 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 The encoding us
177d0 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e ed for the filen
177e0 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 ame argument.**
177f0 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 of sqlite3_open(
17800 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 ) and sqlite3_op
17810 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 en_v2() must be
17820 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 UTF-8, not whate
17830 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 ver.** codepage
17840 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 is currently def
17850 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 ined. Filenames
17860 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 containing inte
17870 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 rnational.** cha
17880 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 racters must be
17890 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 converted to UTF
178a0 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 -8 prior to pass
178b0 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a ing them into.**
178c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 sqlite3_open()
178d0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f or sqlite3_open_
178e0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 v2()..**.** Requ
178f0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
17900 32 37 30 31 5d 20 5b 48 31 32 37 30 32 5d 20 5b 2701] [H12702] [
17910 48 31 32 37 30 33 5d 20 5b 48 31 32 37 30 34 5d H12703] [H12704]
17920 20 5b 48 31 32 37 30 36 5d 20 5b 48 31 32 37 30 [H12706] [H1270
17930 37 5d 20 5b 48 31 32 37 30 39 5d 20 5b 48 31 32 7] [H12709] [H12
17940 37 31 31 5d 0a 2a 2a 20 5b 48 31 32 37 31 32 5d 711].** [H12712]
17950 20 5b 48 31 32 37 31 33 5d 20 5b 48 31 32 37 31 [H12713] [H1271
17960 34 5d 20 5b 48 31 32 37 31 37 5d 20 5b 48 31 32 4] [H12717] [H12
17970 37 31 39 5d 20 5b 48 31 32 37 32 31 5d 20 5b 48 719] [H12721] [H
17980 31 32 37 32 33 5d 0a 2a 2f 0a 69 6e 74 20 73 71 12723].*/.int sq
17990 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f lite3_open(. co
179a0 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 nst char *filena
179b0 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 me, /* Databas
179c0 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d e filename (UTF-
179d0 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 8) */. sqlite3
179e0 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 **ppDb
179f0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 /* OUT: SQLite d
17a00 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 b handle */.);.i
17a10 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 nt sqlite3_open1
17a20 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 6(. const void
17a30 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 *filename, /*
17a40 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d Database filenam
17a50 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 e (UTF-16) */.
17a60 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 sqlite3 **ppDb
17a70 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 /* OUT:
17a80 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 SQLite db handle
17a90 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 */.);.int sqlit
17aa0 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f e3_open_v2(. co
17ab0 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 nst char *filena
17ac0 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 me, /* Databas
17ad0 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d e filename (UTF-
17ae0 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 8) */. sqlite3
17af0 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 **ppDb,
17b00 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 /* OUT: SQLite d
17b10 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e b handle */. in
17b20 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 t flags,
17b30 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a /* Flags *
17b40 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
17b50 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e zVfs /* N
17b60 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c ame of VFS modul
17b70 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a e to use */.);..
17b80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
17b90 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 Error Codes And
17ba0 4d 65 73 73 61 67 65 73 20 7b 48 31 32 38 30 30 Messages {H12800
17bb0 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 0a 2a 2a } <S60200>.**.**
17bc0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 The sqlite3_err
17bd0 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 code() interface
17be0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
17bf0 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 eric [result cod
17c00 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 e] or.** [extend
17c10 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 ed result code]
17c20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 for the most rec
17c30 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 ent failed sqlit
17c40 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a e3_* API call.**
17c50 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
17c60 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e a [database con
17c70 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 nection]. If a p
17c80 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 rior API call fa
17c90 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 iled.** but the
17ca0 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 most recent API
17cb0 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 call succeeded,
17cc0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
17cd0 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 from.** sqlite3
17ce0 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e _errcode() is un
17cf0 64 65 66 69 6e 65 64 2e 20 20 54 68 65 20 73 71 defined. The sq
17d00 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 lite3_extended_e
17d10 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 rrcode().** inte
17d20 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d rface is the sam
17d30 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 e except that it
17d40 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 always returns
17d50 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 the .** [extende
17d60 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 d result code] e
17d70 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 ven when extende
17d80 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 d result codes a
17d90 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a re.** disabled..
17da0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
17db0 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 3_errmsg() and s
17dc0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 qlite3_errmsg16(
17dd0 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 ) return English
17de0 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 -language.** tex
17df0 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 t that describes
17e00 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 the error, as e
17e10 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 ither UTF-8 or U
17e20 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 TF-16 respective
17e30 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f ly..** Memory to
17e40 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 hold the error
17e50 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 message string i
17e60 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e s managed intern
17e70 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 ally..** The app
17e80 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f lication does no
17e90 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 t need to worry
17ea0 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 about freeing th
17eb0 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 e result..** How
17ec0 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 ever, the error
17ed0 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 string might be
17ee0 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 overwritten or d
17ef0 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a eallocated by.**
17f00 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c subsequent call
17f10 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 s to other SQLit
17f20 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 e interface func
17f30 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 tions..**.** Whe
17f40 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 n the serialized
17f50 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
17f60 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 ] is in use, it
17f70 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 might be the.**
17f80 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f case that a seco
17f90 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 nd error occurs
17fa0 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68 on a separate th
17fb0 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a read in between.
17fc0 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 ** the time of t
17fd0 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 he first error a
17fe0 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 nd the call to t
17ff0 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e hese interfaces.
18000 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 .** When that ha
18010 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e ppens, the secon
18020 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 d error will be
18030 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 reported since t
18040 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 hese.** interfac
18050 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 es always report
18060 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
18070 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f result. To avo
18080 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 id.** this, each
18090 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 thread can obta
180a0 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 in exclusive use
180b0 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 of the [databas
180c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a e connection] D.
180d0 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b ** by invoking [
180e0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e sqlite3_mutex_en
180f0 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 ter]([sqlite3_db
18100 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f _mutex](D)) befo
18110 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 re beginning.**
18120 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 to use D and inv
18130 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d oking [sqlite3_m
18140 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c utex_leave]([sql
18150 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 ite3_db_mutex](D
18160 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 )) after.** all
18170 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 calls to the int
18180 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 erfaces listed h
18190 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 ere are complete
181a0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 d..**.** If an i
181b0 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 nterface fails w
181c0 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 ith SQLITE_MISUS
181d0 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 E, that means th
181e0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 e interface.** w
181f0 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 as invoked incor
18200 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 rectly by the ap
18210 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 plication. In t
18220 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a hat case, the.**
18230 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 error code and
18240 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d message may or m
18250 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a ay not be set..*
18260 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
18270 73 3a 0a 2a 2a 20 5b 48 31 32 38 30 31 5d 20 5b s:.** [H12801] [
18280 48 31 32 38 30 32 5d 20 5b 48 31 32 38 30 33 5d H12802] [H12803]
18290 20 5b 48 31 32 38 30 37 5d 20 5b 48 31 32 38 30 [H12807] [H1280
182a0 38 5d 20 5b 48 31 32 38 30 39 5d 0a 2a 2f 0a 69 8] [H12809].*/.i
182b0 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f nt sqlite3_errco
182c0 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b de(sqlite3 *db);
182d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 .int sqlite3_ext
182e0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 ended_errcode(sq
182f0 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 lite3 *db);.cons
18300 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
18310 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 errmsg(sqlite3*)
18320 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 ;.const void *sq
18330 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 lite3_errmsg16(s
18340 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
18350 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 CAPI3REF: SQL S
18360 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 tatement Object
18370 7b 48 31 33 30 30 30 7d 20 3c 48 31 33 30 31 30 {H13000} <H13010
18380 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b >.** KEYWORDS: {
18390 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
183a0 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 nt} {prepared st
183b0 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 atements}.**.**
183c0 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 An instance of t
183d0 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 his object repre
183e0 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 sents a single S
183f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a QL statement..**
18400 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 This object is
18410 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 variously known
18420 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73 as a "prepared s
18430 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a tatement" or a.*
18440 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 * "compiled SQL
18450 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 statement" or si
18460 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 mply as a "state
18470 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ment"..**.** The
18480 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 life of a state
18490 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 ment object goes
184a0 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 something like
184b0 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e this:.**.** <ol>
184c0 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 .** <li> Create
184d0 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 the object using
184e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
184f0 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c e_v2()] or a rel
18500 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e ated.** fun
18510 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 ction..** <li> B
18520 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 ind values to [h
18530 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 ost parameters]
18540 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 using the sqlite
18550 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 3_bind_*().**
18560 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a interfaces..*
18570 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 * <li> Run the S
18580 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 QL by calling [s
18590 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f qlite3_step()] o
185a0 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 ne or more times
185b0 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 ..** <li> Reset
185c0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 the statement us
185d0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ing [sqlite3_res
185e0 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 et()] then go ba
185f0 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 ck.** to st
18600 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a ep 2. Do this z
18610 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 ero or more time
18620 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 s..** <li> Destr
18630 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 oy the object us
18640 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e ing [sqlite3_fin
18650 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f alize()]..** </o
18660 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 l>.**.** Refer t
18670 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 o documentation
18680 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 on individual me
18690 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 thods above for
186a0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e additional.** in
186b0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 formation..*/.ty
186c0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
186d0 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 ite3_stmt sqlite
186e0 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 3_stmt;../*.** C
186f0 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d API3REF: Run-tim
18700 65 20 4c 69 6d 69 74 73 20 7b 48 31 32 37 36 30 e Limits {H12760
18710 7d 20 3c 53 32 30 36 30 30 3e 0a 2a 2a 0a 2a 2a } <S20600>.**.**
18720 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 This interface
18730 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 allows the size
18740 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 of various const
18750 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 ructs to be limi
18760 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e ted.** on a conn
18770 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 ection by connec
18780 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 tion basis. The
18790 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
187a0 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 is the.** [data
187b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
187c0 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 whose limit is
187d0 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 to be set or que
187e0 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 ried. The.** se
187f0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 cond parameter i
18800 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 s one of the [li
18810 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 mit categories]
18820 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a that define a.**
18830 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 class of constr
18840 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 ucts to be size
18850 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 limited. The th
18860 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ird parameter is
18870 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 the.** new limi
18880 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 t for that const
18890 72 75 63 74 2e 20 20 54 68 65 20 66 75 6e 63 74 ruct. The funct
188a0 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 ion returns the
188b0 6f 6c 64 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a old limit..**.**
188c0 20 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 If the new limi
188d0 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 t is a negative
188e0 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 number, the limi
188f0 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a t is unchanged..
18900 2a 2a 20 46 6f 72 20 74 68 65 20 6c 69 6d 69 74 ** For the limit
18910 20 63 61 74 65 67 6f 72 79 20 6f 66 20 53 51 4c category of SQL
18920 49 54 45 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 68 ITE_LIMIT_XYZ th
18930 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 ere is a .** [li
18940 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 mits | hard uppe
18950 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 r bound].** set
18960 62 79 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d by a compile-tim
18970 65 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 e C preprocessor
18980 20 6d 61 63 72 6f 20 6e 61 6d 65 64 20 0a 2a 2a macro named .**
18990 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 [limits | SQLIT
189a0 45 5f 4d 41 58 5f 58 59 5a 5d 2e 0a 2a 2a 20 28 E_MAX_XYZ]..** (
189b0 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e The "_LIMIT_" in
189c0 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 the name is cha
189d0 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e nged to "_MAX_".
189e0 29 0a 2a 2a 20 41 74 74 65 6d 70 74 73 20 74 6f ).** Attempts to
189f0 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 increase a limi
18a00 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 t above its hard
18a10 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 upper bound are
18a20 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 .** silently tru
18a30 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 ncated to the ha
18a40 72 64 20 75 70 70 65 72 20 6c 69 6d 69 74 2e 0a rd upper limit..
18a50 2a 2a 0a 2a 2a 20 52 75 6e 20 74 69 6d 65 20 6c **.** Run time l
18a60 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 imits are intend
18a70 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 ed for use in ap
18a80 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 plications that
18a90 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 manage.** both t
18aa0 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 heir own interna
18ab0 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 l database and a
18ac0 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 lso databases th
18ad0 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 at are controlle
18ae0 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 d.** by untruste
18af0 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 d external sourc
18b00 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 es. An example
18b10 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 application migh
18b20 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 t be a.** web br
18b30 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 owser that has i
18b40 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 ts own databases
18b50 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 for storing his
18b60 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 tory and.** sepa
18b70 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 rate databases c
18b80 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 ontrolled by Jav
18b90 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 aScript applicat
18ba0 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a ions downloaded.
18bb0 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 ** off the Inter
18bc0 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e net. The intern
18bd0 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e al databases can
18be0 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a be given the.**
18bf0 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 large, default
18c00 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 limits. Databas
18c10 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 es managed by ex
18c20 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 ternal sources c
18c30 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d an.** be given m
18c40 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 uch smaller limi
18c50 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 ts designed to p
18c60 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 revent a denial
18c70 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 of service.** at
18c80 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 tack. Developer
18c90 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e s might also wan
18ca0 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 t to use the [sq
18cb0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
18cc0 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 izer()].** inter
18cd0 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 face to further
18ce0 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 control untruste
18cf0 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 d SQL. The size
18d00 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
18d10 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 .** created by a
18d20 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 n untrusted scri
18d30 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 pt can be contai
18d40 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a ned using the.**
18d50 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 [max_page_count
18d60 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a ] [PRAGMA]..**.*
18d70 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c * New run-time l
18d80 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 imit categories
18d90 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 may be added in
18da0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e future releases.
18db0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
18dc0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 37 36 32 5d nts:.** [H12762]
18dd0 20 5b 48 31 32 37 36 36 5d 20 5b 48 31 32 37 36 [H12766] [H1276
18de0 39 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 9].*/.int sqlite
18df0 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 3_limit(sqlite3*
18e00 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 , int id, int ne
18e10 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 wVal);../*.** CA
18e20 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 PI3REF: Run-Time
18e30 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 Limit Categorie
18e40 73 20 7b 48 31 32 37 39 30 7d 20 3c 48 31 32 37 s {H12790} <H127
18e50 36 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 60>.** KEYWORDS:
18e60 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 {limit category
18e70 7d 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 } {limit categor
18e80 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ies}.**.** These
18e90 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e constants defin
18ea0 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 e various perfor
18eb0 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 mance limits.**
18ec0 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 that can be lowe
18ed0 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 red at run-time
18ee0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c using [sqlite3_l
18ef0 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 imit()]..** The
18f00 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 synopsis of the
18f10 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 meanings of the
18f20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 various limits i
18f30 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a s shown below..*
18f40 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 * Additional inf
18f50 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 ormation is avai
18f60 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 lable at [limits
18f70 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c | Limits in SQL
18f80 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e ite]..**.** <dl>
18f90 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c .** <dt>SQLITE_L
18fa0 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e IMIT_LENGTH</dt>
18fb0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
18fc0 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 mum size of any
18fd0 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f string or BLOB o
18fe0 72 20 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e r table row.<dd>
18ff0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
19000 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 E_LIMIT_SQL_LENG
19010 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 TH</dt>.** <dd>T
19020 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 he maximum lengt
19030 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 h of an SQL stat
19040 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a ement.</dd>.**.*
19050 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d * <dt>SQLITE_LIM
19060 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a IT_COLUMN</dt>.*
19070 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
19080 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 m number of colu
19090 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 mns in a table d
190a0 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 efinition or in
190b0 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 the.** result se
190c0 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 t of a [SELECT]
190d0 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e or the maximum n
190e0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
190f0 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 in an index.**
19100 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 or in an ORDER B
19110 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c Y or GROUP BY cl
19120 61 75 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ause.</dd>.**.**
19130 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 <dt>SQLITE_LIMI
19140 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 T_EXPR_DEPTH</dt
19150 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
19160 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 imum depth of th
19170 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 e parse tree on
19180 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c any expression.<
19190 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
191a0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 QLITE_LIMIT_COMP
191b0 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e OUND_SELECT</dt>
191c0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
191d0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 mum number of te
191e0 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e rms in a compoun
191f0 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 d SELECT stateme
19200 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c nt.</dd>.**.** <
19210 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
19220 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 VDBE_OP</dt>.**
19230 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
19240 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 number of instru
19250 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 ctions in a virt
19260 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 ual machine prog
19270 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 ram.** used to i
19280 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 mplement an SQL
19290 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a statement.</dd>.
192a0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
192b0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f _LIMIT_FUNCTION_
192c0 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ARG</dt>.** <dd>
192d0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
192e0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 er of arguments
192f0 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f on a function.</
19300 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
19310 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 LITE_LIMIT_ATTAC
19320 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e HED</dt>.** <dd>
19330 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
19340 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 er of [ATTACH |
19350 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 attached databas
19360 65 73 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 es].</dd>.**.**
19370 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
19380 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 _LIKE_PATTERN_LE
19390 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 NGTH</dt>.** <dd
193a0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e >The maximum len
193b0 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 gth of the patte
193c0 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 rn argument to t
193d0 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 he [LIKE] or.**
193e0 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 [GLOB] operators
193f0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
19400 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 >SQLITE_LIMIT_VA
19410 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 RIABLE_NUMBER</d
19420 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
19430 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
19440 76 61 72 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 variables in an
19450 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 SQL statement th
19460 61 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 at can.** be bou
19470 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c nd.</dd>.** </dl
19480 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c >.*/.#define SQL
19490 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 ITE_LIMIT_LENGTH
194a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
194b0 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 0.#define SQ
194c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c LITE_LIMIT_SQL_L
194d0 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 ENGTH
194e0 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 1.#define S
194f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 QLITE_LIMIT_COLU
19500 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 MN
19510 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 2.#define
19520 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 SQLITE_LIMIT_EXP
19530 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 R_DEPTH
19540 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 3.#define
19550 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f SQLITE_LIMIT_CO
19560 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 MPOUND_SELECT
19570 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 4.#defin
19580 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 e SQLITE_LIMIT_V
19590 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 DBE_OP
195a0 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 5.#defi
195b0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
195c0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 FUNCTION_ARG
195d0 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 6.#def
195e0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
195f0 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 _ATTACHED
19600 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 7.#de
19610 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
19620 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c T_LIKE_PATTERN_L
19630 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 ENGTH 8.#d
19640 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
19650 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 IT_VARIABLE_NUMB
19660 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 0a ER 9..
19670 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
19680 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c Compiling An SQL
19690 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 30 Statement {H130
196a0 31 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 20 10} <S10000>.**
196b0 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 KEYWORDS: {SQL s
196c0 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 tatement compile
196d0 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 r}.**.** To exec
196e0 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 ute an SQL query
196f0 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 , it must first
19700 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f be compiled into
19710 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 a byte-code.**
19720 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e program using on
19730 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 e of these routi
19740 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 nes..**.** The f
19750 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 irst argument, "
19760 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 db", is a [datab
19770 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
19780 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a obtained from a.
19790 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 ** prior success
197a0 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ful call to [sql
197b0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 ite3_open()], [s
197c0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
197d0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ] or.** [sqlite3
197e0 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 _open16()]. The
197f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
19800 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 tion must not ha
19810 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a ve been closed..
19820 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 **.** The second
19830 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c argument, "zSql
19840 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d ", is the statem
19850 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c ent to be compil
19860 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 ed, encoded.** a
19870 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f s either UTF-8 o
19880 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 r UTF-16. The s
19890 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
198a0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 and sqlite3_pre
198b0 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 pare_v2().** int
198c0 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d erfaces use UTF-
198d0 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 8, and sqlite3_p
198e0 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 repare16() and s
198f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
19900 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 _v2().** use UTF
19910 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 -16..**.** If th
19920 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 e nByte argument
19930 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 is less than ze
19940 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 ro, then zSql is
19950 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a read up to the.
19960 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 ** first zero te
19970 72 6d 69 6e 61 74 6f 72 2e 20 49 66 20 6e 42 79 rminator. If nBy
19980 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 te is non-negati
19990 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 ve, then it is t
199a0 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 he maximum.** nu
199b0 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 mber of bytes r
199c0 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 ead from zSql.
199d0 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f When nByte is no
199e0 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a n-negative, the.
199f0 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 ** zSql string e
19a00 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68 nds at either th
19a10 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f e first '\000' o
19a20 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 r '\u0000' chara
19a30 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e cter or.** the n
19a40 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 Byte-th byte, wh
19a50 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 ichever comes fi
19a60 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c rst. If the call
19a70 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 er knows.** that
19a80 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 the supplied st
19a90 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d ring is nul-term
19aa0 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 inated, then the
19ab0 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a re is a small.**
19ac0 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 performance adv
19ad0 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 antage to be gai
19ae0 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 ned by passing a
19af0 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 n nByte paramete
19b00 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 r that.** is equ
19b10 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 al to the number
19b20 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 of bytes in the
19b30 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 input string <i
19b40 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a >including</i>.*
19b50 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e * the nul-termin
19b60 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a ator bytes..**.*
19b70 2a 20 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e * If pzTail is n
19b80 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a ot NULL then *pz
19b90 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 Tail is made to
19ba0 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 point to the fir
19bb0 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 st byte.** past
19bc0 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 the end of the f
19bd0 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 irst SQL stateme
19be0 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 nt in zSql. The
19bf0 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 se routines only
19c00 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 .** compile the
19c10 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 first statement
19c20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 in zSql, so *pzT
19c30 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e ail is left poin
19c40 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 ting to.** what
19c50 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c remains uncompil
19c60 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d ed..**.** *ppStm
19c70 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 t is left pointi
19c80 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 ng to a compiled
19c90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
19ca0 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 ment] that can b
19cb0 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 e.** executed us
19cc0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 ing [sqlite3_ste
19cd0 70 28 29 5d 2e 20 20 49 66 20 74 68 65 72 65 20 p()]. If there
19ce0 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 is an error, *pp
19cf0 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 Stmt is set.** t
19d00 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 o NULL. If the
19d10 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 input text conta
19d20 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 ins no SQL (if t
19d30 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 he input is an e
19d40 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f mpty.** string o
19d50 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 r a comment) the
19d60 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 n *ppStmt is set
19d70 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 to NULL..** The
19d80 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 calling procedu
19d90 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c re is responsibl
19da0 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 e for deleting t
19db0 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 he compiled.** S
19dc0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 QL statement usi
19dd0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 ng [sqlite3_fina
19de0 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 lize()] after it
19df0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 has finished wi
19e00 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 th it..** ppStmt
19e10 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c may not be NULL
19e20 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 ..**.** On succe
19e30 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 ss, [SQLITE_OK]
19e40 69 73 20 72 65 74 75 72 6e 65 64 2c 20 6f 74 68 is returned, oth
19e50 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 erwise an [error
19e60 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e code] is return
19e70 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ed..**.** The sq
19e80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
19e90 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 () and sqlite3_p
19ea0 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e repare16_v2() in
19eb0 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 terfaces are.**
19ec0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 recommended for
19ed0 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 all new programs
19ee0 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 . The two older
19ef0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72 interfaces are r
19f00 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 etained.** for b
19f10 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 ackwards compati
19f20 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 bility, but thei
19f30 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 r use is discour
19f40 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 aged..** In the
19f50 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c "v2" interfaces,
19f60 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 the prepared st
19f70 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 atement.** that
19f80 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 is returned (the
19f90 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 [sqlite3_stmt]
19fa0 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 object) contains
19fb0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a a copy of the.*
19fc0 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 * original SQL t
19fd0 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 ext. This causes
19fe0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 the [sqlite3_st
19ff0 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 ep()] interface
1a000 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 64 to.** behave a d
1a010 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 77 ifferently in tw
1a020 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f o ways:.**.** <o
1a030 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 l>.** <li>.** If
1a040 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 the database sc
1a050 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e hema changes, in
1a060 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 stead of returni
1a070 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d ng [SQLITE_SCHEM
1a080 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 A] as it.** alwa
1a090 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b ys used to do, [
1a0a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
1a0b0 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c will automatical
1a0c0 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 ly recompile the
1a0d0 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e SQL.** statemen
1a0e0 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e t and try to run
1a0f0 20 69 74 20 61 67 61 69 6e 2e 20 20 49 66 20 74 it again. If t
1a100 68 65 20 73 63 68 65 6d 61 20 68 61 73 20 63 68 he schema has ch
1a110 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 anged in.** a wa
1a120 79 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 y that makes the
1a130 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f statement no lo
1a140 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c nger valid, [sql
1a150 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c ite3_step()] wil
1a160 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 l still.** retur
1a170 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 n [SQLITE_SCHEMA
1a180 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 ]. But unlike t
1a190 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 he legacy behavi
1a1a0 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 or, [SQLITE_SCHE
1a1b0 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 MA] is.** now a
1a1c0 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 fatal error. Ca
1a1d0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 lling [sqlite3_p
1a1e0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61 repare_v2()] aga
1a1f0 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 in will not make
1a200 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f the.** error go
1a210 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 away. Note: us
1a220 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 e [sqlite3_errms
1a230 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 g()] to find the
1a240 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 text.** of the
1a250 70 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68 parsing error th
1a260 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e at results in an
1a270 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d [SQLITE_SCHEMA]
1a280 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 return..** </li
1a290 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 >.**.** <li>.**
1a2a0 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 When an error oc
1a2b0 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 curs, [sqlite3_s
1a2c0 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 tep()] will retu
1a2d0 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 rn one of the de
1a2e0 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 tailed.** [error
1a2f0 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 codes] or [exte
1a300 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 nded error codes
1a310 5d 2e 20 20 54 68 65 20 6c 65 67 61 63 79 20 62 ]. The legacy b
1a320 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 ehavior was that
1a330 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 .** [sqlite3_ste
1a340 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 p()] would only
1a350 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 return a generic
1a360 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
1a370 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 result code.** a
1a380 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 nd you would hav
1a390 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f e to make a seco
1a3a0 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 nd call to [sqli
1a3b0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 te3_reset()] in
1a3c0 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 66 69 6e 64 order.** to find
1a3d0 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 the underlying
1a3e0 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f cause of the pro
1a3f0 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 blem. With the "
1a400 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 v2" prepare.** i
1a410 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 nterfaces, the u
1a420 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e nderlying reason
1a430 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 for the error i
1a440 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 s returned immed
1a450 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e iately..** </li>
1a460 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ol>.**.**
1a470 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
1a480 20 5b 48 31 33 30 31 31 5d 20 5b 48 31 33 30 31 [H13011] [H1301
1a490 32 5d 20 5b 48 31 33 30 31 33 5d 20 5b 48 31 33 2] [H13013] [H13
1a4a0 30 31 34 5d 20 5b 48 31 33 30 31 35 5d 20 5b 48 014] [H13015] [H
1a4b0 31 33 30 31 36 5d 20 5b 48 31 33 30 31 39 5d 20 13016] [H13019]
1a4c0 5b 48 31 33 30 32 31 5d 0a 2a 2a 0a 2a 2f 0a 69 [H13021].**.*/.i
1a4d0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nt sqlite3_prepa
1a4e0 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 re(. sqlite3 *d
1a4f0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a b, /*
1a500 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 Database handle
1a510 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
1a520 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a *zSql, /*
1a530 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 SQL statement,
1a540 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f UTF-8 encoded */
1a550 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 . int nByte,
1a560 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 /* Ma
1a570 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
1a580 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a zSql in bytes. *
1a590 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 /. sqlite3_stmt
1a5a0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f **ppStmt, /* O
1a5b0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 UT: Statement ha
1a5c0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
1a5d0 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 char **pzTail
1a5e0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 /* OUT: Pointe
1a5f0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 r to unused port
1a600 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 ion of zSql */.)
1a610 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 ;.int sqlite3_pr
1a620 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 epare_v2(. sqli
1a630 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
1a640 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
1a650 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
1a660 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 t char *zSql,
1a670 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 /* SQL state
1a680 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f ment, UTF-8 enco
1a690 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 ded */. int nBy
1a6a0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 te,
1a6b0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 /* Maximum leng
1a6c0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 th of zSql in by
1a6d0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 tes. */. sqlite
1a6e0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 3_stmt **ppStmt,
1a6f0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d /* OUT: Statem
1a700 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ent handle */.
1a710 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 const char **pzT
1a720 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 ail /* OUT:
1a730 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 Pointer to unuse
1a740 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 d portion of zSq
1a750 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 l */.);.int sqli
1a760 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 te3_prepare16(.
1a770 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
1a780 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
1a790 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 base handle */.
1a7a0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 const void *zSq
1a7b0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 l, /* SQL
1a7c0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 statement, UTF-1
1a7d0 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6 encoded */. i
1a7e0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 nt nByte,
1a7f0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 /* Maximu
1a800 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c m length of zSql
1a810 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 in bytes. */.
1a820 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 sqlite3_stmt **p
1a830 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 pStmt, /* OUT:
1a840 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 Statement handle
1a850 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 */. const void
1a860 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a **pzTail /*
1a870 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f OUT: Pointer to
1a880 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 unused portion
1a890 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e of zSql */.);.in
1a8a0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 t sqlite3_prepar
1a8b0 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 e16_v2(. sqlite
1a8c0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
1a8d0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 /* Database ha
1a8e0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
1a8f0 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 void *zSql,
1a900 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 /* SQL stateme
1a910 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 nt, UTF-16 encod
1a920 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 ed */. int nByt
1a930 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 e,
1a940 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 /* Maximum lengt
1a950 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 h of zSql in byt
1a960 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 es. */. sqlite3
1a970 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 _stmt **ppStmt,
1a980 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 /* OUT: Stateme
1a990 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 nt handle */. c
1a9a0 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 onst void **pzTa
1a9b0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 il /* OUT: P
1a9c0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 ointer to unused
1a9d0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c portion of zSql
1a9e0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.);../*.** CA
1a9f0 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 PI3REF: Retrievi
1aa00 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c ng Statement SQL
1aa10 20 7b 48 31 33 31 30 30 7d 20 3c 48 31 33 30 30 {H13100} <H1300
1aa20 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 0>.**.** This in
1aa30 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 terface can be u
1aa40 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 sed to retrieve
1aa50 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 a saved copy of
1aa60 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 the original.**
1aa70 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f SQL text used to
1aa80 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 create a [prepa
1aa90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 red statement] i
1aaa0 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 f that statement
1aab0 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 was.** compiled
1aac0 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 using either [s
1aad0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1aae0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 2()] or [sqlite3
1aaf0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
1ab00 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
1ab10 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 31 30 31 ents:.** [H13101
1ab20 5d 20 5b 48 31 33 31 30 32 5d 20 5b 48 31 33 31 ] [H13102] [H131
1ab30 30 33 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 03].*/.const cha
1ab40 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 r *sqlite3_sql(s
1ab50 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
1ab60 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
1ab70 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 3REF: Dynamicall
1ab80 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 y Typed Value Ob
1ab90 6a 65 63 74 20 7b 48 31 35 30 30 30 7d 20 3c 53 ject {H15000} <S
1aba0 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 20200>.** KEYWOR
1abb0 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 DS: {protected s
1abc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 qlite3_value} {u
1abd0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
1abe0 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 e3_value}.**.**
1abf0 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 SQLite uses the
1ac00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
1ac10 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e ject to represen
1ac20 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 t all values.**
1ac30 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 that can be stor
1ac40 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 ed in a database
1ac50 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 table. SQLite u
1ac60 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 ses dynamic typi
1ac70 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 ng.** for the va
1ac80 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 lues it stores.
1ac90 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e Values stored in
1aca0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
1acb0 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 bjects.** can be
1acc0 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 integers, float
1acd0 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 ing point values
1ace0 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 , strings, BLOBs
1acf0 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a , or NULL..**.**
1ad00 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 An sqlite3_valu
1ad10 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 e object may be
1ad20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 either "protecte
1ad30 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 d" or "unprotect
1ad40 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 ed"..** Some int
1ad50 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 erfaces require
1ad60 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 a protected sqli
1ad70 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 te3_value. Othe
1ad80 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 r interfaces.**
1ad90 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 will accept eith
1ada0 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f er a protected o
1adb0 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 r an unprotected
1adc0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a sqlite3_value..
1add0 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 ** Every interfa
1ade0 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 ce that accepts
1adf0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 sqlite3_value ar
1ae00 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 guments specifie
1ae10 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 s.** whether or
1ae20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 not it requires
1ae30 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 a protected sqli
1ae40 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a te3_value..**.**
1ae50 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 The terms "prot
1ae60 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 ected" and "unpr
1ae70 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74 otected" refer t
1ae80 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 o whether or not
1ae90 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 .** a mutex is h
1aea0 65 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c eld. A internal
1aeb0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 mutex is held f
1aec0 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a or a protected.*
1aed0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 * sqlite3_value
1aee0 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 object but no mu
1aef0 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 tex is held for
1af00 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a an unprotected.*
1af10 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 * sqlite3_value
1af20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 object. If SQLi
1af30 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 te is compiled t
1af40 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 o be single-thre
1af50 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 aded.** (with [S
1af60 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
1af70 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 =0] and with [sq
1af80 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 lite3_threadsafe
1af90 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 ()] returning 0)
1afa0 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 .** or if SQLite
1afb0 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f is run in one o
1afc0 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 f reduced mutex
1afd0 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 modes .** [SQLIT
1afe0 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
1aff0 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 HREAD] or [SQLIT
1b000 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 E_CONFIG_MULTITH
1b010 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 READ].** then th
1b020 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e ere is no distin
1b030 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 ction between pr
1b040 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 otected and unpr
1b050 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 otected.** sqlit
1b060 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
1b070 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 and they can be
1b080 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 used interchang
1b090 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c eably. However,
1b0a0 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 .** for maximum
1b0b0 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 code portability
1b0c0 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 it is recommend
1b0d0 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 ed that applicat
1b0e0 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 ions.** still ma
1b0f0 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 ke the distincti
1b100 6f 6e 20 62 65 74 77 65 65 6e 20 62 65 74 77 65 on between betwe
1b110 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 en protected and
1b120 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 unprotected.**
1b130 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
1b140 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 jects even when
1b150 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 not strictly req
1b160 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 uired..**.** The
1b170 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
1b180 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 bjects that are
1b190 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 passed as parame
1b1a0 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a ters into the.**
1b1b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
1b1c0 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d of [application-
1b1d0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
1b1e0 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 tions] are prote
1b1f0 63 74 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c cted..** The sql
1b200 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
1b210 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a t returned by.**
1b220 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
1b230 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 _value()] is unp
1b240 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 rotected..** Unp
1b250 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
1b260 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d _value objects m
1b270 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 ay only be used
1b280 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 with.** [sqlite3
1b290 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d _result_value()]
1b2a0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 and [sqlite3_bi
1b2b0 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 nd_value()]..**
1b2c0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c The [sqlite3_val
1b2d0 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 ue_blob | sqlite
1b2e0 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 3_value_type()]
1b2f0 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 family of.** int
1b300 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 erfaces require
1b310 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
1b320 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 3_value objects.
1b330 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
1b340 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 ct Mem sqlite3_v
1b350 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 alue;../*.** CAP
1b360 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 I3REF: SQL Funct
1b370 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 ion Context Obje
1b380 63 74 20 7b 48 31 36 30 30 31 7d 20 3c 53 32 30 ct {H16001} <S20
1b390 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 200>.**.** The c
1b3a0 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 ontext in which
1b3b0 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 an SQL function
1b3c0 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 executes is stor
1b3d0 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 ed in an.** sqli
1b3e0 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 te3_context obje
1b3f0 63 74 2e 20 20 41 20 70 6f 69 6e 74 65 72 20 74 ct. A pointer t
1b400 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e o an sqlite3_con
1b410 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 text object.** i
1b420 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 s always first p
1b430 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 arameter to [app
1b440 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
1b450 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e SQL functions].
1b460 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
1b470 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
1b480 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 function impleme
1b490 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 ntation will pas
1b4a0 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 s this.** pointe
1b4b0 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 r through into c
1b4c0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
1b4d0 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 _result_int | sq
1b4e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c lite3_result()],
1b4f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 .** [sqlite3_agg
1b500 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 regate_context()
1b510 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 ], [sqlite3_user
1b520 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 _data()],.** [sq
1b530 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 lite3_context_db
1b540 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c _handle()], [sql
1b550 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 ite3_get_auxdata
1b560 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b ()],.** and/or [
1b570 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 sqlite3_set_auxd
1b580 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 ata()]..*/.typed
1b590 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
1b5a0 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 3_context sqlite
1b5b0 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 3_context;../*.*
1b5c0 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 * CAPI3REF: Bind
1b5d0 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 ing Values To Pr
1b5e0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 epared Statement
1b5f0 73 20 7b 48 31 33 35 30 30 7d 20 3c 53 37 30 33 s {H13500} <S703
1b600 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 00>.** KEYWORDS:
1b610 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 {host parameter
1b620 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 } {host paramete
1b630 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 rs} {host parame
1b640 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 ter name}.** KEY
1b650 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 WORDS: {SQL para
1b660 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 meter} {SQL para
1b670 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 meters} {paramet
1b680 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a er binding}.**.*
1b690 2a 20 49 6e 20 74 68 65 20 53 51 4c 20 73 74 72 * In the SQL str
1b6a0 69 6e 67 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 ings input to [s
1b6b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1b6c0 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 2()] and its var
1b6d0 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 iants,.** litera
1b6e0 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 ls may be replac
1b6f0 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 ed by a [paramet
1b700 65 72 5d 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 er] in one of th
1b710 65 73 65 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a ese forms:.**.**
1b720 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f <ul>.** <li> ?
1b730 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a .** <li> ?NNN.*
1b740 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 * <li> :VVV.**
1b750 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c <li> @VVV.** <l
1b760 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c i> $VVV.** </ul
1b770 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70 >.**.** In the p
1b780 61 72 61 6d 65 74 65 72 20 66 6f 72 6d 73 20 73 arameter forms s
1b790 68 6f 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69 hown above NNN i
1b7a0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 s an integer lit
1b7b0 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 eral,.** and VVV
1b7c0 20 69 73 20 61 6e 20 61 6c 70 68 61 2d 6e 75 6d is an alpha-num
1b7d0 65 72 69 63 20 70 61 72 61 6d 65 74 65 72 20 6e eric parameter n
1b7e0 61 6d 65 2e 20 54 68 65 20 76 61 6c 75 65 73 20 ame. The values
1b7f0 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 of these.** para
1b800 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c meters (also cal
1b810 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 led "host parame
1b820 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 ter names" or "S
1b830 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a QL parameters").
1b840 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 ** can be set us
1b850 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f ing the sqlite3_
1b860 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 bind_*() routine
1b870 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a s defined here..
1b880 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
1b890 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
1b8a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 sqlite3_bind_*()
1b8b0 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 routines is alw
1b8c0 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 ays.** a pointer
1b8d0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
1b8e0 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 _stmt] object re
1b8f0 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b turned from.** [
1b900 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
1b910 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 v2()] or its var
1b920 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 iants..**.** The
1b930 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
1b940 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 is the index of
1b950 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 the SQL paramet
1b960 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a er to be set..**
1b970 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 The leftmost SQ
1b980 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 L parameter has
1b990 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 an index of 1.
1b9a0 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 When the same na
1b9b0 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d med.** SQL param
1b9c0 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 eter is used mor
1b9d0 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 e than once, sec
1b9e0 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 ond and subseque
1b9f0 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 nt.** occurrence
1ba00 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 s have the same
1ba10 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72 index as the fir
1ba20 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a st occurrence..*
1ba30 2a 20 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 * The index for
1ba40 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 named parameters
1ba50 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 can be looked u
1ba60 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b p using the.** [
1ba70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
1ba80 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 ameter_index()]
1ba90 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 API if desired.
1baa0 20 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f The index.** fo
1bab0 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 r "?NNN" paramet
1bac0 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 ers is the value
1bad0 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20 of NNN..** The
1bae0 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 NNN value must b
1baf0 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 e between 1 and
1bb00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d the [sqlite3_lim
1bb10 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 it()].** paramet
1bb20 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 er [SQLITE_LIMIT
1bb30 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 _VARIABLE_NUMBER
1bb40 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 ] (default value
1bb50 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 : 999)..**.** Th
1bb60 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 e third argument
1bb70 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f is the value to
1bb80 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 bind to the par
1bb90 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e ameter..**.** In
1bba0 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 those routines
1bbb0 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 that have a four
1bbc0 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 th argument, its
1bbd0 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a value is the.**
1bbe0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
1bbf0 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 in the paramete
1bc00 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a r. To be clear:
1bc10 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 the value is th
1bc20 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c e.** number of <
1bc30 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 u>bytes</u> in t
1bc40 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 he value, not th
1bc50 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 e number of char
1bc60 61 63 74 65 72 73 2e 0a 2a 2a 20 49 66 20 74 68 acters..** If th
1bc70 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
1bc80 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 er is negative,
1bc90 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 the length of th
1bca0 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 e string is.** t
1bcb0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
1bcc0 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 es up to the fir
1bcd0 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 st zero terminat
1bce0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 or..**.** The fi
1bcf0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 fth argument to
1bd00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
1bd10 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e b(), sqlite3_bin
1bd20 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a d_text(), and.**
1bd30 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
1bd40 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74 xt16() is a dest
1bd50 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 ructor used to d
1bd60 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c ispose of the BL
1bd70 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 OB or.** string
1bd80 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 after SQLite has
1bd90 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 finished with i
1bda0 74 2e 20 49 66 20 74 68 65 20 66 69 66 74 68 20 t. If the fifth
1bdb0 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 argument is.** t
1bdc0 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 he special value
1bdd0 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d [SQLITE_STATIC]
1bde0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 , then SQLite as
1bdf0 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a sumes that the.*
1be00 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 * information is
1be10 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 in static, unma
1be20 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 naged space and
1be30 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f does not need to
1be40 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 be freed..** If
1be50 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d the fifth argum
1be60 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 ent has the valu
1be70 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 e [SQLITE_TRANSI
1be80 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 ENT], then.** SQ
1be90 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f Lite makes its o
1bea0 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 wn private copy
1beb0 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 of the data imme
1bec0 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a diately, before.
1bed0 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 ** the sqlite3_b
1bee0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 ind_*() routine
1bef0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 returns..**.** T
1bf00 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
1bf10 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 zeroblob() routi
1bf20 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 ne binds a BLOB
1bf30 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 of length N that
1bf40 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 .** is filled wi
1bf50 74 68 20 7a 65 72 6f 65 73 2e 20 20 41 20 7a 65 th zeroes. A ze
1bf60 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 roblob uses a fi
1bf70 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 xed amount of me
1bf80 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e mory.** (just an
1bf90 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 integer to hold
1bfa0 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 its size) while
1bfb0 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f it is being pro
1bfc0 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 cessed..** Zerob
1bfd0 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 lobs are intende
1bfe0 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c d to serve as pl
1bff0 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 aceholders for B
1c000 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f LOBs whose.** co
1c010 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 ntent is later w
1c020 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 ritten using.**
1c030 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 [sqlite3_blob_op
1c040 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c en | incremental
1c050 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 BLOB I/O] routi
1c060 6e 65 73 2e 0a 2a 2a 20 41 20 6e 65 67 61 74 69 nes..** A negati
1c070 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 ve value for the
1c080 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 zeroblob result
1c090 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 s in a zero-leng
1c0a0 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 th BLOB..**.** T
1c0b0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
1c0c0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 *() routines mus
1c0d0 74 20 62 65 20 63 61 6c 6c 65 64 20 61 66 74 65 t be called afte
1c0e0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 r.** [sqlite3_pr
1c0f0 65 70 61 72 65 5f 76 32 28 29 5d 20 28 61 6e 64 epare_v2()] (and
1c100 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 6f its variants) o
1c110 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 r [sqlite3_reset
1c120 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72 ()] and.** befor
1c130 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 e [sqlite3_step(
1c140 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20 )]..** Bindings
1c150 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 are not cleared
1c160 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f by the [sqlite3_
1c170 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 reset()] routine
1c180 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72 ..** Unbound par
1c190 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 ameters are inte
1c1a0 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e rpreted as NULL.
1c1b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
1c1c0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 tines return [SQ
1c1d0 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 LITE_OK] on succ
1c1e0 65 73 73 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 ess or an error
1c1f0 63 6f 64 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68 code if.** anyth
1c200 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20 ing goes wrong.
1c210 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 [SQLITE_RANGE]
1c220 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 is returned if t
1c230 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 he parameter.**
1c240 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 index is out of
1c250 72 61 6e 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f range. [SQLITE_
1c260 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e NOMEM] is return
1c270 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 ed if malloc() f
1c280 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 ails..** [SQLITE
1c290 5f 4d 49 53 55 53 45 5d 20 6d 69 67 68 74 20 62 _MISUSE] might b
1c2a0 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 e returned if th
1c2b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
1c2c0 20 63 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20 called on a.**
1c2d0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 virtual machine
1c2e0 74 68 61 74 20 69 73 20 74 68 65 20 77 72 6f 6e that is the wron
1c2f0 67 20 73 74 61 74 65 20 6f 72 20 77 68 69 63 68 g state or which
1c300 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 65 65 has already bee
1c310 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 n finalized..**
1c320 44 65 74 65 63 74 69 6f 6e 20 6f 66 20 6d 69 73 Detection of mis
1c330 75 73 65 20 69 73 20 75 6e 72 65 6c 69 61 62 6c use is unreliabl
1c340 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 e. Applications
1c350 20 73 68 6f 75 6c 64 20 6e 6f 74 20 64 65 70 65 should not depe
1c360 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 5f nd.** on SQLITE_
1c370 4d 49 53 55 53 45 20 72 65 74 75 72 6e 73 2e 20 MISUSE returns.
1c380 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 69 SQLITE_MISUSE i
1c390 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 69 6e s intended to in
1c3a0 64 69 63 61 74 65 20 61 0a 2a 2a 20 61 20 6c 6f dicate a.** a lo
1c3b0 67 69 63 20 65 72 72 6f 72 20 69 6e 20 74 68 65 gic error in the
1c3c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 46 application. F
1c3d0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f uture versions o
1c3e0 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a f SQLite might.*
1c3f0 2a 20 70 61 6e 69 63 20 72 61 74 68 65 72 20 74 * panic rather t
1c400 68 61 6e 20 72 65 74 75 72 6e 20 53 51 4c 49 54 han return SQLIT
1c410 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 E_MISUSE..**.**
1c420 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
1c430 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
1c440 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b r_count()],.** [
1c450 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
1c460 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 ameter_name()],
1c470 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e and [sqlite3_bin
1c480 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 d_parameter_inde
1c490 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 x()]..**.** Requ
1c4a0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
1c4b0 33 35 30 36 5d 20 5b 48 31 33 35 30 39 5d 20 5b 3506] [H13509] [
1c4c0 48 31 33 35 31 32 5d 20 5b 48 31 33 35 31 35 5d H13512] [H13515]
1c4d0 20 5b 48 31 33 35 31 38 5d 20 5b 48 31 33 35 32 [H13518] [H1352
1c4e0 31 5d 20 5b 48 31 33 35 32 34 5d 20 5b 48 31 33 1] [H13524] [H13
1c4f0 35 32 37 5d 0a 2a 2a 20 5b 48 31 33 35 33 30 5d 527].** [H13530]
1c500 20 5b 48 31 33 35 33 33 5d 20 5b 48 31 33 35 33 [H13533] [H1353
1c510 36 5d 20 5b 48 31 33 35 33 39 5d 20 5b 48 31 33 6] [H13539] [H13
1c520 35 34 32 5d 20 5b 48 31 33 35 34 35 5d 20 5b 48 542] [H13545] [H
1c530 31 33 35 34 38 5d 20 5b 48 31 33 35 35 31 5d 0a 13548] [H13551].
1c540 2a 2a 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 **.*/.int sqlite
1c550 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 3_bind_blob(sqli
1c560 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
1c570 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
1c580 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 n, void(*)(void
1c590 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 *));.int sqlite3
1c5a0 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c _bind_double(sql
1c5b0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
1c5c0 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 double);.int sq
1c5d0 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 lite3_bind_int(s
1c5e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
1c5f0 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c t, int);.int sql
1c600 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 ite3_bind_int64(
1c610 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
1c620 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 nt, sqlite3_int6
1c630 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 4);.int sqlite3_
1c640 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 bind_null(sqlite
1c650 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 3_stmt*, int);.i
1c660 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
1c670 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d text(sqlite3_stm
1c680 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 t*, int, const c
1c690 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 har*, int n, voi
1c6a0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e d(*)(void*));.in
1c6b0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 t sqlite3_bind_t
1c6c0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ext16(sqlite3_st
1c6d0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 mt*, int, const
1c6e0 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 void*, int, void
1c6f0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 (*)(void*));.int
1c700 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 sqlite3_bind_va
1c710 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 lue(sqlite3_stmt
1c720 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 *, int, const sq
1c730 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 lite3_value*);.i
1c740 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
1c750 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 zeroblob(sqlite3
1c760 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 _stmt*, int, int
1c770 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 n);../*.** CAPI
1c780 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 3REF: Number Of
1c790 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 20 7b SQL Parameters {
1c7a0 48 31 33 36 30 30 7d 20 3c 53 37 30 33 30 30 3e H13600} <S70300>
1c7b0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
1c7c0 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ine can be used
1c7d0 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 to find the numb
1c7e0 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d er of [SQL param
1c7f0 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b eters].** in a [
1c800 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1c810 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 nt]. SQL parame
1c820 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 ters are tokens
1c830 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 of the.** form "
1c840 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 ?", "?NNN", ":AA
1c850 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 A", "$AAA", or "
1c860 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 @AAA" that serve
1c870 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 as.** placehold
1c880 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 ers for values t
1c890 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 hat are [sqlite3
1c8a0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 _bind_blob | bou
1c8b0 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 nd].** to the pa
1c8c0 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 rameters at a la
1c8d0 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 ter time..**.**
1c8e0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 This routine act
1c8f0 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 ually returns th
1c900 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c e index of the l
1c910 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 argest (rightmos
1c920 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e t).** parameter.
1c930 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 For all forms e
1c940 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 xcept ?NNN, this
1c950 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 will correspond
1c960 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 to the.** numbe
1c970 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 r of unique para
1c980 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 meters. If para
1c990 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e meters of the ?N
1c9a0 4e 4e 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 NN are used,.**
1c9b0 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 there may be gap
1c9c0 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a s in the list..*
1c9d0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
1c9e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
1c9f0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 b|sqlite3_bind()
1ca00 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 ],.** [sqlite3_b
1ca10 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 ind_parameter_na
1ca20 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 me()], and.** [s
1ca30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
1ca40 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a meter_index()]..
1ca50 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
1ca60 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 30 31 5d 0a ts:.** [H13601].
1ca70 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 */.int sqlite3_b
1ca80 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f ind_parameter_co
1ca90 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 unt(sqlite3_stmt
1caa0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
1cab0 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 REF: Name Of A H
1cac0 6f 73 74 20 50 61 72 61 6d 65 74 65 72 20 7b 48 ost Parameter {H
1cad0 31 33 36 32 30 7d 20 3c 53 37 30 33 30 30 3e 0a 13620} <S70300>.
1cae0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
1caf0 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ne returns a poi
1cb00 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 61 6d 65 nter to the name
1cb10 20 6f 66 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20 of the n-th.**
1cb20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 [SQL parameter]
1cb30 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 in a [prepared s
1cb40 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51 tatement]..** SQ
1cb50 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 L parameters of
1cb60 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 the form "?NNN"
1cb70 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 or ":AAA" or "@A
1cb80 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a AA" or "$AAA".**
1cb90 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 have a name whi
1cba0 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 ch is the string
1cbb0 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 "?NNN" or ":AAA
1cbc0 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 " or "@AAA" or "
1cbd0 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 $AAA".** respect
1cbe0 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 ively..** In oth
1cbf0 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e er words, the in
1cc00 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 itial ":" or "$"
1cc10 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a or "@" or "?".*
1cc20 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 * is included as
1cc30 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d part of the nam
1cc40 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 73 e..** Parameters
1cc50 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 of the form "?"
1cc60 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f without a follo
1cc70 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 wing integer hav
1cc80 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 e no name.** and
1cc90 20 61 72 65 20 61 6c 73 6f 20 72 65 66 65 72 72 are also referr
1cca0 65 64 20 74 6f 20 61 73 20 22 61 6e 6f 6e 79 6d ed to as "anonym
1ccb0 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e ous parameters".
1ccc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 .**.** The first
1ccd0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 host parameter
1cce0 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 has an index of
1ccf0 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 1, not 0..**.**
1cd00 49 66 20 74 68 65 20 76 61 6c 75 65 20 6e 20 69 If the value n i
1cd10 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f s out of range o
1cd20 72 20 69 66 20 74 68 65 20 6e 2d 74 68 20 70 61 r if the n-th pa
1cd30 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 rameter is.** na
1cd40 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c meless, then NUL
1cd50 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 L is returned.
1cd60 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 The returned str
1cd70 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 ing is.** always
1cd80 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 in UTF-8 encodi
1cd90 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e ng even if the n
1cda0 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 amed parameter w
1cdb0 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 as.** originally
1cdc0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 specified as UT
1cdd0 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 F-16 in [sqlite3
1cde0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 _prepare16()] or
1cdf0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
1ce00 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a pare16_v2()]..**
1ce10 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
1ce20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
1ce30 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d |sqlite3_bind()]
1ce40 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 ,.** [sqlite3_bi
1ce50 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 nd_parameter_cou
1ce60 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 nt()], and.** [s
1ce70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
1ce80 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a meter_index()]..
1ce90 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
1cea0 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 32 31 5d 0a ts:.** [H13621].
1ceb0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 */.const char *s
1cec0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
1ced0 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 meter_name(sqlit
1cee0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a e3_stmt*, int);.
1cef0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1cf00 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 Index Of A Para
1cf10 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 meter With A Giv
1cf20 65 6e 20 4e 61 6d 65 20 7b 48 31 33 36 34 30 7d en Name {H13640}
1cf30 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S70300>.**.**
1cf40 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 Return the index
1cf50 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d of an SQL param
1cf60 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e eter given its n
1cf70 61 6d 65 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 64 ame. The.** ind
1cf80 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 ex value returne
1cf90 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f d is suitable fo
1cfa0 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63 r use as the sec
1cfb0 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ond.** parameter
1cfc0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e to [sqlite3_bin
1cfd0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 d_blob|sqlite3_b
1cfe0 69 6e 64 28 29 5d 2e 20 20 41 20 7a 65 72 6f 0a ind()]. A zero.
1cff0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 ** is returned i
1d000 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 f no matching pa
1d010 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 rameter is found
1d020 2e 20 20 54 68 65 20 70 61 72 61 6d 65 74 65 72 . The parameter
1d030 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 .** name must be
1d040 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 given in UTF-8
1d050 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 even if the orig
1d060 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a inal statement.*
1d070 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 * was prepared f
1d080 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 rom UTF-16 text
1d090 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 using [sqlite3_p
1d0a0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a repare16_v2()]..
1d0b0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
1d0c0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
1d0d0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 ob|sqlite3_bind(
1d0e0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
1d0f0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 bind_parameter_c
1d100 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 ount()], and.**
1d110 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
1d120 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d rameter_index()]
1d130 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
1d140 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 34 31 ents:.** [H13641
1d150 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ].*/.int sqlite3
1d160 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
1d170 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 index(sqlite3_st
1d180 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 mt*, const char
1d190 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *zName);../*.**
1d1a0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 CAPI3REF: Reset
1d1b0 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 All Bindings On
1d1c0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 A Prepared State
1d1d0 6d 65 6e 74 20 7b 48 31 33 36 36 30 7d 20 3c 53 ment {H13660} <S
1d1e0 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 70300>.**.** Con
1d1f0 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 trary to the int
1d200 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 uition of many,
1d210 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
1d220 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 ] does not reset
1d230 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 .** the [sqlite3
1d240 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e _bind_blob | bin
1d250 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 dings] on a [pre
1d260 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
1d270 2e 0a 2a 2a 20 55 73 65 20 74 68 69 73 20 72 6f ..** Use this ro
1d280 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 utine to reset a
1d290 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 ll host paramete
1d2a0 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a rs to NULL..**.*
1d2b0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
1d2c0 2a 2a 20 5b 48 31 33 36 36 31 5d 0a 2a 2f 0a 69 ** [H13661].*/.i
1d2d0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 nt sqlite3_clear
1d2e0 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 _bindings(sqlite
1d2f0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 3_stmt*);../*.**
1d300 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 CAPI3REF: Numbe
1d310 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 r Of Columns In
1d320 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b 48 31 A Result Set {H1
1d330 33 37 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 3710} <S10700>.*
1d340 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 *.** Return the
1d350 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e number of column
1d360 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 s in the result
1d370 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 set returned by
1d380 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 the.** [prepared
1d390 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54 68 69 statement]. Thi
1d3a0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e s routine return
1d3b0 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 s 0 if pStmt is
1d3c0 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d an SQL.** statem
1d3d0 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f ent that does no
1d3e0 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 t return data (f
1d3f0 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 or example an [U
1d400 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 52 PDATE])..**.** R
1d410 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
1d420 5b 48 31 33 37 31 31 5d 0a 2a 2f 0a 69 6e 74 20 [H13711].*/.int
1d430 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 sqlite3_column_c
1d440 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d ount(sqlite3_stm
1d450 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
1d460 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 * CAPI3REF: Colu
1d470 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 mn Names In A Re
1d480 73 75 6c 74 20 53 65 74 20 7b 48 31 33 37 32 30 sult Set {H13720
1d490 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a } <S10700>.**.**
1d4a0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
1d4b0 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 return the name
1d4c0 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 assigned to a pa
1d4d0 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a rticular column.
1d4e0 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 ** in the result
1d4f0 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 set of a [SELEC
1d500 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 T] statement. T
1d510 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d he sqlite3_colum
1d520 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 n_name().** inte
1d530 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
1d540 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 pointer to a zer
1d550 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 o-terminated UTF
1d560 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 -8 string.** and
1d570 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
1d580 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 name16() returns
1d590 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
1d5a0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a zero-terminated.
1d5b0 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 ** UTF-16 string
1d5c0 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 . The first par
1d5d0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 ameter is the [p
1d5e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
1d5f0 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 t].** that imple
1d600 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 ments the [SELEC
1d610 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 54 68 T] statement. Th
1d620 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
1d630 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c er is the.** col
1d640 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 umn number. The
1d650 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e leftmost column
1d660 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a is number 0..**
1d670 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 .** The returned
1d680 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 string pointer
1d690 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 is valid until e
1d6a0 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 ither the [prepa
1d6b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a red statement].*
1d6c0 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 * is destroyed b
1d6d0 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c y [sqlite3_final
1d6e0 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 ize()] or until
1d6f0 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f the next call to
1d700 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 .** sqlite3_colu
1d710 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c mn_name() or sql
1d720 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
1d730 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 16() on the same
1d740 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 column..**.** I
1d750 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 f sqlite3_malloc
1d760 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 () fails during
1d770 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f the processing o
1d780 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 f either routine
1d790 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 .** (for example
1d7a0 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 during a conver
1d7b0 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 sion from UTF-8
1d7c0 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 to UTF-16) then
1d7d0 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 a.** NULL pointe
1d7e0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a r is returned..*
1d7f0 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 *.** The name of
1d800 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e a result column
1d810 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 is the value of
1d820 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 the "AS" clause
1d830 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c for.** that col
1d840 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 umn, if there is
1d850 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 an AS clause.
1d860 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 If there is no A
1d870 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e S clause.** then
1d880 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
1d890 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 column is unspe
1d8a0 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 cified and may c
1d8b0 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e hange from.** on
1d8c0 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c e release of SQL
1d8d0 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e ite to the next.
1d8e0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
1d8f0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 32 31 5d nts:.** [H13721]
1d900 20 5b 48 31 33 37 32 33 5d 20 5b 48 31 33 37 32 [H13723] [H1372
1d910 34 5d 20 5b 48 31 33 37 32 35 5d 20 5b 48 31 33 4] [H13725] [H13
1d920 37 32 36 5d 20 5b 48 31 33 37 32 37 5d 0a 2a 2f 726] [H13727].*/
1d930 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
1d940 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
1d950 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
1d960 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f int N);.const vo
1d970 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 id *sqlite3_colu
1d980 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 mn_name16(sqlite
1d990 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 3_stmt*, int N);
1d9a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1d9b0 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 : Source Of Data
1d9c0 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 In A Query Resu
1d9d0 6c 74 20 7b 48 31 33 37 34 30 7d 20 3c 53 31 30 lt {H13740} <S10
1d9e0 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 700>.**.** These
1d9f0 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 routines provid
1da00 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 e a means to det
1da10 65 72 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c 75 ermine what colu
1da20 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61 mn of what.** ta
1da30 62 6c 65 20 69 6e 20 77 68 69 63 68 20 64 61 74 ble in which dat
1da40 61 62 61 73 65 20 61 20 72 65 73 75 6c 74 20 6f abase a result o
1da50 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 f a [SELECT] sta
1da60 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f tement comes fro
1da70 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f m..** The name o
1da80 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f f the database o
1da90 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d r table or colum
1daa0 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 n can be returne
1dab0 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 d as.** either a
1dac0 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 UTF-8 or UTF-16
1dad0 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 string. The _d
1dae0 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 atabase_ routine
1daf0 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 s return.** the
1db00 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 database name, t
1db10 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 he _table_ routi
1db20 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 nes return the t
1db30 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a able name, and.*
1db40 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f * the origin_ ro
1db50 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 utines return th
1db60 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a e column name..*
1db70 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 * The returned s
1db80 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 tring is valid u
1db90 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 ntil the [prepar
1dba0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 ed statement] is
1dbb0 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 destroyed.** us
1dbc0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e ing [sqlite3_fin
1dbd0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 alize()] or unti
1dbe0 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 l the same infor
1dbf0 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 mation is reques
1dc00 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 ted.** again in
1dc10 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f a different enco
1dc20 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ding..**.** The
1dc30 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 names returned a
1dc40 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 re the original
1dc50 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 un-aliased names
1dc60 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 of the.** datab
1dc70 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 ase, table, and
1dc80 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 column..**.** Th
1dc90 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
1dca0 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e to the followin
1dcb0 67 20 63 61 6c 6c 73 20 69 73 20 61 20 5b 70 72 g calls is a [pr
1dcc0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1dcd0 5d 2e 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 ]..** These func
1dce0 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 tions return inf
1dcf0 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 ormation about t
1dd00 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 he Nth column re
1dd10 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 turned by.** the
1dd20 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 statement, wher
1dd30 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e e N is the secon
1dd40 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d d function argum
1dd50 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ent..**.** If th
1dd60 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 e Nth column ret
1dd70 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 urned by the sta
1dd80 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 tement is an exp
1dd90 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 ression or.** su
1dda0 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f bquery and is no
1ddb0 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 t a column value
1ddc0 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 , then all of th
1ddd0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 ese functions re
1dde0 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 54 turn.** NULL. T
1ddf0 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 hese routine mig
1de00 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e ht also return N
1de10 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 ULL if a memory
1de20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 allocation error
1de30 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 4f 74 68 .** occurs. Oth
1de40 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 erwise, they ret
1de50 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 urn the name of
1de60 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 the attached dat
1de70 61 62 61 73 65 2c 20 74 61 62 6c 65 0a 2a 2a 20 abase, table.**
1de80 61 6e 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 and column that
1de90 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c query result col
1dea0 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 umn was extracte
1deb0 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 d from..**.** As
1dec0 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 with all other
1ded0 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f SQLite APIs, tho
1dee0 73 65 20 70 6f 73 74 66 69 78 65 64 20 77 69 74 se postfixed wit
1def0 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a h "16" return.**
1df00 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 UTF-16 encoded
1df10 73 74 72 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 strings, the oth
1df20 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 er functions ret
1df30 75 72 6e 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d urn UTF-8. {END}
1df40 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 .**.** These API
1df50 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c s are only avail
1df60 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 able if the libr
1df70 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 ary was compiled
1df80 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 with the.** [SQ
1df90 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 LITE_ENABLE_COLU
1dfa0 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 MN_METADATA] C-p
1dfb0 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 reprocessor symb
1dfc0 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a ol defined..**.*
1dfd0 2a 20 7b 41 31 33 37 35 31 7d 0a 2a 2a 20 49 66 * {A13751}.** If
1dfe0 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 two or more thr
1dff0 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 eads call one or
1e000 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 more of these r
1e010 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 outines against
1e020 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 the same.** prep
1e030 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 ared statement a
1e040 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 nd column at the
1e050 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 same time then
1e060 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a the results are.
1e070 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a ** undefined..**
1e080 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
1e090 3a 0a 2a 2a 20 5b 48 31 33 37 34 31 5d 20 5b 48 :.** [H13741] [H
1e0a0 31 33 37 34 32 5d 20 5b 48 31 33 37 34 33 5d 20 13742] [H13743]
1e0b0 5b 48 31 33 37 34 34 5d 20 5b 48 31 33 37 34 35 [H13744] [H13745
1e0c0 5d 20 5b 48 31 33 37 34 36 5d 20 5b 48 31 33 37 ] [H13746] [H137
1e0d0 34 38 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 48].**.** If two
1e0e0 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 or more threads
1e0f0 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 call one or mor
1e100 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f e.** [sqlite3_co
1e110 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 lumn_database_na
1e120 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 me | column meta
1e130 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d data interfaces]
1e140 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 .** for the same
1e150 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
1e160 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 ment] and result
1e170 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 column.** at th
1e180 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e e same time then
1e190 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 the results are
1e1a0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 undefined..*/.c
1e1b0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
1e1c0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 e3_column_databa
1e1d0 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f se_name(sqlite3_
1e1e0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 stmt*,int);.cons
1e1f0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
1e200 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f column_database_
1e210 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 name16(sqlite3_s
1e220 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 tmt*,int);.const
1e230 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 char *sqlite3_c
1e240 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 olumn_table_name
1e250 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
1e260 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 nt);.const void
1e270 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
1e280 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c table_name16(sql
1e290 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
1e2a0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
1e2b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 ite3_column_orig
1e2c0 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f in_name(sqlite3_
1e2d0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 stmt*,int);.cons
1e2e0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
1e2f0 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 column_origin_na
1e300 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d me16(sqlite3_stm
1e310 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 t*,int);../*.**
1e320 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 CAPI3REF: Declar
1e330 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 ed Datatype Of A
1e340 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48 Query Result {H
1e350 31 33 37 36 30 7d 20 3c 53 31 30 37 30 30 3e 0a 13760} <S10700>.
1e360 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
1e370 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b parameter is a [
1e380 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1e390 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 nt]..** If this
1e3a0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b statement is a [
1e3b0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
1e3c0 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f t and the Nth co
1e3d0 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 lumn of the.** r
1e3e0 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 eturned result s
1e3f0 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 et of that [SELE
1e400 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 CT] is a table c
1e410 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a olumn (not an.**
1e420 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 expression or s
1e430 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 ubquery) then th
1e440 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 e declared type
1e450 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 of the table.**
1e460 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e column is return
1e470 65 64 2e 20 20 49 66 20 74 68 65 20 4e 74 68 20 ed. If the Nth
1e480 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 column of the re
1e490 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a sult set is an.*
1e4a0 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 * expression or
1e4b0 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 subquery, then a
1e4c0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 NULL pointer is
1e4d0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 returned..** Th
1e4e0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e e returned strin
1e4f0 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d g is always UTF-
1e500 38 20 65 6e 63 6f 64 65 64 2e 20 7b 45 4e 44 7d 8 encoded. {END}
1e510 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 .**.** For examp
1e520 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 le, given the da
1e530 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a tabase schema:.*
1e540 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c *.** CREATE TABL
1e550 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 E t1(c1 VARIANT)
1e560 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 ;.**.** and the
1e570 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d following statem
1e580 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c ent to be compil
1e590 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 ed:.**.** SELECT
1e5a0 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d c1 + 1, c1 FROM
1e5b0 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 t1;.**.** this
1e5c0 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 routine would re
1e5d0 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 turn the string
1e5e0 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 "VARIANT" for th
1e5f0 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a e second result.
1e600 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 ** column (i==1)
1e610 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 , and a NULL poi
1e620 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 nter for the fir
1e630 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e st result column
1e640 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 (i==0)..**.** S
1e650 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d QLite uses dynam
1e660 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 ic run-time typi
1e670 6e 67 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63 ng. So just bec
1e680 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a ause a column.**
1e690 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 is declared to
1e6a0 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 contain a partic
1e6b0 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e ular type does n
1e6c0 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 ot mean that the
1e6d0 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 .** data stored
1e6e0 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 in that column i
1e6f0 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 s of the declare
1e700 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 d type. SQLite
1e710 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 is.** strongly t
1e720 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 yped, but the ty
1e730 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 ping is dynamic
1e740 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 54 79 70 not static. Typ
1e750 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 e.** is associat
1e760 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 ed with individu
1e770 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 al values, not w
1e780 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 ith the containe
1e790 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f rs.** used to ho
1e7a0 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e ld those values.
1e7b0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
1e7c0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 36 31 5d nts:.** [H13761]
1e7d0 20 5b 48 31 33 37 36 32 5d 20 5b 48 31 33 37 36 [H13762] [H1376
1e7e0 33 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 3].*/.const char
1e7f0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
1e800 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 _decltype(sqlite
1e810 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 3_stmt*,int);.co
1e820 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
1e830 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 3_column_decltyp
1e840 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 e16(sqlite3_stmt
1e850 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 *,int);../*.** C
1e860 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 API3REF: Evaluat
1e870 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 e An SQL Stateme
1e880 6e 74 20 7b 48 31 33 32 30 30 7d 20 3c 53 31 30 nt {H13200} <S10
1e890 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 000>.**.** After
1e8a0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
1e8b0 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e tement] has been
1e8c0 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 prepared using
1e8d0 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 either.** [sqlit
1e8e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
1e8f0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 or [sqlite3_pre
1e900 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 pare16_v2()] or
1e910 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 one of the legac
1e920 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 y.** interfaces
1e930 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1e940 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
1e950 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 prepare16()], th
1e960 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d is function.** m
1e970 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e ust be called on
1e980 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 e or more times
1e990 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 to evaluate the
1e9a0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a statement..**.**
1e9b0 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 The details of
1e9c0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 the behavior of
1e9d0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 the sqlite3_step
1e9e0 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 () interface dep
1e9f0 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 end.** on whethe
1ea00 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 r the statement
1ea10 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69 was prepared usi
1ea20 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 ng the newer "v2
1ea30 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b " interface.** [
1ea40 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
1ea50 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 v2()] and [sqlit
1ea60 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
1ea70 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 )] or the older
1ea80 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 legacy.** interf
1ea90 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 ace [sqlite3_pre
1eaa0 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c pare()] and [sql
1eab0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
1eac0 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 ]. The use of t
1ead0 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 he.** new "v2" i
1eae0 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f nterface is reco
1eaf0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 mmended for new
1eb00 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 applications but
1eb10 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 the legacy.** i
1eb20 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f nterface will co
1eb30 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 ntinue to be sup
1eb40 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e ported..**.** In
1eb50 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 the legacy inte
1eb60 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 rface, the retur
1eb70 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 n value will be
1eb80 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 either [SQLITE_B
1eb90 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 USY],.** [SQLITE
1eba0 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f _DONE], [SQLITE_
1ebb0 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 ROW], [SQLITE_ER
1ebc0 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 ROR], or [SQLITE
1ebd0 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 _MISUSE]..** Wit
1ebe0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 h the "v2" inter
1ebf0 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 face, any of the
1ec00 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 other [result c
1ec10 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 odes] or.** [ext
1ec20 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
1ec30 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 es] might be ret
1ec40 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a urned as well..*
1ec50 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 *.** [SQLITE_BUS
1ec60 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 Y] means that th
1ec70 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e e database engin
1ec80 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 e was unable to
1ec90 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 acquire the.** d
1eca0 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 atabase locks it
1ecb0 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 needs to do its
1ecc0 20 6a 6f 62 2e 20 20 49 66 20 74 68 65 20 73 74 job. If the st
1ecd0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f atement is a [CO
1ece0 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 MMIT].** or occu
1ecf0 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e rs outside of an
1ed00 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 explicit transa
1ed10 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 ction, then you
1ed20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a can retry the.**
1ed30 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 statement. If
1ed40 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 the statement is
1ed50 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 not a [COMMIT]
1ed60 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 and occurs withi
1ed70 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 n a.** explicit
1ed80 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e transaction then
1ed90 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c you should roll
1eda0 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 back the transac
1edb0 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 tion before.** c
1edc0 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a ontinuing..**.**
1edd0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d [SQLITE_DONE] m
1ede0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 eans that the st
1edf0 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 atement has fini
1ee00 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a shed executing.*
1ee10 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 * successfully.
1ee20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
1ee30 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 should not be ca
1ee40 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 lled again on th
1ee50 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 is virtual.** ma
1ee60 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 chine without fi
1ee70 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c rst calling [sql
1ee80 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f ite3_reset()] to
1ee90 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 reset the virtu
1eea0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 al.** machine ba
1eeb0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 ck to its initia
1eec0 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 l state..**.** I
1eed0 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d f the SQL statem
1eee0 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 ent being execut
1eef0 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 ed returns any d
1ef00 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 ata, then [SQLIT
1ef10 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 E_ROW].** is ret
1ef20 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 urned each time
1ef30 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 a new row of dat
1ef40 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 a is ready for p
1ef50 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 rocessing by the
1ef60 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 .** caller. The
1ef70 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 values may be ac
1ef80 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 cessed using the
1ef90 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 [column access
1efa0 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 functions]..** s
1efb0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 qlite3_step() is
1efc0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f called again to
1efd0 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 retrieve the ne
1efe0 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a xt row of data..
1eff0 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 **.** [SQLITE_ER
1f000 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 ROR] means that
1f010 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 a run-time error
1f020 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 (such as a cons
1f030 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 traint.** violat
1f040 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 ion) has occurre
1f050 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 d. sqlite3_step
1f060 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 () should not be
1f070 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e called again on
1f080 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 .** the VM. More
1f090 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 information may
1f0a0 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c be found by cal
1f0b0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 ling [sqlite3_er
1f0c0 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 rmsg()]..** With
1f0d0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 the legacy inte
1f0e0 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 rface, a more sp
1f0f0 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 ecific error cod
1f100 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a e (for example,.
1f110 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 ** [SQLITE_INTER
1f120 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 RUPT], [SQLITE_S
1f130 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f CHEMA], [SQLITE_
1f140 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f CORRUPT], and so
1f150 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 forth).** can b
1f160 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 e obtained by ca
1f170 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 lling [sqlite3_r
1f180 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a eset()] on the.*
1f190 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 * [prepared stat
1f1a0 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20 ement]. In the
1f1b0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a "v2" interface,.
1f1c0 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 ** the more spec
1f1d0 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 ific error code
1f1e0 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 is returned dire
1f1f0 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f ctly by sqlite3_
1f200 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 step()..**.** [S
1f210 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 QLITE_MISUSE] me
1f220 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69 ans that the thi
1f230 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 s routine was ca
1f240 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 lled inappropria
1f250 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 tely..** Perhaps
1f260 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f it was called o
1f270 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 n a [prepared st
1f280 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 atement] that ha
1f290 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 s.** already bee
1f2a0 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c n [sqlite3_final
1f2b0 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d ize | finalized]
1f2c0 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 or on one that
1f2d0 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c had.** previousl
1f2e0 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 y returned [SQLI
1f2f0 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 TE_ERROR] or [SQ
1f300 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 LITE_DONE]. Or
1f310 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 it could.** be t
1f320 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 he case that the
1f330 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 same database c
1f340 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 onnection is bei
1f350 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f ng used by two o
1f360 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 r.** more thread
1f370 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f s at the same mo
1f380 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a ment in time..**
1f390 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 .** <b>Goofy Int
1f3a0 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 erface Alert:</b
1f3b0 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 > In the legacy
1f3c0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 interface, the s
1f3d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a qlite3_step().**
1f3e0 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 API always retu
1f3f0 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 rns a generic er
1f400 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 ror code, [SQLIT
1f410 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 E_ERROR], follow
1f420 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 ing any.** error
1f430 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c other than [SQL
1f440 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 ITE_BUSY] and [S
1f450 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 QLITE_MISUSE].
1f460 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a You must call.**
1f470 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
1f480 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 )] or [sqlite3_f
1f490 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 inalize()] in or
1f4a0 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 der to find one
1f4b0 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 of the.** specif
1f4c0 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d ic [error codes]
1f4d0 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 that better des
1f4e0 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 cribes the error
1f4f0 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 ..** We admit th
1f500 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f at this is a goo
1f510 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 fy design. The
1f520 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e problem has been
1f530 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 fixed.** with t
1f540 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 he "v2" interfac
1f550 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 e. If you prepa
1f560 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 re all of your S
1f570 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a QL statements.**
1f580 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 using either [s
1f590 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1f5a0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 2()] or [sqlite3
1f5b0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
1f5c0 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 instead.** of t
1f5d0 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 he legacy [sqlit
1f5e0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e e3_prepare()] an
1f5f0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 d [sqlite3_prepa
1f600 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 re16()] interfac
1f610 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 es,.** then the
1f620 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 more specific [e
1f630 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 rror codes] are
1f640 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c returned directl
1f650 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f y.** by sqlite3_
1f660 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 step(). The use
1f670 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 of the "v2" int
1f680 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d erface is recomm
1f690 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 ended..**.** Req
1f6a0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
1f6b0 31 33 32 30 32 5d 20 5b 48 31 35 33 30 34 5d 20 13202] [H15304]
1f6c0 5b 48 31 35 33 30 36 5d 20 5b 48 31 35 33 30 38 [H15306] [H15308
1f6d0 5d 20 5b 48 31 35 33 31 30 5d 0a 2a 2f 0a 69 6e ] [H15310].*/.in
1f6e0 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 t sqlite3_step(s
1f6f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a qlite3_stmt*);..
1f700 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1f710 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e Number of column
1f720 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 s in a result se
1f730 74 20 7b 48 31 33 37 37 30 7d 20 3c 53 31 30 37 t {H13770} <S107
1f740 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 00>.**.** Return
1f750 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
1f760 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20 63 75 values in the cu
1f770 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 rrent row of the
1f780 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a result set..**.
1f790 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
1f7a0 0a 2a 2a 20 5b 48 31 33 37 37 31 5d 20 5b 48 31 .** [H13771] [H1
1f7b0 33 37 37 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 3772].*/.int sql
1f7c0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 ite3_data_count(
1f7d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
1f7e0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tmt);../*.** CAP
1f7f0 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 I3REF: Fundament
1f800 61 6c 20 44 61 74 61 74 79 70 65 73 20 7b 48 31 al Datatypes {H1
1f810 30 32 36 35 7d 20 3c 53 31 30 31 31 30 3e 3c 53 0265} <S10110><S
1f820 31 30 31 32 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 10120>.** KEYWOR
1f830 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a DS: SQLITE_TEXT.
1f840 2a 2a 0a 2a 2a 20 7b 48 31 30 32 36 36 7d 20 45 **.** {H10266} E
1f850 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 very value in SQ
1f860 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 Lite has one of
1f870 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c five fundamental
1f880 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a datatypes:.**.*
1f890 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 * <ul>.** <li> 6
1f8a0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 4-bit signed int
1f8b0 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d eger.** <li> 64-
1f8c0 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e bit IEEE floatin
1f8d0 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a g point number.*
1f8e0 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a * <li> string.**
1f8f0 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c <li> BLOB.** <l
1f900 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e i> NULL.** </ul>
1f910 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 {END}.**.** The
1f920 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 se constants are
1f930 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 codes for each
1f940 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a of those types..
1f950 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 **.** Note that
1f960 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 the SQLITE_TEXT
1f970 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 constant was als
1f980 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 o used in SQLite
1f990 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f version 2.** fo
1f9a0 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 r a completely d
1f9b0 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 ifferent meaning
1f9c0 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 . Software that
1f9d0 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 links against b
1f9e0 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 oth.** SQLite ve
1f9f0 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 rsion 2 and SQLi
1fa00 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f te version 3 sho
1fa10 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f uld use SQLITE3_
1fa20 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c TEXT, not.** SQL
1fa30 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 ITE_TEXT..*/.#de
1fa40 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 fine SQLITE_INTE
1fa50 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 GER 1.#define S
1fa60 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 QLITE_FLOAT 2
1fa70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1fa80 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 BLOB 4.#defi
1fa90 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 ne SQLITE_NULL
1faa0 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 5.#ifdef SQLI
1fab0 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 TE_TEXT.# undef
1fac0 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 SQLITE_TEXT.#els
1fad0 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 e.# define SQLIT
1fae0 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e E_TEXT 3.#en
1faf0 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 dif.#define SQLI
1fb00 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a TE3_TEXT 3..
1fb10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1fb20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 Result Values Fr
1fb30 6f 6d 20 41 20 51 75 65 72 79 20 7b 48 31 33 38 om A Query {H138
1fb40 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 00} <S10700>.**
1fb50 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d KEYWORDS: {colum
1fb60 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f n access functio
1fb70 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ns}.**.** These
1fb80 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 routines form th
1fb90 65 20 22 72 65 73 75 6c 74 20 73 65 74 20 71 75 e "result set qu
1fba0 65 72 79 22 20 69 6e 74 65 72 66 61 63 65 2e 0a ery" interface..
1fbb0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
1fbc0 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f ines return info
1fbd0 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 rmation about a
1fbe0 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 single column of
1fbf0 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 the current.**
1fc00 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 result row of a
1fc10 71 75 65 72 79 2e 20 20 49 6e 20 65 76 65 72 79 query. In every
1fc20 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 case the first
1fc30 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f argument is a po
1fc40 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 inter.** to the
1fc50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
1fc60 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 ent] that is bei
1fc70 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 ng evaluated (th
1fc80 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a e [sqlite3_stmt*
1fc90 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 ].** that was re
1fca0 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c turned from [sql
1fcb0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
1fcc0 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 )] or one of its
1fcd0 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e variants).** an
1fce0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 d the second arg
1fcf0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 ument is the ind
1fd00 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e ex of the column
1fd10 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 for which infor
1fd20 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 mation.** should
1fd30 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20 54 be returned. T
1fd40 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 he leftmost colu
1fd50 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 mn of the result
1fd60 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 set has the ind
1fd70 65 78 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 ex 0..**.** If t
1fd80 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
1fd90 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e does not curren
1fda0 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 tly point to a v
1fdb0 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 alid row, or if
1fdc0 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e the.** column in
1fdd0 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 dex is out of ra
1fde0 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 nge, the result
1fdf0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a is undefined..**
1fe00 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
1fe10 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c may only be call
1fe20 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 ed when the most
1fe30 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a recent call to.
1fe40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ** [sqlite3_step
1fe50 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 ()] has returned
1fe60 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e [SQLITE_ROW] an
1fe70 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 d neither.** [sq
1fe80 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e lite3_reset()] n
1fe90 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 or [sqlite3_fina
1fea0 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 lize()] have bee
1feb0 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 n called subsequ
1fec0 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 ently..** If any
1fed0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e of these routin
1fee0 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 es are called af
1fef0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ter [sqlite3_res
1ff00 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c et()] or.** [sql
1ff10 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
1ff20 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 or after [sqlit
1ff30 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 e3_step()] has r
1ff40 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 eturned.** somet
1ff50 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 hing other than
1ff60 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 [SQLITE_ROW], th
1ff70 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e e results are un
1ff80 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b defined..** If [
1ff90 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
1ffa0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 or [sqlite3_rese
1ffb0 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 t()] or [sqlite3
1ffc0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 _finalize()].**
1ffd0 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 are called from
1ffe0 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 a different thre
1fff0 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 ad while any of
20000 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a these routines.*
20010 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 * are pending, t
20020 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 hen the results
20030 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a are undefined..*
20040 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
20050 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 _column_type() r
20060 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 outine returns t
20070 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e he.** [SQLITE_IN
20080 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 TEGER | datatype
20090 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 code] for the i
200a0 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 nitial data type
200b0 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c .** of the resul
200c0 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72 t column. The r
200d0 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 eturned value is
200e0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f one of [SQLITE_
200f0 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 INTEGER],.** [SQ
20100 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 LITE_FLOAT], [SQ
20110 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c LITE_TEXT], [SQL
20120 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 ITE_BLOB], or [S
20130 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 QLITE_NULL]. Th
20140 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 e value.** retur
20150 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 ned by sqlite3_c
20160 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 olumn_type() is
20170 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 only meaningful
20180 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f if no type.** co
20190 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f nversions have o
201a0 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72 ccurred as descr
201b0 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 ibed below. Aft
201c0 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 er a type conver
201d0 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c sion,.** the val
201e0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ue returned by s
201f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 qlite3_column_ty
20200 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 pe() is undefine
20210 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 d. Future.** ve
20220 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
20230 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 may change the
20240 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 behavior of sqli
20250 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 te3_column_type(
20260 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 ).** following a
20270 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e type conversion
20280 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 ..**.** If the r
20290 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 esult is a BLOB
202a0 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 or UTF-8 string
202b0 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 then the sqlite3
202c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a _column_bytes().
202d0 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 ** routine retur
202e0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
202f0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 bytes in that B
20300 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a LOB or string..*
20310 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 * If the result
20320 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 is a UTF-16 stri
20330 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ng, then sqlite3
20340 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 _column_bytes()
20350 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 converts.** the
20360 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 string to UTF-8
20370 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 and then returns
20380 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
20390 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 ytes..** If the
203a0 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 result is a nume
203b0 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 ric value then s
203c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
203d0 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 tes() uses.** [s
203e0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
203f0 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 )] to convert th
20400 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 at value to a UT
20410 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 F-8 string and r
20420 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 eturns.** the nu
20430 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e mber of bytes in
20440 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a that string..**
20450 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 The value retur
20460 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 ned does not inc
20470 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 lude the zero te
20480 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20 rminator at the
20490 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 end.** of the st
204a0 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72 69 ring. For clari
204b0 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72 65 ty: the value re
204c0 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e 75 turned is the nu
204d0 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 mber of.** bytes
204e0 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 in the string,
204f0 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f not the number o
20500 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a f characters..**
20510 0a 2a 2a 20 53 74 72 69 6e 67 73 20 72 65 74 75 .** Strings retu
20520 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
20530 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e column_text() an
20540 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e d sqlite3_column
20550 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 _text16(),.** ev
20560 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 en empty strings
20570 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 , are always zer
20580 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 o terminated. T
20590 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c he return.** val
205a0 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ue from sqlite3_
205b0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f column_blob() fo
205c0 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 r a zero-length
205d0 42 4c 4f 42 20 69 73 20 61 6e 20 61 72 62 69 74 BLOB is an arbit
205e0 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c rary.** pointer,
205f0 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 61 possibly even a
20600 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a NULL pointer..*
20610 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
20620 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
20630 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d ) routine is sim
20640 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f ilar to sqlite3_
20650 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a column_bytes().*
20660 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74 68 65 * but leaves the
20670 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 result in UTF-1
20680 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 6 in native byte
20690 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f order instead o
206a0 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 54 68 65 20 f UTF-8..** The
206b0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 zero terminator
206c0 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 is not included
206d0 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a in this count..*
206e0 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a 65 63 74 20 *.** The object
206f0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c returned by [sql
20700 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 ite3_column_valu
20710 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 e()] is an.** [u
20720 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
20730 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
20740 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 . An unprotecte
20750 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 d sqlite3_value
20760 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e object.** may on
20770 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20 ly be used with
20780 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 [sqlite3_bind_va
20790 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 lue()] and [sqli
207a0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 te3_result_value
207b0 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b ()]..** If the [
207c0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
207d0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
207e0 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a t returned by.**
207f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
20800 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 _value()] is use
20810 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 d in any other w
20820 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 ay, including ca
20830 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e lls.** to routin
20840 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 es like [sqlite3
20850 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b _value_int()], [
20860 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
20870 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 xt()],.** or [sq
20880 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 lite3_value_byte
20890 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 s()], then the b
208a0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 ehavior is undef
208b0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ined..**.** Thes
208c0 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d e routines attem
208d0 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 pt to convert th
208e0 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 e value where ap
208f0 70 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a propriate. For.
20900 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 ** example, if t
20910 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 he internal repr
20920 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c esentation is FL
20930 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 OAT and a text r
20940 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 esult.** is requ
20950 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f ested, [sqlite3_
20960 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 snprintf()] is u
20970 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 sed internally t
20980 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a o perform the.**
20990 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f conversion auto
209a0 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 matically. The
209b0 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 following table
209c0 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 details the conv
209d0 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 ersions.** that
209e0 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a are applied:.**.
209f0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a ** <blockquote>.
20a00 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 ** <table border
20a10 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 ="1">.** <tr><th
20a20 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 > Internal<br>Ty
20a30 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 pe <th> Requeste
20a40 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 d<br>Type <th>
20a50 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a Conversion.**.**
20a60 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 <tr><td> NULL
20a70 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 <td> INTEGER
20a80 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 <td> Result is
20a90 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 0.** <tr><td>
20aa0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c NULL <td> FL
20ab0 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 OAT <td> Resu
20ac0 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 lt is 0.0.** <tr
20ad0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c ><td> NULL <
20ae0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 td> TEXT <t
20af0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c d> Result is NUL
20b00 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 L pointer.** <tr
20b10 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c ><td> NULL <
20b20 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 td> BLOB <t
20b30 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c d> Result is NUL
20b40 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 L pointer.** <tr
20b50 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c ><td> INTEGER <
20b60 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 td> FLOAT <t
20b70 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 d> Convert from
20b80 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 integer to float
20b90 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 .** <tr><td> INT
20ba0 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 EGER <td> TEX
20bb0 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 T <td> ASCII
20bc0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 rendering of the
20bd0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e integer.** <tr>
20be0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 <td> INTEGER <t
20bf0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 d> BLOB <td
20c00 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 > Same as INTEGE
20c10 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c R->TEXT.** <tr><
20c20 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 td> FLOAT <td
20c30 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e > INTEGER <td>
20c40 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c Convert from fl
20c50 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a oat to integer.*
20c60 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 * <tr><td> FLOA
20c70 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 T <td> TEXT
20c80 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 <td> ASCII re
20c90 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 ndering of the f
20ca0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e loat.** <tr><td>
20cb0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 FLOAT <td>
20cc0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 BLOB <td> Sa
20cd0 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 me as FLOAT->TEX
20ce0 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 T.** <tr><td> T
20cf0 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 EXT <td> INTE
20d00 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 GER <td> Use a
20d10 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 toi().** <tr><td
20d20 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 > TEXT <td>
20d30 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 FLOAT <td> U
20d40 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 se atof().** <tr
20d50 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c ><td> TEXT <
20d60 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 td> BLOB <t
20d70 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 d> No change.**
20d80 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 <tr><td> BLOB
20d90 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 <td> INTEGER
20da0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f <td> Convert to
20db0 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 TEXT then use a
20dc0 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 toi().** <tr><td
20dd0 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 > BLOB <td>
20de0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 FLOAT <td> C
20df0 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 onvert to TEXT t
20e00 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a hen use atof().*
20e10 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 * <tr><td> BLOB
20e20 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 <td> TEXT
20e30 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 <td> Add a ze
20e40 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 ro terminator if
20e50 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 needed.** </tab
20e60 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 le>.** </blockqu
20e70 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 ote>.**.** The t
20e80 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 able above makes
20e90 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 reference to st
20ea0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 andard C library
20eb0 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 functions atoi(
20ec0 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e ).** and atof().
20ed0 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f SQLite does no
20ee0 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 t really use the
20ef0 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 se functions. I
20f00 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e t has its.** own
20f10 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 equivalent inte
20f20 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 rnal routines.
20f30 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 The atoi() and a
20f40 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a tof() names are.
20f50 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 ** used in the t
20f60 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 able for brevity
20f70 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 and because the
20f80 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 y are familiar t
20f90 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 o most.** C prog
20fa0 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e rammers..**.** N
20fb0 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 ote that when ty
20fc0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f pe conversions o
20fd0 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 ccur, pointers r
20fe0 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 eturned by prior
20ff0 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c .** calls to sql
21000 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 ite3_column_blob
21010 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 (), sqlite3_colu
21020 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f mn_text(), and/o
21030 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c r.** sqlite3_col
21040 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 umn_text16() may
21050 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e be invalidated.
21060 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 .** Type convers
21070 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 ions and pointer
21080 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d invalidations m
21090 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e ight occur.** in
210a0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 the following c
210b0 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e ases:.**.** <ul>
210c0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 .** <li> The ini
210d0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 tial content is
210e0 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 a BLOB and sqlit
210f0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
21100 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 or.** sqli
21110 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
21120 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 6() is called.
21130 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f A zero-terminato
21140 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 r might.**
21150 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 need to be added
21160 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c to the string.<
21170 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 /li>.** <li> The
21180 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 initial content
21190 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 is UTF-8 text a
211a0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nd sqlite3_colum
211b0 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a n_bytes16() or.*
211c0 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 * sqlite3_c
211d0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 olumn_text16() i
211e0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 s called. The c
211f0 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 ontent must be c
21200 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 onverted.**
21210 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e to UTF-16.</li>
21220 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 .** <li> The ini
21230 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 tial content is
21240 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 UTF-16 text and
21250 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
21260 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 ytes() or.**
21270 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e sqlite3_column
21280 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 _text() is calle
21290 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 d. The content
212a0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 must be converte
212b0 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 d.** to UTF
212c0 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c -8.</li>.** </ul
212d0 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 >.**.** Conversi
212e0 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d ons between UTF-
212f0 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 16be and UTF-16l
21300 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e e are always don
21310 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 e in place and d
21320 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 o.** not invalid
21330 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e ate a prior poin
21340 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 ter, though of c
21350 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e ourse the conten
21360 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a t of the buffer.
21370 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f ** that the prio
21380 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 r pointer points
21390 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65 to will have be
213a0 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 en modified. Ot
213b0 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 her kinds.** of
213c0 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 conversion are d
213d0 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 one in place whe
213e0 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 n it is possible
213f0 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 , but sometimes
21400 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 they.** are not
21410 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 possible and in
21420 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f those cases prio
21430 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 r pointers are i
21440 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a nvalidated..**.*
21450 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 * The safest and
21460 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 easiest to reme
21470 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 mber policy is t
21480 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 o invoke these r
21490 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e outines.** in on
214a0 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 e of the followi
214b0 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c ng ways:.**.** <
214c0 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 ul>.** <li>sqli
214d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
214e0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 ) followed by sq
214f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
21500 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c es()</li>.** <l
21510 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e i>sqlite3_column
21520 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 _blob() followed
21530 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by sqlite3_colu
21540 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a mn_bytes()</li>.
21550 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f ** <li>sqlite3_
21560 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 column_text16()
21570 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 followed by sqli
21580 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
21590 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 16()</li>.** </u
215a0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 l>.**.** In othe
215b0 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f r words, you sho
215c0 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 uld call sqlite3
215d0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a _column_text(),.
215e0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d ** sqlite3_colum
215f0 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c n_blob(), or sql
21600 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
21610 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 16() first to fo
21620 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a rce the result.*
21630 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 * into the desir
21640 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 ed format, then
21650 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 invoke sqlite3_c
21660 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 olumn_bytes() or
21670 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 .** sqlite3_colu
21680 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 mn_bytes16() to
21690 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 find the size of
216a0 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f the result. Do
216b0 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a not mix calls.*
216c0 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c * to sqlite3_col
216d0 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 umn_text() or sq
216e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
216f0 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 b() with calls t
21700 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c o.** sqlite3_col
21710 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 umn_bytes16(), a
21720 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 nd do not mix ca
21730 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 lls to sqlite3_c
21740 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a olumn_text16().*
21750 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 * with calls to
21760 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
21770 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 ytes()..**.** Th
21780 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 e pointers retur
21790 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e ned are valid un
217a0 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 til a type conve
217b0 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a rsion occurs as.
217c0 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f ** described abo
217d0 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 ve, or until [sq
217e0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 lite3_step()] or
217f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
21800 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 )] or.** [sqlite
21810 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 3_finalize()] is
21820 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65 called. The me
21830 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 mory space used
21840 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a to hold strings.
21850 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 ** and BLOBs is
21860 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 freed automatica
21870 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c lly. Do <b>not<
21880 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 /b> pass the poi
21890 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a nters returned.*
218a0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
218b0 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 n_blob()], [sqli
218c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
218d0 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a )], etc. into.**
218e0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
218f0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 ]..**.** If a me
21900 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
21910 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 error occurs dur
21920 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 ing the evaluati
21930 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 on of any.** of
21940 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 these routines,
21950 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 a default value
21960 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 is returned. Th
21970 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a e default value.
21980 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 ** is either the
21990 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 integer 0, the
219a0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e floating point n
219b0 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 umber 0.0, or a
219c0 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e NULL.** pointer.
219d0 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c Subsequent cal
219e0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 ls to [sqlite3_e
219f0 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 rrcode()] will r
21a00 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 eturn.** [SQLITE
21a10 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 52 _NOMEM]..**.** R
21a20 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
21a30 5b 48 31 33 38 30 33 5d 20 5b 48 31 33 38 30 36 [H13803] [H13806
21a40 5d 20 5b 48 31 33 38 30 39 5d 20 5b 48 31 33 38 ] [H13809] [H138
21a50 31 32 5d 20 5b 48 31 33 38 31 35 5d 20 5b 48 31 12] [H13815] [H1
21a60 33 38 31 38 5d 20 5b 48 31 33 38 32 31 5d 20 5b 3818] [H13821] [
21a70 48 31 33 38 32 34 5d 0a 2a 2a 20 5b 48 31 33 38 H13824].** [H138
21a80 32 37 5d 20 5b 48 31 33 38 33 30 5d 0a 2a 2f 0a 27] [H13830].*/.
21a90 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
21aa0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
21ab0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
21ac0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 nt iCol);.int sq
21ad0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
21ae0 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a es(sqlite3_stmt*
21af0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 , int iCol);.int
21b00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
21b10 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f bytes16(sqlite3_
21b20 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
21b30 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 ;.double sqlite3
21b40 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 _column_double(s
21b50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
21b60 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c t iCol);.int sql
21b70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 ite3_column_int(
21b80 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
21b90 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 nt iCol);.sqlite
21ba0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 3_int64 sqlite3_
21bb0 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c column_int64(sql
21bc0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
21bd0 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 iCol);.const uns
21be0 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 igned char *sqli
21bf0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
21c00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
21c10 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 nt iCol);.const
21c20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
21c30 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 lumn_text16(sqli
21c40 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
21c50 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 Col);.int sqlite
21c60 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 3_column_type(sq
21c70 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
21c80 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f iCol);.sqlite3_
21c90 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 value *sqlite3_c
21ca0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 olumn_value(sqli
21cb0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
21cc0 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 Col);../*.** CAP
21cd0 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 I3REF: Destroy A
21ce0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d Prepared Statem
21cf0 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 ent Object {H133
21d00 30 30 7d 20 3c 53 37 30 33 30 30 3e 3c 53 33 30 00} <S70300><S30
21d10 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 100>.**.** The s
21d20 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
21d30 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 ) function is ca
21d40 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 lled to delete a
21d50 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
21d60 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 ment]..** If the
21d70 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 65 statement was e
21d80 78 65 63 75 74 65 64 20 73 75 63 63 65 73 73 66 xecuted successf
21d90 75 6c 6c 79 20 6f 72 20 6e 6f 74 20 65 78 65 63 ully or not exec
21da0 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 uted at all, the
21db0 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 69 n.** SQLITE_OK i
21dc0 73 20 72 65 74 75 72 6e 65 64 2e 20 49 66 20 65 s returned. If e
21dd0 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 xecution of the
21de0 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 statement failed
21df0 20 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72 then an.** [err
21e00 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 or code] or [ext
21e10 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 ended error code
21e20 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a ] is returned..*
21e30 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
21e40 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 e can be called
21e50 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 at any point dur
21e60 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f ing the executio
21e70 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 n of the.** [pre
21e80 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
21e90 2e 20 20 49 66 20 74 68 65 20 76 69 72 74 75 61 . If the virtua
21ea0 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e 6f l machine has no
21eb0 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 t.** completed e
21ec0 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20 74 68 xecution when th
21ed0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 is routine is ca
21ee0 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20 6c 69 lled, that is li
21ef0 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69 ke.** encounteri
21f00 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 ng an error or a
21f10 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 n [sqlite3_inter
21f20 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 rupt | interrupt
21f30 5d 2e 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 ]..** Incomplete
21f40 20 75 70 64 61 74 65 73 20 6d 61 79 20 62 65 20 updates may be
21f50 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 rolled back and
21f60 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e transactions can
21f70 63 65 6c 65 64 2c 0a 2a 2a 20 64 65 70 65 6e 64 celed,.** depend
21f80 69 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75 ing on the circu
21f90 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 mstances, and th
21fa0 65 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 e.** [error code
21fb0 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 ] returned will
21fc0 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 be [SQLITE_ABORT
21fd0 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 ]..**.** Require
21fe0 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 31 33 30 ments:.** [H1130
21ff0 32 5d 20 5b 48 31 31 33 30 34 5d 0a 2a 2f 0a 69 2] [H11304].*/.i
22000 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c nt sqlite3_final
22010 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ize(sqlite3_stmt
22020 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
22030 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 CAPI3REF: Reset
22040 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 A Prepared Stat
22050 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 ement Object {H1
22060 33 33 33 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 3330} <S70300>.*
22070 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
22080 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f _reset() functio
22090 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 n is called to r
220a0 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 eset a [prepared
220b0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f statement].** o
220c0 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 bject back to it
220d0 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c s initial state,
220e0 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d ready to be re-
220f0 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 executed..** Any
22100 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 SQL statement v
22110 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 ariables that ha
22120 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 d values bound t
22130 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 o them using.**
22140 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e the [sqlite3_bin
22150 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 d_blob | sqlite3
22160 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 _bind_*() API] r
22170 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 etain their valu
22180 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 es..** Use [sqli
22190 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e te3_clear_bindin
221a0 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 gs()] to reset t
221b0 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a he bindings..**.
221c0 2a 2a 20 7b 48 31 31 33 33 32 7d 20 54 68 65 20 ** {H11332} The
221d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 [sqlite3_reset(S
221e0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 )] interface res
221f0 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 ets the [prepare
22200 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a d statement] S.*
22210 2a 20 20 20 20 20 20 20 20 20 20 62 61 63 6b 20 * back
22220 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 to the beginning
22230 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e of its program.
22240 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 34 7d 20 .**.** {H11334}
22250 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 If the most rece
22260 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 nt call to [sqli
22270 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 te3_step(S)] for
22280 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
22290 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
222a0 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 ment] S returned
222b0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 [SQLITE_ROW] or
222c0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a [SQLITE_DONE],.
222d0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 ** or i
222e0 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 f [sqlite3_step(
222f0 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 S)] has never be
22300 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 fore been called
22310 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 on S,.**
22320 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 then [sqlite3
22330 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 _reset(S)] retur
22340 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a ns [SQLITE_OK]..
22350 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 36 7d 20 49 **.** {H11336} I
22360 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e f the most recen
22370 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 t call to [sqlit
22380 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 e3_step(S)] for
22390 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
223a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
223b0 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 ent] S indicated
223c0 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a an error, then.
223d0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
223e0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 ite3_reset(S)] r
223f0 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 eturns an approp
22400 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 riate [error cod
22410 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 e]..**.** {H1133
22420 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 8} The [sqlite3_
22430 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 reset(S)] interf
22440 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 ace does not cha
22450 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a nge the values.*
22460 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 61 6e * of an
22470 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f y [sqlite3_bind_
22480 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f blob|bindings] o
22490 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 n the [prepared
224a0 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f statement] S..*/
224b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 .int sqlite3_res
224c0 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 et(sqlite3_stmt
224d0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *pStmt);../*.**
224e0 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 CAPI3REF: Create
224f0 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c Or Redefine SQL
22500 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 31 Functions {H161
22510 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 00} <S20200>.**
22520 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 KEYWORDS: {funct
22530 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 ion creation rou
22540 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 tines}.** KEYWOR
22550 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e DS: {application
22560 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
22570 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 ction}.** KEYWOR
22580 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e DS: {application
22590 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
225a0 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 ctions}.**.** Th
225b0 65 73 65 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e ese two function
225c0 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 s (collectively
225d0 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 known as "functi
225e0 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 on creation rout
225f0 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 ines").** are us
22600 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 ed to add SQL fu
22610 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 nctions or aggre
22620 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 gates or to rede
22630 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f fine the behavio
22640 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 r.** of existing
22650 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f SQL functions o
22660 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 r aggregates. T
22670 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e he only differen
22680 63 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a 2a ce between the.*
22690 2a 20 74 77 6f 20 69 73 20 74 68 61 74 20 74 68 * two is that th
226a0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
226b0 65 72 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 er, the name of
226c0 74 68 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e the (scalar) fun
226d0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 ction or.** aggr
226e0 65 67 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 egate, is encode
226f0 64 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 20 73 d in UTF-8 for s
22700 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
22710 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 nction() and UTF
22720 2d 31 36 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 -16.** for sqlit
22730 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
22740 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 on16()..**.** Th
22750 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
22760 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 r is the [databa
22770 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 se connection] t
22780 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a o which the SQL.
22790 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 ** function is t
227a0 6f 20 62 65 20 61 64 64 65 64 2e 20 20 49 66 20 o be added. If
227b0 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 61 6d a single program
227c0 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 uses more than
227d0 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 one database.**
227e0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 6e 74 65 72 connection inter
227f0 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c 20 nally, then SQL
22800 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 functions must b
22810 65 20 61 64 64 65 64 20 69 6e 64 69 76 69 64 75 e added individu
22820 61 6c 6c 79 20 74 6f 0a 2a 2a 20 65 61 63 68 20 ally to.** each
22830 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
22840 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ion..**.** The s
22850 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
22860 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 is the name of t
22870 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 he SQL function
22880 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 to be created or
22890 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 .** redefined.
228a0 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 The length of th
228b0 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 e name is limite
228c0 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20 d to 255 bytes,
228d0 65 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a 20 exclusive of.**
228e0 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 the zero-termina
228f0 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 tor. Note that
22900 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 the name length
22910 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65 limit is in byte
22920 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 s, not.** charac
22930 74 65 72 73 2e 20 20 41 6e 79 20 61 74 74 65 6d ters. Any attem
22940 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 pt to create a f
22950 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c unction with a l
22960 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 onger name.** wi
22970 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 ll result in [SQ
22980 4c 49 54 45 5f 45 52 52 4f 52 5d 20 62 65 69 6e LITE_ERROR] bein
22990 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a g returned..**.*
229a0 2a 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 * The third para
229b0 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 meter (nArg).**
229c0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 is the number of
229d0 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 arguments that
229e0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
229f0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 or.** aggregate
22a00 20 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20 takes. If this
22a10 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c parameter is -1,
22a20 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 then the SQL fu
22a30 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 nction or.** agg
22a40 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 regate may take
22a50 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 any number of ar
22a60 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 guments between
22a70 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 0 and the limit.
22a80 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 ** set by [sqlit
22a90 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 e3_limit]([SQLIT
22aa0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e E_LIMIT_FUNCTION
22ab0 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 _ARG]). If the
22ac0 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 third.** paramet
22ad0 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 er is less than
22ae0 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 -1 or greater th
22af0 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 an 127 then the
22b00 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 behavior is.** u
22b10 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
22b20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d The fourth param
22b30 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 eter, eTextRep,
22b40 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a specifies what.*
22b50 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c * [SQLITE_UTF8 |
22b60 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 text encoding]
22b70 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f this SQL functio
22b80 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a n prefers for.**
22b90 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e its parameters.
22ba0 20 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 Any SQL functi
22bb0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f on implementatio
22bc0 6e 20 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 n should be able
22bd0 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b to work.** work
22be0 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 with UTF-8, UTF
22bf0 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 -16le, or UTF-16
22c00 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d be. But some im
22c10 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 plementations ma
22c20 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 y be.** more eff
22c30 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 icient with one
22c40 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e encoding than an
22c50 6f 74 68 65 72 2e 20 20 49 74 20 69 73 20 61 6c other. It is al
22c60 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f lowed to.** invo
22c70 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 ke sqlite3_creat
22c80 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 e_function() or
22c90 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
22ca0 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 unction16() mult
22cb0 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 iple.** times wi
22cc0 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 th the same func
22cd0 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 tion but with di
22ce0 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f fferent values o
22cf0 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 57 f eTextRep..** W
22d00 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 hen multiple imp
22d10 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 lementations of
22d20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f the same functio
22d30 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c n are available,
22d40 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 SQLite.** will
22d50 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 pick the one tha
22d60 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c t involves the l
22d70 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 east amount of d
22d80 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a ata conversion..
22d90 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6f ** If there is o
22da0 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 nly a single imp
22db0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 lementation whic
22dc0 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 h does not care
22dd0 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 what text.** enc
22de0 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 oding is used, t
22df0 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 hen the fourth a
22e00 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 rgument should b
22e10 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a e [SQLITE_ANY]..
22e20 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 **.** The fifth
22e30 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 parameter is an
22e40 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 arbitrary pointe
22e50 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e r. The implemen
22e60 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a tation of the.**
22e70 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 function can ga
22e80 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 in access to thi
22e90 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 s pointer using
22ea0 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 [sqlite3_user_da
22eb0 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ta()]..**.** The
22ec0 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68 seventh, eighth
22ed0 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d and ninth param
22ee0 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 eters, xFunc, xS
22ef0 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 tep and xFinal,
22f00 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 are.** pointers
22f10 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 to C-language fu
22f20 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 nctions that imp
22f30 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 lement the SQL f
22f40 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 unction or.** ag
22f50 67 72 65 67 61 74 65 2e 20 41 20 73 63 61 6c 61 gregate. A scala
22f60 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 r SQL function r
22f70 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 equires an imple
22f80 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 mentation of the
22f90 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 xFunc.** callba
22fa0 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f ck only, NULL po
22fb0 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 inters should be
22fc0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78 passed as the x
22fd0 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a Step and xFinal.
22fe0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 41 ** parameters. A
22ff0 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 n aggregate SQL
23000 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 function require
23010 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 s an implementat
23020 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 ion of xStep.**
23030 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e and xFinal and N
23040 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61 ULL should be pa
23050 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 ssed for xFunc.
23060 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 To delete an exi
23070 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e sting.** SQL fun
23080 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 ction or aggrega
23090 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f te, pass NULL fo
230a0 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 r all three func
230b0 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e 0a tion callbacks..
230c0 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65 72 6d **.** It is perm
230d0 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 itted to registe
230e0 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 r multiple imple
230f0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 mentations of th
23100 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 e same.** functi
23110 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d ons with the sam
23120 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 e name but with
23130 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 either differing
23140 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 numbers of.** a
23150 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 rguments or diff
23160 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 ering preferred
23170 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 text encodings.
23180 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 SQLite will use
23190 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e .** the implemen
231a0 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 tation most clos
231b0 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 ely matches the
231c0 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 way in which the
231d0 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e .** SQL function
231e0 20 69 73 20 75 73 65 64 2e 20 20 41 20 66 75 6e is used. A fun
231f0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 ction implementa
23200 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d tion with a non-
23210 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 negative.** nArg
23220 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 parameter is a
23230 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 better match tha
23240 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 n a function imp
23250 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 lementation with
23260 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e .** a negative n
23270 41 72 67 2e 20 20 41 20 66 75 6e 63 74 69 6f 6e Arg. A function
23280 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65 where the prefe
23290 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 rred text encodi
232a0 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 ng.** matches th
232b0 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 e database encod
232c0 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a ing is a better.
232d0 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 ** match than a
232e0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 function where t
232f0 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 he encoding is d
23300 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 41 ifferent. .** A
23310 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 function where
23320 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 the encoding dif
23330 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 ference is betwe
23340 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 en UTF16le and U
23350 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 TF16be.** is a c
23360 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e loser match than
23370 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 a function wher
23380 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 e the encoding d
23390 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 ifference is.**
233a0 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 between UTF8 and
233b0 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 42 75 UTF16..**.** Bu
233c0 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 ilt-in functions
233d0 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 may be overload
233e0 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 ed by new applic
233f0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
23400 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 nctions..** The
23410 66 69 72 73 74 20 61 70 70 6c 69 63 61 74 69 6f first applicatio
23420 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
23430 6f 6e 20 77 69 74 68 20 61 20 67 69 76 65 6e 20 on with a given
23440 6e 61 6d 65 20 6f 76 65 72 72 69 64 65 73 20 61 name overrides a
23450 6c 6c 0a 2a 2a 20 62 75 69 6c 74 2d 69 6e 20 66 ll.** built-in f
23460 75 6e 63 74 69 6f 6e 73 20 69 6e 20 74 68 65 20 unctions in the
23470 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 same [database c
23480 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 69 74 68 20 onnection] with
23490 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a the same name..*
234a0 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 70 70 * Subsequent app
234b0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
234c0 20 66 75 6e 63 74 69 6f 6e 73 20 6f 66 20 74 68 functions of th
234d0 65 20 73 61 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79 e same name only
234e0 20 6f 76 65 72 72 69 64 65 20 0a 2a 2a 20 70 72 override .** pr
234f0 69 6f 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d ior application-
23500 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
23510 73 20 74 68 61 74 20 61 72 65 20 61 6e 20 65 78 s that are an ex
23520 61 63 74 20 6d 61 74 63 68 20 66 6f 72 20 74 68 act match for th
23530 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 70 e.** number of p
23540 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 70 72 arameters and pr
23550 65 66 65 72 72 65 64 20 65 6e 63 6f 64 69 6e 67 eferred encoding
23560 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 70 70 6c 69 ..**.** An appli
23570 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
23580 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 unction is permi
23590 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 tted to call oth
235a0 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 er.** SQLite int
235b0 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 erfaces. Howeve
235c0 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 r, such calls mu
235d0 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 st not.** close
235e0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
235f0 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 nection nor fina
23600 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 lize or reset th
23610 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 e prepared.** st
23620 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 atement in which
23630 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 the function is
23640 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 running..**.**
23650 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
23660 20 5b 48 31 36 31 30 33 5d 20 5b 48 31 36 31 30 [H16103] [H1610
23670 36 5d 20 5b 48 31 36 31 30 39 5d 20 5b 48 31 36 6] [H16109] [H16
23680 31 31 32 5d 20 5b 48 31 36 31 31 38 5d 20 5b 48 112] [H16118] [H
23690 31 36 31 32 31 5d 20 5b 48 31 36 31 32 37 5d 0a 16121] [H16127].
236a0 2a 2a 20 5b 48 31 36 31 33 30 5d 20 5b 48 31 36 ** [H16130] [H16
236b0 31 33 33 5d 20 5b 48 31 36 31 33 36 5d 20 5b 48 133] [H16136] [H
236c0 31 36 31 33 39 5d 20 5b 48 31 36 31 34 32 5d 0a 16139] [H16142].
236d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 */.int sqlite3_c
236e0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a reate_function(.
236f0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 sqlite3 *db,.
23700 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 const char *zFu
23710 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e nctionName,. in
23720 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 t nArg,. int eT
23730 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a extRep,. void *
23740 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 pApp,. void (*x
23750 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f Func)(sqlite3_co
23760 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 ntext*,int,sqlit
23770 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 e3_value**),. v
23780 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c oid (*xStep)(sql
23790 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e ite3_context*,in
237a0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t,sqlite3_value*
237b0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 *),. void (*xFi
237c0 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e nal)(sqlite3_con
237d0 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 text*).);.int sq
237e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
237f0 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 ction16(. sqlit
23800 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 e3 *db,. const
23810 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e void *zFunctionN
23820 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c ame,. int nArg,
23830 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c . int eTextRep,
23840 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 . void *pApp,.
23850 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 void (*xFunc)(s
23860 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
23870 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 int,sqlite3_valu
23880 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 e**),. void (*x
23890 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f Step)(sqlite3_co
238a0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 ntext*,int,sqlit
238b0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 e3_value**),. v
238c0 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 oid (*xFinal)(sq
238d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a lite3_context*).
238e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
238f0 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e EF: Text Encodin
23900 67 73 20 7b 48 31 30 32 36 37 7d 20 3c 53 35 30 gs {H10267} <S50
23910 32 30 30 3e 20 3c 48 31 36 31 30 30 3e 0a 2a 2a 200> <H16100>.**
23920 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 .** These consta
23930 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 nt define intege
23940 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 r codes that rep
23950 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f resent the vario
23960 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 us.** text encod
23970 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 ings supported b
23980 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 y SQLite..*/.#de
23990 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 fine SQLITE_UTF8
239a0 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 1.#de
239b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 fine SQLITE_UTF1
239c0 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 6LE 2.#de
239d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 fine SQLITE_UTF1
239e0 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 6BE 3.#de
239f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 fine SQLITE_UTF1
23a00 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 6 4
23a10 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 /* Use native by
23a20 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 te order */.#def
23a30 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 ine SQLITE_ANY
23a40 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 5 /
23a50 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 * sqlite3_create
23a60 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a _function only *
23a70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
23a80 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 _UTF16_ALIGNED
23a90 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 8 /* sqlite3_
23aa0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
23ab0 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 only */../*.**
23ac0 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 CAPI3REF: Deprec
23ad0 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a ated Functions.*
23ae0 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a * DEPRECATED.**.
23af0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f ** These functio
23b00 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 ns are [deprecat
23b10 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 ed]. In order t
23b20 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 o maintain.** ba
23b30 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 ckwards compatib
23b40 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 ility with older
23b50 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e code, these fun
23b60 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 ctions continue
23b70 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 .** to be suppor
23b80 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e ted. However, n
23b90 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 ew applications
23ba0 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 should avoid.**
23bb0 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 the use of these
23bc0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 functions. To
23bd0 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 help encourage p
23be0 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a eople to avoid.*
23bf0 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 * using these fu
23c00 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 nctions, we are
23c10 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c not going to tel
23c20 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 l you what they
23c30 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 do..*/.#ifndef S
23c40 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 QLITE_OMIT_DEPRE
23c50 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 CATED.SQLITE_DEP
23c60 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 RECATED int sqli
23c70 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
23c80 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 unt(sqlite3_cont
23c90 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 ext*);.SQLITE_DE
23ca0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c PRECATED int sql
23cb0 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c ite3_expired(sql
23cc0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c ite3_stmt*);.SQL
23cd0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 ITE_DEPRECATED i
23ce0 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 nt sqlite3_trans
23cf0 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c fer_bindings(sql
23d00 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 ite3_stmt*, sqli
23d10 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 te3_stmt*);.SQLI
23d20 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e TE_DEPRECATED in
23d30 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c t sqlite3_global
23d40 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a _recover(void);.
23d50 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 SQLITE_DEPRECATE
23d60 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 D void sqlite3_t
23d70 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f hread_cleanup(vo
23d80 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 id);.SQLITE_DEPR
23d90 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 ECATED int sqlit
23da0 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 e3_memory_alarm(
23db0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 void(*)(void*,sq
23dc0 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 lite3_int64,int)
23dd0 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 ,void*,sqlite3_i
23de0 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f nt64);.#endif../
23df0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
23e00 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e btaining SQL Fun
23e10 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 ction Parameter
23e20 56 61 6c 75 65 73 20 7b 48 31 35 31 30 30 7d 20 Values {H15100}
23e30 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S20200>.**.** T
23e40 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d he C-language im
23e50 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
23e60 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e SQL functions an
23e70 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 d aggregates use
23e80 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 s.** this set of
23e90 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 interface routi
23ea0 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 nes to access th
23eb0 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 e parameter valu
23ec0 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e es on.** the fun
23ed0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 ction or aggrega
23ee0 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 te..**.** The xF
23ef0 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 unc (for scalar
23f00 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 functions) or xS
23f10 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 tep (for aggrega
23f20 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a tes) parameters.
23f30 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ** to [sqlite3_c
23f40 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
23f50 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 ] and [sqlite3_c
23f60 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
23f70 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 ()].** define ca
23f80 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 llbacks that imp
23f90 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 lement the SQL f
23fa0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 unctions and agg
23fb0 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 regates..** The
23fc0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 4th parameter to
23fd0 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 these callbacks
23fe0 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 is an array of
23ff0 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b pointers to.** [
24000 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
24010 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 3_value] objects
24020 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 . There is one
24030 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 [sqlite3_value]
24040 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 object for.** ea
24050 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 ch parameter to
24060 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
24070 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 . These routine
24080 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a s are used to.**
24090 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 extract values
240a0 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 from the [sqlite
240b0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 3_value] objects
240c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f ..**.** These ro
240d0 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 utines work only
240e0 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 with [protected
240f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
24100 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 objects..** Any
24110 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 attempt to use t
24120 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e hese routines on
24130 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 an [unprotected
24140 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a sqlite3_value].
24150 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 ** object result
24160 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 s in undefined b
24170 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 ehavior..**.** T
24180 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f hese routines wo
24190 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 rk just like the
241a0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b corresponding [
241b0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 column access fu
241c0 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 nctions].** exce
241d0 70 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72 pt that these r
241e0 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 outines take a s
241f0 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 ingle [protected
24200 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
24210 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 object.** pointe
24220 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b r instead of a [
24230 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 sqlite3_stmt*] p
24240 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e ointer and an in
24250 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d teger column num
24260 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ber..**.** The s
24270 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
24280 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 t16() interface
24290 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 extracts a UTF-1
242a0 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 6 string.** in t
242b0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f he native byte-o
242c0 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 rder of the host
242d0 20 6d 61 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a machine. The.*
242e0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f * sqlite3_value_
242f0 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 text16be() and s
24300 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
24310 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 t16le() interfac
24320 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 es.** extract UT
24330 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 F-16 strings as
24340 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c big-endian and l
24350 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 ittle-endian res
24360 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a pectively..**.**
24370 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c The sqlite3_val
24380 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 ue_numeric_type(
24390 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 ) interface atte
243a0 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a mpts to apply.**
243b0 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 numeric affinit
243c0 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 y to the value.
243d0 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 This means that
243e0 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a an attempt is.*
243f0 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 * made to conver
24400 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 t the value to a
24410 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f n integer or flo
24420 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 ating point. If
24430 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 .** such a conve
24440 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c rsion is possibl
24450 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f e without loss o
24460 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 f information (i
24470 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 n other.** words
24480 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 , if the value i
24490 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 s a string that
244a0 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d looks like a num
244b0 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ber).** then the
244c0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 conversion is p
244d0 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 erformed. Other
244e0 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 wise no conversi
244f0 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 on occurs..** Th
24500 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 e [SQLITE_INTEGE
24510 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 R | datatype] af
24520 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 ter conversion i
24530 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
24540 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 * Please pay par
24550 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f ticular attentio
24560 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 n to the fact th
24570 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 at the pointer r
24580 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 eturned.** from
24590 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 [sqlite3_value_b
245a0 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 lob()], [sqlite3
245b0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 _value_text()],
245c0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 or.** [sqlite3_v
245d0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 alue_text16()] c
245e0 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 an be invalidate
245f0 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e d by a subsequen
24600 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 t call to.** [sq
24610 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 lite3_value_byte
24620 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 s()], [sqlite3_v
24630 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c alue_bytes16()],
24640 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
24650 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b text()],.** or [
24660 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
24670 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 xt16()]..**.** T
24680 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 hese routines mu
24690 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f st be called fro
246a0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 m the same threa
246b0 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 d as.** the SQL
246c0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 function that su
246d0 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 pplied the [sqli
246e0 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 te3_value*] para
246f0 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 meters..**.** Re
24700 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
24710 48 31 35 31 30 33 5d 20 5b 48 31 35 31 30 36 5d H15103] [H15106]
24720 20 5b 48 31 35 31 30 39 5d 20 5b 48 31 35 31 31 [H15109] [H1511
24730 32 5d 20 5b 48 31 35 31 31 35 5d 20 5b 48 31 35 2] [H15115] [H15
24740 31 31 38 5d 20 5b 48 31 35 31 32 31 5d 20 5b 48 118] [H15121] [H
24750 31 35 31 32 34 5d 0a 2a 2a 20 5b 48 31 35 31 32 15124].** [H1512
24760 37 5d 20 5b 48 31 35 31 33 30 5d 20 5b 48 31 35 7] [H15130] [H15
24770 31 33 33 5d 20 5b 48 31 35 31 33 36 5d 0a 2a 2f 133] [H15136].*/
24780 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
24790 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 ite3_value_blob(
247a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
247b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c .int sqlite3_val
247c0 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 ue_bytes(sqlite3
247d0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 _value*);.int sq
247e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 lite3_value_byte
247f0 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 s16(sqlite3_valu
24800 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 e*);.double sqli
24810 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 te3_value_double
24820 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
24830 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 ;.int sqlite3_va
24840 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f lue_int(sqlite3_
24850 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 value*);.sqlite3
24860 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 _int64 sqlite3_v
24870 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 alue_int64(sqlit
24880 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 e3_value*);.cons
24890 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 t unsigned char
248a0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 *sqlite3_value_t
248b0 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 ext(sqlite3_valu
248c0 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 e*);.const void
248d0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 *sqlite3_value_t
248e0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 ext16(sqlite3_va
248f0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 lue*);.const voi
24900 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 d *sqlite3_value
24910 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 _text16le(sqlite
24920 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 3_value*);.const
24930 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 void *sqlite3_v
24940 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 alue_text16be(sq
24950 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 lite3_value*);.i
24960 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt sqlite3_value
24970 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 _type(sqlite3_va
24980 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 lue*);.int sqlit
24990 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 e3_value_numeric
249a0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 _type(sqlite3_va
249b0 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 lue*);../*.** CA
249c0 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 PI3REF: Obtain A
249d0 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f ggregate Functio
249e0 6e 20 43 6f 6e 74 65 78 74 20 7b 48 31 36 32 31 n Context {H1621
249f0 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 0} <S20200>.**.*
24a00 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 * The implementa
24a10 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 67 61 74 tion of aggregat
24a20 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 e SQL functions
24a30 75 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 use this routine
24a40 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20 to allocate.**
24a50 61 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 a structure for
24a60 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 storing their st
24a70 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 ate..**.** The f
24a80 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 irst time the sq
24a90 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
24aa0 63 6f 6e 74 65 78 74 28 29 20 72 6f 75 74 69 6e context() routin
24ab0 65 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 e is called for
24ac0 61 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 a.** particular
24ad0 61 67 67 72 65 67 61 74 65 2c 20 53 51 4c 69 74 aggregate, SQLit
24ae0 65 20 61 6c 6c 6f 63 61 74 65 73 20 6e 42 79 74 e allocates nByt
24af0 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 es of memory, ze
24b00 72 6f 65 73 20 6f 75 74 20 74 68 61 74 0a 2a 2a roes out that.**
24b10 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 memory, and ret
24b20 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
24b30 6f 20 69 74 2e 20 4f 6e 20 73 65 63 6f 6e 64 20 o it. On second
24b40 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 and subsequent c
24b50 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 alls to.** sqlit
24b60 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
24b70 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 text() for the s
24b80 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 ame aggregate fu
24b90 6e 63 74 69 6f 6e 20 69 6e 64 65 78 2c 0a 2a 2a nction index,.**
24ba0 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 the same buffer
24bb0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 54 68 is returned. Th
24bc0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
24bd0 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 of the aggregat
24be0 65 20 63 61 6e 20 75 73 65 0a 2a 2a 20 74 68 65 e can use.** the
24bf0 20 72 65 74 75 72 6e 65 64 20 62 75 66 66 65 72 returned buffer
24c00 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 65 20 64 to accumulate d
24c10 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 ata..**.** SQLit
24c20 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 e automatically
24c30 66 72 65 65 73 20 74 68 65 20 61 6c 6c 6f 63 61 frees the alloca
24c40 74 65 64 20 62 75 66 66 65 72 20 77 68 65 6e 20 ted buffer when
24c50 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a the aggregate.**
24c60 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 query concludes
24c70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 ..**.** The firs
24c80 74 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 t parameter shou
24c90 6c 64 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 ld be a copy of
24ca0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
24cb0 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 context | SQL fu
24cc0 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 nction context]
24cd0 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73 that is the firs
24ce0 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 t parameter.** t
24cf0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 o the callback r
24d00 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c outine that impl
24d10 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 ements the aggre
24d20 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a gate function..*
24d30 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
24d40 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 e must be called
24d50 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 from the same t
24d60 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a hread in which.*
24d70 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 * the aggregate
24d80 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 SQL function is
24d90 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 running..**.** R
24da0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
24db0 5b 48 31 36 32 31 31 5d 20 5b 48 31 36 32 31 33 [H16211] [H16213
24dc0 5d 20 5b 48 31 36 32 31 35 5d 20 5b 48 31 36 32 ] [H16215] [H162
24dd0 31 37 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 17].*/.void *sql
24de0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
24df0 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 ontext(sqlite3_c
24e00 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 ontext*, int nBy
24e10 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tes);../*.** CAP
24e20 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 I3REF: User Data
24e30 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b For Functions {
24e40 48 31 36 32 34 30 7d 20 3c 53 32 30 32 30 30 3e H16240} <S20200>
24e50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
24e60 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 e3_user_data() i
24e70 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
24e80 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 a copy of.** th
24e90 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 e pointer that w
24ea0 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61 as the pUserData
24eb0 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 parameter (the
24ec0 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 5th parameter).*
24ed0 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 * of the [sqlite
24ee0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
24ef0 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c n()].** and [sql
24f00 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
24f10 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e tion16()] routin
24f20 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c es that original
24f30 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 ly.** registered
24f40 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
24f50 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f defined functio
24f60 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 n. {END}.**.** T
24f70 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 his routine must
24f80 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 be called from
24f90 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 the same thread
24fa0 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 in which.** the
24fb0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
24fc0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 ned function is
24fd0 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 running..**.** R
24fe0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
24ff0 5b 48 31 36 32 34 33 5d 0a 2a 2f 0a 76 6f 69 64 [H16243].*/.void
25000 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 *sqlite3_user_d
25010 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ata(sqlite3_cont
25020 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ext*);../*.** CA
25030 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 PI3REF: Database
25040 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 Connection For
25050 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32 35 Functions {H1625
25060 30 7d 20 3c 53 36 30 36 30 30 3e 3c 53 32 30 32 0} <S60600><S202
25070 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 00>.**.** The sq
25080 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 lite3_context_db
25090 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 _handle() interf
250a0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f ace returns a co
250b0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 py of.** the poi
250c0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 nter to the [dat
250d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
250e0 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d ] (the 1st param
250f0 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 eter).** of the
25100 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
25110 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 function()].** a
25120 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 nd [sqlite3_crea
25130 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d te_function16()]
25140 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f routines that o
25150 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 riginally.** reg
25160 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c istered the appl
25170 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 ication defined
25180 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 function..**.**
25190 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
251a0 20 5b 48 31 36 32 35 33 5d 0a 2a 2f 0a 73 71 6c [H16253].*/.sql
251b0 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f ite3 *sqlite3_co
251c0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 ntext_db_handle(
251d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
251e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
251f0 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 EF: Function Aux
25200 69 6c 69 61 72 79 20 44 61 74 61 20 7b 48 31 36 iliary Data {H16
25210 32 37 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 270} <S20200>.**
25220 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e .** The followin
25230 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 g two functions
25240 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73 may be used by s
25250 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 calar SQL functi
25260 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 ons to.** associ
25270 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 ate metadata wit
25280 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 h argument value
25290 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 s. If the same v
252a0 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 alue is passed t
252b0 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e o.** multiple in
252c0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 vocations of the
252d0 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 same SQL functi
252e0 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 on during query
252f0 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 execution, under
25300 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 .** some circums
25310 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 tances the assoc
25320 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d iated metadata m
25330 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e ay be preserved.
25340 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 This may.** be
25350 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c used, for exampl
25360 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 e, to add a regu
25370 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d lar-expression m
25380 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a atching scalar.*
25390 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 * function. The
253a0 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e compiled version
253b0 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 of the regular
253c0 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 expression is st
253d0 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 ored as.** metad
253e0 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 ata associated w
253f0 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 ith the SQL valu
25400 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 e passed as the
25410 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 regular expressi
25420 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 on.** pattern.
25430 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 The compiled reg
25440 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 ular expression
25450 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e can be reused on
25460 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 multiple.** inv
25470 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 ocations of the
25480 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f same function so
25490 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e that the origin
254a0 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e al pattern strin
254b0 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 g.** does not ne
254c0 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 ed to be recompi
254d0 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f led on each invo
254e0 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 cation..**.** Th
254f0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 e sqlite3_get_au
25500 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 xdata() interfac
25510 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e e returns a poin
25520 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 ter to the metad
25530 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 ata.** associate
25540 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 d by the sqlite3
25550 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 _set_auxdata() f
25560 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 unction with the
25570 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a Nth argument.**
25580 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 value to the ap
25590 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
255a0 64 20 66 75 6e 63 74 69 6f 6e 2e 20 49 66 20 6e d function. If n
255b0 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 o metadata has b
255c0 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e een ever.** been
255d0 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 set for the Nth
255e0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 argument of the
255f0 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 function, or if
25600 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 the correspondi
25610 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 ng.** function p
25620 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 arameter has cha
25630 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d nged since the m
25640 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 eta-data was set
25650 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 ,.** then sqlite
25660 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 3_get_auxdata()
25670 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 returns a NULL p
25680 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 ointer..**.** Th
25690 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 e sqlite3_set_au
256a0 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 xdata() interfac
256b0 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 e saves the meta
256c0 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 data.** pointed
256d0 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61 to by its 3rd pa
256e0 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d rameter as the m
256f0 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 etadata for the
25700 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 N-th.** argument
25710 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 of the applicat
25720 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
25730 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e tion. Subsequen
25740 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 t.** calls to sq
25750 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 lite3_get_auxdat
25760 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e a() might return
25770 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 this data, if i
25780 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 t has.** not bee
25790 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 n destroyed..**
257a0 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c If it is not NUL
257b0 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 L, SQLite will i
257c0 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 nvoke the destru
257d0 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e ctor.** function
257e0 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 given by the 4t
257f0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 h parameter to s
25800 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 qlite3_set_auxda
25810 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d ta() on.** the m
25820 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68 65 etadata when the
25830 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 corresponding f
25840 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 unction paramete
25850 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 r changes.** or
25860 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 when the SQL sta
25870 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 tement completes
25880 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 , whichever come
25890 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 s first..**.** S
258a0 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f QLite is free to
258b0 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 call the destru
258c0 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 ctor and drop me
258d0 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a tadata on any.**
258e0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e parameter of an
258f0 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e y function at an
25900 79 20 74 69 6d 65 2e 20 20 54 68 65 20 6f 6e 6c y time. The onl
25910 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 20 74 y guarantee is t
25920 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 hat.** the destr
25930 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 uctor will be ca
25940 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 lled before the
25950 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 6f 70 metadata is drop
25960 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 ped..**.** In pr
25970 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 actice, metadata
25980 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65 is preserved be
25990 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 tween function c
259a0 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 alls for.** expr
259b0 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 essions that are
259c0 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d constant at com
259d0 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 pile time. This
259e0 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c includes literal
259f0 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 53 .** values and S
25a00 51 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a QL variables..**
25a10 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
25a20 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 es must be calle
25a30 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 d from the same
25a40 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a thread in which.
25a50 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 ** the SQL funct
25a60 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a ion is running..
25a70 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
25a80 74 73 3a 0a 2a 2a 20 5b 48 31 36 32 37 32 5d 20 ts:.** [H16272]
25a90 5b 48 31 36 32 37 34 5d 20 5b 48 31 36 32 37 36 [H16274] [H16276
25aa0 5d 20 5b 48 31 36 32 37 37 5d 20 5b 48 31 36 32 ] [H16277] [H162
25ab0 37 38 5d 20 5b 48 31 36 32 37 39 5d 0a 2a 2f 0a 78] [H16279].*/.
25ac0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 void *sqlite3_ge
25ad0 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 t_auxdata(sqlite
25ae0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 3_context*, int
25af0 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 N);.void sqlite3
25b00 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c _set_auxdata(sql
25b10 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 ite3_context*, i
25b20 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 nt N, void*, voi
25b30 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a d (*)(void*));..
25b40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
25b50 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e Constants Defin
25b60 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 ing Special Dest
25b70 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 20 ructor Behavior
25b80 7b 48 31 30 32 38 30 7d 20 3c 53 33 30 31 30 30 {H10280} <S30100
25b90 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 >.**.** These ar
25ba0 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 e special values
25bb0 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 for the destruc
25bc0 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73 tor that is pass
25bd0 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 ed in as the.**
25be0 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 final argument t
25bf0 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 o routines like
25c00 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
25c10 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74 68 65 blob()]. If the
25c20 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 destructor.** a
25c30 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 rgument is SQLIT
25c40 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 E_STATIC, it mea
25c50 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 ns that the cont
25c60 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 ent pointer is c
25c70 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 onstant.** and w
25c80 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 ill never change
25c90 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e . It does not n
25ca0 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f eed to be destro
25cb0 79 65 64 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c yed. The.** SQL
25cc0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 ITE_TRANSIENT va
25cd0 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 lue means that t
25ce0 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 he content will
25cf0 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e likely change in
25d00 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 .** the near fut
25d10 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c ure and that SQL
25d20 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 ite should make
25d30 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 its own private
25d40 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 copy of.** the c
25d50 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 ontent before re
25d60 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 turning..**.** T
25d70 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 he typedef is ne
25d80 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 cessary to work
25d90 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 around problems
25da0 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b in certain.** C+
25db0 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 + compilers. Se
25dc0 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a e ticket #2191..
25dd0 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 */.typedef void
25de0 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 (*sqlite3_destru
25df0 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a ctor_type)(void*
25e00 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 );.#define SQLIT
25e10 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 E_STATIC ((
25e20 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 sqlite3_destruct
25e30 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 or_type)0).#defi
25e40 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 ne SQLITE_TRANSI
25e50 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f ENT ((sqlite3_
25e60 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 destructor_type)
25e70 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 -1)../*.** CAPI3
25e80 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 REF: Setting The
25e90 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 Result Of An SQ
25ea0 4c 20 46 75 6e 63 74 69 6f 6e 20 7b 48 31 36 34 L Function {H164
25eb0 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 00} <S20200>.**.
25ec0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
25ed0 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68 s are used by th
25ee0 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 e xFunc or xFina
25ef0 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 l callbacks that
25f00 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 .** implement SQ
25f10 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 L functions and
25f20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 aggregates. See
25f30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 .** [sqlite3_cre
25f40 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 ate_function()]
25f50 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 and [sqlite3_cre
25f60 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 ate_function16()
25f70 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f ].** for additio
25f80 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e nal information.
25f90 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e .**.** These fun
25fa0 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 ctions work very
25fb0 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b much like the [
25fc0 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e parameter bindin
25fd0 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 g] family of.**
25fe0 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 functions used t
25ff0 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f o bind values to
26000 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 host parameters
26010 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 in prepared sta
26020 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 tements..** Refe
26030 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 r to the [SQL pa
26040 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e rameter] documen
26050 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 tation for addit
26060 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f ional informatio
26070 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c n..**.** The sql
26080 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 ite3_result_blob
26090 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 () interface set
260a0 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f s the result fro
260b0 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 m.** an applicat
260c0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
260d0 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 tion to be the B
260e0 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e LOB whose conten
260f0 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 t is pointed.**
26100 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 to by the second
26110 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 parameter and w
26120 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 hich is N bytes
26130 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 long where N is
26140 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 the.** third par
26150 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 ameter..**.** Th
26160 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
26170 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 _zeroblob() inte
26180 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72 rfaces set the r
26190 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 esult of.** the
261a0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
261b0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 ned function to
261c0 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 be a BLOB contai
261d0 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a ning all zero.**
261e0 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 bytes and N byt
261f0 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 es in size, wher
26200 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 e N is the value
26210 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 of the 2nd para
26220 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 meter..**.** The
26230 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
26240 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 double() interfa
26250 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 ce sets the resu
26260 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 lt from.** an ap
26270 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
26280 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 d function to be
26290 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e a floating poin
262a0 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 t value specifie
262b0 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 d.** by its 2nd
262c0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 argument..**.**
262d0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
262e0 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 lt_error() and s
262f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
26300 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e ror16() function
26310 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 s.** cause the i
26320 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 mplemented SQL f
26330 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 unction to throw
26340 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a an exception..*
26350 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 * SQLite uses th
26360 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 e string pointed
26370 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e to by the.** 2n
26380 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 d parameter of s
26390 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
263a0 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 ror() or sqlite3
263b0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
263c0 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 ).** as the text
263d0 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 of an error mes
263e0 73 61 67 65 2e 20 20 53 51 4c 69 74 65 20 69 6e sage. SQLite in
263f0 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72 terprets the err
26400 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 or.** message st
26410 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 ring from sqlite
26420 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 3_result_error()
26430 20 61 73 20 55 54 46 2d 38 2e 20 53 51 4c 69 74 as UTF-8. SQLit
26440 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 e.** interprets
26450 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 the string from
26460 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
26470 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d rror16() as UTF-
26480 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 16 in native.**
26490 62 79 74 65 20 6f 72 64 65 72 2e 20 20 49 66 20 byte order. If
264a0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
264b0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 ter to sqlite3_r
264c0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a esult_error().**
264d0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 or sqlite3_resu
264e0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 lt_error16() is
264f0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 negative then SQ
26500 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 Lite takes as th
26510 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 e error.** messa
26520 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 ge all text up t
26530 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 hrough the first
26540 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e zero character.
26550 0a 2a 2a 20 49 66 20 74 68 65 20 74 68 69 72 64 .** If the third
26560 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
26570 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
26580 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 or() or.** sqlit
26590 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 e3_result_error1
265a0 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 6() is non-negat
265b0 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 ive then SQLite
265c0 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a takes that many.
265d0 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 ** bytes (not ch
265e0 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 aracters) from t
265f0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 he 2nd parameter
26600 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 as the error me
26610 73 73 61 67 65 2e 0a 2a 2a 20 54 68 65 20 73 71 ssage..** The sq
26620 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
26630 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 or() and sqlite3
26640 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
26650 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 ).** routines ma
26660 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 ke a private cop
26670 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d y of the error m
26680 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f essage text befo
26690 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 re.** they retur
266a0 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 n. Hence, the c
266b0 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 alling function
266c0 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f can deallocate o
266d0 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 r.** modify the
266e0 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 text after they
266f0 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 return without h
26700 61 72 6d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 arm..** The sqli
26710 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
26720 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e _code() function
26730 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 changes the err
26740 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 or code.** retur
26750 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 ned by SQLite as
26760 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 a result of an
26770 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 error in a funct
26780 69 6f 6e 2e 20 20 42 79 20 64 65 66 61 75 6c 74 ion. By default
26790 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 ,.** the error c
267a0 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 ode is SQLITE_ER
267b0 52 4f 52 2e 20 20 41 20 73 75 62 73 65 71 75 65 ROR. A subseque
267c0 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 nt call to sqlit
267d0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
267e0 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f ).** or sqlite3_
267f0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 result_error16()
26800 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f resets the erro
26810 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 r code to SQLITE
26820 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 _ERROR..**.** Th
26830 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
26840 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 _toobig() interf
26850 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 ace causes SQLit
26860 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 e to throw an er
26870 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e ror.** indicatin
26880 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 g that a string
26890 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f or BLOB is to lo
268a0 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e ng to represent.
268b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
268c0 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 e3_result_nomem(
268d0 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 ) interface caus
268e0 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 es SQLite to thr
268f0 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 ow an error.** i
26900 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 ndicating that a
26910 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
26920 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a on failed..**.**
26930 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 The sqlite3_res
26940 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 ult_int() interf
26950 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 ace sets the ret
26960 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 urn value.** of
26970 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
26980 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
26990 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 to be the 32-bi
269a0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 t signed integer
269b0 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 .** value given
269c0 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d in the 2nd argum
269d0 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ent..** The sqli
269e0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 te3_result_int64
269f0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 () interface set
26a00 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c s the return val
26a10 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 ue.** of the app
26a20 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
26a30 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
26a40 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 the 64-bit signe
26a50 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c d integer.** val
26a60 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 ue given in the
26a70 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 2nd argument..**
26a80 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
26a90 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e result_null() in
26aa0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 terface sets the
26ab0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a return value.**
26ac0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 of the applicat
26ad0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
26ae0 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e tion to be NULL.
26af0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
26b00 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 e3_result_text()
26b10 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 , sqlite3_result
26b20 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 _text16(),.** sq
26b30 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
26b40 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c t16le(), and sql
26b50 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
26b60 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 16be() interface
26b70 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 s.** set the ret
26b80 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 urn value of the
26b90 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
26ba0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f ined function to
26bb0 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 be.** a text st
26bc0 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 ring which is re
26bd0 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 presented as UTF
26be0 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 -8, UTF-16 nativ
26bf0 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a e byte order,.**
26c00 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 UTF-16 little e
26c10 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 ndian, or UTF-16
26c20 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 big endian, res
26c30 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 53 51 pectively..** SQ
26c40 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 Lite takes the t
26c50 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 ext result from
26c60 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
26c70 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 from.** the 2nd
26c80 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 parameter of the
26c90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
26ca0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 text* interfaces
26cb0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 ..** If the 3rd
26cc0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
26cd0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
26ce0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 text* interfaces
26cf0 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c .** is negative,
26d00 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b then SQLite tak
26d10 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 es result text f
26d20 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 rom the 2nd para
26d30 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 meter.** through
26d40 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 the first zero
26d50 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 character..** If
26d60 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 the 3rd paramet
26d70 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 er to the sqlite
26d80 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 3_result_text* i
26d90 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 nterfaces.** is
26da0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 non-negative, th
26db0 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 en as many bytes
26dc0 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 (not characters
26dd0 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a ) of the text.**
26de0 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 pointed to by t
26df0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 he 2nd parameter
26e00 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 are taken as th
26e10 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
26e20 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f fined.** functio
26e30 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 n result..** If
26e40 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 the 4th paramete
26e50 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 r to the sqlite3
26e60 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e _result_text* in
26e70 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 terfaces.** or s
26e80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
26e90 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c ob is a non-NULL
26ea0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 pointer, then S
26eb0 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 QLite calls that
26ec0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 .** function as
26ed0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f the destructor o
26ee0 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c n the text or BL
26ef0 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 OB result when i
26f00 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 t has.** finishe
26f10 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 d using that res
26f20 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 ult..** If the 4
26f30 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
26f40 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 the sqlite3_resu
26f50 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 lt_text* interfa
26f60 63 65 73 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 ces or.** sqlite
26f70 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 3_result_blob is
26f80 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e the special con
26f90 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 stant SQLITE_STA
26fa0 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 TIC, then SQLite
26fb0 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 .** assumes that
26fc0 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f the text or BLO
26fd0 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 B result is in c
26fe0 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e onstant space an
26ff0 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f d does not.** co
27000 70 79 20 74 68 65 20 69 74 20 6f 72 20 63 61 6c py the it or cal
27010 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 77 l a destructor w
27020 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 hen it has finis
27030 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 hed using that r
27040 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 esult..** If the
27050 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 4th parameter t
27060 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 o the sqlite3_re
27070 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 sult_text* inter
27080 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 faces.** or sqli
27090 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 te3_result_blob
270a0 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 is the special c
270b0 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 onstant SQLITE_T
270c0 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e RANSIENT.** then
270d0 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 SQLite makes a
270e0 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 copy of the resu
270f0 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 lt into space ob
27100 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 tained from.** f
27110 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c rom [sqlite3_mal
27120 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 loc()] before it
27130 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 returns..**.**
27140 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
27150 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 lt_value() inter
27160 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 face sets the re
27170 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 sult of.** the a
27180 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
27190 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ed function to b
271a0 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 e a copy the.**
271b0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c [unprotected sql
271c0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
271d0 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20 ct specified by
271e0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
271f0 72 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 r. The.** sqlit
27200 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 e3_result_value(
27210 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 ) interface make
27220 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 s a copy of the
27230 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a [sqlite3_value].
27240 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b ** so that the [
27250 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 sqlite3_value] s
27260 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 pecified in the
27270 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 parameter may ch
27280 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 ange or.** be de
27290 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 allocated after
272a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 sqlite3_result_v
272b0 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 alue() returns w
272c0 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 ithout harm..**
272d0 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c A [protected sql
272e0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
272f0 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 ct may always be
27300 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a used where an.*
27310 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 * [unprotected s
27320 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
27330 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64 ject is required
27340 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b , so either.** k
27350 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f ind of [sqlite3_
27360 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 value] object ca
27370 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74 n be used with t
27380 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a his interface..*
27390 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f *.** If these ro
273a0 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 utines are calle
273b0 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 d from within th
273c0 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 e different thre
273d0 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f ad.** than the o
273e0 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 ne containing th
273f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
27400 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 fined function t
27410 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 hat received.**
27420 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e the [sqlite3_con
27430 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 text] pointer, t
27440 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 he results are u
27450 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
27460 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
27470 20 5b 48 31 36 34 30 33 5d 20 5b 48 31 36 34 30 [H16403] [H1640
27480 36 5d 20 5b 48 31 36 34 30 39 5d 20 5b 48 31 36 6] [H16409] [H16
27490 34 31 32 5d 20 5b 48 31 36 34 31 35 5d 20 5b 48 412] [H16415] [H
274a0 31 36 34 31 38 5d 20 5b 48 31 36 34 32 31 5d 20 16418] [H16421]
274b0 5b 48 31 36 34 32 34 5d 0a 2a 2a 20 5b 48 31 36 [H16424].** [H16
274c0 34 32 37 5d 20 5b 48 31 36 34 33 30 5d 20 5b 48 427] [H16430] [H
274d0 31 36 34 33 33 5d 20 5b 48 31 36 34 33 36 5d 20 16433] [H16436]
274e0 5b 48 31 36 34 33 39 5d 20 5b 48 31 36 34 34 32 [H16439] [H16442
274f0 5d 20 5b 48 31 36 34 34 35 5d 20 5b 48 31 36 34 ] [H16445] [H164
27500 34 38 5d 0a 2a 2a 20 5b 48 31 36 34 35 31 5d 20 48].** [H16451]
27510 5b 48 31 36 34 35 34 5d 20 5b 48 31 36 34 35 37 [H16454] [H16457
27520 5d 20 5b 48 31 36 34 36 30 5d 20 5b 48 31 36 34 ] [H16460] [H164
27530 36 33 5d 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 63].*/.void sqli
27540 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 te3_result_blob(
27550 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
27560 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 , const void*, i
27570 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 nt, void(*)(void
27580 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 *));.void sqlite
27590 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 3_result_double(
275a0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
275b0 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 , double);.void
275c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
275d0 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e rror(sqlite3_con
275e0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 text*, const cha
275f0 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 r*, int);.void s
27600 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
27610 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f ror16(sqlite3_co
27620 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f ntext*, const vo
27630 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 id*, int);.void
27640 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
27650 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 rror_toobig(sqli
27660 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 te3_context*);.v
27670 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
27680 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 lt_error_nomem(s
27690 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 qlite3_context*)
276a0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
276b0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 esult_error_code
276c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
276d0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 *, int);.void sq
276e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 lite3_result_int
276f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
27700 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 *, int);.void sq
27710 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 lite3_result_int
27720 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 64(sqlite3_conte
27730 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 xt*, sqlite3_int
27740 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 64);.void sqlite
27750 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 3_result_null(sq
27760 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b lite3_context*);
27770 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
27780 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 sult_text(sqlite
27790 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 3_context*, cons
277a0 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f t char*, int, vo
277b0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 id(*)(void*));.v
277c0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
277d0 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 lt_text16(sqlite
277e0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 3_context*, cons
277f0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f t void*, int, vo
27800 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 id(*)(void*));.v
27810 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
27820 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 lt_text16le(sqli
27830 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f te3_context*, co
27840 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 nst void*, int,v
27850 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
27860 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
27870 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c ult_text16be(sql
27880 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 ite3_context*, c
27890 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c onst void*, int,
278a0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
278b0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
278c0 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 sult_value(sqlit
278d0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c e3_context*, sql
278e0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f ite3_value*);.vo
278f0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
27900 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 t_zeroblob(sqlit
27910 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 e3_context*, int
27920 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 n);../*.** CAPI
27930 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 3REF: Define New
27940 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 Collating Seque
27950 6e 63 65 73 20 7b 48 31 36 36 30 30 7d 20 3c 53 nces {H16600} <S
27960 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20300>.**.** The
27970 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 se functions are
27980 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77 used to add new
27990 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 collation seque
279a0 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b nces to the.** [
279b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
279c0 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 ion] specified a
279d0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 s the first argu
279e0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ment..**.** The
279f0 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20 name of the new
27a00 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e collation sequen
27a10 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64 20 ce is specified
27a20 61 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e as a UTF-8 strin
27a30 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 g.** for sqlite3
27a40 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
27a50 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f n() and sqlite3_
27a60 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
27a70 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 _v2().** and a U
27a80 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72 TF-16 string for
27a90 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
27aa0 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49 collation16(). I
27ab0 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 n all cases.** t
27ac0 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65 he name is passe
27ad0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 d as the second
27ae0 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e function argumen
27af0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 t..**.** The thi
27b00 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 rd argument may
27b10 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f be one of the co
27b20 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f nstants [SQLITE_
27b30 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 UTF8],.** [SQLIT
27b40 45 5f 55 54 46 31 36 4c 45 5d 2c 20 6f 72 20 5b E_UTF16LE], or [
27b50 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c SQLITE_UTF16BE],
27b60 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 indicating that
27b70 20 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69 the user-suppli
27b80 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 ed.** routine ex
27b90 70 65 63 74 73 20 74 6f 20 62 65 20 70 61 73 73 pects to be pass
27ba0 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 ed pointers to s
27bb0 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 trings encoded u
27bc0 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 sing UTF-8,.** U
27bd0 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 TF-16 little-end
27be0 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 ian, or UTF-16 b
27bf0 69 67 2d 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 ig-endian, respe
27c00 63 74 69 76 65 6c 79 2e 20 54 68 65 0a 2a 2a 20 ctively. The.**
27c10 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d third argument m
27c20 69 67 68 74 20 61 6c 73 6f 20 62 65 20 5b 53 51 ight also be [SQ
27c30 4c 49 54 45 5f 55 54 46 31 36 5d 20 74 6f 20 69 LITE_UTF16] to i
27c40 6e 64 69 63 61 74 65 20 74 68 61 74 20 74 68 65 ndicate that the
27c50 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 65 78 70 65 routine.** expe
27c60 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 cts pointers to
27c70 62 65 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 be UTF-16 string
27c80 73 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 s in the native
27c90 62 79 74 65 20 6f 72 64 65 72 2c 20 6f 72 20 74 byte order, or t
27ca0 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 63 he.** argument c
27cb0 61 6e 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 an be [SQLITE_UT
27cc0 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 69 66 20 F16_ALIGNED] if
27cd0 74 68 65 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 the.** the routi
27ce0 6e 65 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74 ne expects point
27cf0 65 72 73 20 74 6f 20 31 36 2d 62 69 74 20 77 6f ers to 16-bit wo
27d00 72 64 20 61 6c 69 67 6e 65 64 20 73 74 72 69 6e rd aligned strin
27d10 67 73 0a 2a 2a 20 6f 66 20 55 54 46 2d 31 36 20 gs.** of UTF-16
27d20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 in the native by
27d30 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 te order..**.**
27d40 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 A pointer to the
27d50 20 75 73 65 72 20 73 75 70 70 6c 69 65 64 20 72 user supplied r
27d60 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70 outine must be p
27d70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 66 assed as the fif
27d80 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 th.** argument.
27d90 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 If it is NULL,
27da0 74 68 69 73 20 69 73 20 74 68 65 20 73 61 6d 65 this is the same
27db0 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65 as deleting the
27dc0 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 collation.** se
27dd0 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20 quence (so that
27de0 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 SQLite cannot ca
27df0 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a ll it anymore)..
27e00 2a 2a 20 45 61 63 68 20 74 69 6d 65 20 74 68 65 ** Each time the
27e10 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 75 70 application sup
27e20 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 plied function i
27e30 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 s invoked, it is
27e40 20 70 61 73 73 65 64 0a 2a 2a 20 61 73 20 69 74 passed.** as it
27e50 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 s first paramete
27e60 72 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 r a copy of the
27e70 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73 20 void* passed as
27e80 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d the fourth argum
27e90 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 ent.** to sqlite
27ea0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
27eb0 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f on() or sqlite3_
27ec0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
27ed0 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 16()..**.** The
27ee0 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 remaining argume
27ef0 6e 74 73 20 74 6f 20 74 68 65 20 61 70 70 6c 69 nts to the appli
27f00 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 cation-supplied
27f10 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20 routine are two
27f20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 strings,.** each
27f30 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 represented by
27f40 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 a (length, data)
27f50 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 pair and encode
27f60 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e d in the encodin
27f70 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61 g.** that was pa
27f80 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 ssed as the thir
27f90 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 d argument when
27fa0 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 the collation se
27fb0 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 quence was.** re
27fc0 67 69 73 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20 gistered. {END}
27fd0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
27fe0 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 defined collati
27ff0 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c on routine shoul
28000 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67 61 d.** return nega
28010 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f tive, zero or po
28020 73 69 74 69 76 65 20 69 66 20 74 68 65 20 66 69 sitive if the fi
28030 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 rst string is le
28040 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61 ss than,.** equa
28050 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 l to, or greater
28060 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 than the second
28070 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 string. i.e. (S
28080 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 TRING1 - STRING2
28090 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c )..**.** The sql
280a0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
280b0 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 ation_v2() works
280c0 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 like sqlite3_cr
280d0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 eate_collation()
280e0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 .** except that
280f0 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72 it takes an extr
28100 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 a argument which
28110 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 is a destructor
28120 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c for.** the coll
28130 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 ation. The dest
28140 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 ructor is called
28150 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 when the collat
28160 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f ion is.** destro
28170 79 65 64 20 61 6e 64 20 69 73 20 70 61 73 73 65 yed and is passe
28180 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 d a copy of the
28190 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
281a0 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a void* pointer.*
281b0 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 * of the sqlite3
281c0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
281d0 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 n_v2()..** Colla
281e0 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f tions are destro
281f0 79 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 yed when they ar
28200 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 e overridden by
28210 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 later calls to t
28220 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20 he.** collation
28230 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f creation functio
28240 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b ns or when the [
28250 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
28260 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a ion] is closed.*
28270 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 * using [sqlite3
28280 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a _close()]..**.**
28290 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c See also: [sql
282a0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
282b0 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 eeded()] and [sq
282c0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
282d0 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2a 0a needed16()]..**.
282e0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
282f0 0a 2a 2a 20 5b 48 31 36 36 30 33 5d 20 5b 48 31 .** [H16603] [H1
28300 36 36 30 34 5d 20 5b 48 31 36 36 30 36 5d 20 5b 6604] [H16606] [
28310 48 31 36 36 30 39 5d 20 5b 48 31 36 36 31 32 5d H16609] [H16612]
28320 20 5b 48 31 36 36 31 35 5d 20 5b 48 31 36 36 31 [H16615] [H1661
28330 38 5d 20 5b 48 31 36 36 32 31 5d 0a 2a 2a 20 5b 8] [H16621].** [
28340 48 31 36 36 32 34 5d 20 5b 48 31 36 36 32 37 5d H16624] [H16627]
28350 20 5b 48 31 36 36 33 30 5d 0a 2a 2f 0a 69 6e 74 [H16630].*/.int
28360 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
28370 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c collation(. sql
28380 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 ite3*, . const
28390 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 char *zName, .
283a0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 int eTextRep, .
283b0 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 void*,. int(*x
283c0 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 Compare)(void*,i
283d0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 nt,const void*,i
283e0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a nt,const void*).
283f0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 );.int sqlite3_c
28400 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f reate_collation_
28410 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 v2(. sqlite3*,
28420 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
28430 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 Name, . int eTe
28440 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c xtRep, . void*,
28450 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 . int(*xCompare
28460 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 )(void*,int,cons
28470 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 t void*,int,cons
28480 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 t void*),. void
28490 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 (*xDestroy)(void
284a0 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 *).);.int sqlite
284b0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
284c0 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a on16(. sqlite3*
284d0 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 , . const void
284e0 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 *zName,. int eT
284f0 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a extRep, . void*
28500 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 ,. int(*xCompar
28510 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e e)(void*,int,con
28520 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e st void*,int,con
28530 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a st void*).);../*
28540 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
28550 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 llation Needed C
28560 61 6c 6c 62 61 63 6b 73 20 7b 48 31 36 37 30 30 allbacks {H16700
28570 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a } <S20300>.**.**
28580 20 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 To avoid having
28590 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c to register all
285a0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 collation seque
285b0 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 nces before a da
285c0 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 tabase.** can be
285d0 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 used, a single
285e0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
285f0 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 n may be registe
28600 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 red with the.**
28610 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
28620 74 69 6f 6e 5d 20 74 6f 20 62 65 20 63 61 6c 6c tion] to be call
28630 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 ed whenever an u
28640 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 ndefined collati
28650 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 on.** sequence i
28660 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a s required..**.*
28670 2a 20 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f * If the functio
28680 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 n is registered
28690 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 using the sqlite
286a0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 3_collation_need
286b0 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 ed() API,.** the
286c0 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74 n it is passed t
286d0 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 he names of unde
286e0 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 fined collation
286f0 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 sequences as str
28700 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 ings.** encoded
28710 69 6e 20 55 54 46 2d 38 2e 20 7b 48 31 36 37 30 in UTF-8. {H1670
28720 33 7d 20 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 3} If sqlite3_co
28730 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 llation_needed16
28740 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 () is used,.** t
28750 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 he names are pas
28760 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e sed as UTF-16 in
28770 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 machine native
28780 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 41 byte order..** A
28790 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 call to either
287a0 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 function replace
287b0 73 20 61 6e 79 20 65 78 69 73 74 69 6e 67 20 63 s any existing c
287c0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 allback..**.** W
287d0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b hen the callback
287e0 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 is invoked, the
287f0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
28800 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 passed is a copy
28810 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e .** of the secon
28820 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 d argument to sq
28830 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
28840 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 needed() or.** s
28850 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
28860 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 _needed16(). Th
28870 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
28880 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 t is the databas
28890 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e e.** connection.
288a0 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 The third argu
288b0 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b ment is one of [
288c0 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 SQLITE_UTF8], [S
288d0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a QLITE_UTF16BE],.
288e0 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 ** or [SQLITE_UT
288f0 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 F16LE], indicati
28900 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 ng the most desi
28910 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 rable form of th
28920 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 e collation.** s
28930 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e equence function
28940 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 required. The
28950 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
28960 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 is the name of
28970 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 the.** required
28980 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e collation sequen
28990 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 ce..**.** The ca
289a0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
289b0 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 should register
289c0 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c the desired coll
289d0 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b ation using.** [
289e0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
289f0 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 ollation()], [sq
28a00 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
28a10 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a lation16()], or.
28a20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 ** [sqlite3_crea
28a30 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 te_collation_v2(
28a40 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 )]..**.** Requir
28a50 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 37 ements:.** [H167
28a60 30 32 5d 20 5b 48 31 36 37 30 34 5d 20 5b 48 31 02] [H16704] [H1
28a70 36 37 30 36 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 6706].*/.int sql
28a80 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
28a90 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 eeded(. sqlite3
28aa0 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 *, . void*, .
28ab0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 void(*)(void*,sq
28ac0 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 lite3*,int eText
28ad0 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 Rep,const char*)
28ae0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .);.int sqlite3_
28af0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 collation_needed
28b00 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 16(. sqlite3*,
28b10 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 . void*,. void
28b20 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 (*)(void*,sqlite
28b30 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 3*,int eTextRep,
28b40 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a const void*).);.
28b50 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 ./*.** Specify t
28b60 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e he key for an en
28b70 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65 crypted database
28b80 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 . This routine
28b90 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c should be.** cal
28ba0 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20 led right after
28bb0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a sqlite3_open()..
28bc0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 **.** The code t
28bd0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 o implement this
28be0 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 API is not avai
28bf0 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 lable in the pub
28c00 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f lic release.** o
28c10 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 f SQLite..*/.int
28c20 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 sqlite3_key(.
28c30 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
28c40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
28c50 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 * Database to be
28c60 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f rekeyed */. co
28c70 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 nst void *pKey,
28c80 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 int nKey /*
28c90 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f The key */.);../
28ca0 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 *.** Change the
28cb0 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 key on an open d
28cc0 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 atabase. If the
28cd0 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 current databas
28ce0 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 e is not.** encr
28cf0 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 ypted, this rout
28d00 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 ine will encrypt
28d10 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 it. If pNew==0
28d20 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 or nNew==0, the
28d30 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 .** database is
28d40 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a decrypted..**.**
28d50 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 The code to imp
28d60 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 lement this API
28d70 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 is not available
28d80 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 in the public r
28d90 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c elease.** of SQL
28da0 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ite..*/.int sqli
28db0 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c te3_rekey(. sql
28dc0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
28dd0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 /* D
28de0 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 atabase to be re
28df0 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 keyed */. const
28e00 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 void *pKey, int
28e10 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 nKey /* The
28e20 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a new key */.);..
28e30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
28e40 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f Suspend Executio
28e50 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 n For A Short Ti
28e60 6d 65 20 7b 48 31 30 35 33 30 7d 20 3c 53 34 30 me {H10530} <S40
28e70 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 410>.**.** The s
28e80 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 qlite3_sleep() f
28e90 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 unction causes t
28ea0 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 he current threa
28eb0 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 d to suspend exe
28ec0 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 cution.** for at
28ed0 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 least a number
28ee0 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 of milliseconds
28ef0 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 specified in its
28f00 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a parameter..**.*
28f10 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 * If the operati
28f20 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e ng system does n
28f30 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 ot support sleep
28f40 20 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a requests with.*
28f50 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 * millisecond ti
28f60 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 me resolution, t
28f70 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c hen the time wil
28f80 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 l be rounded up
28f90 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 to.** the neares
28fa0 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 t second. The nu
28fb0 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 mber of millisec
28fc0 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 onds of sleep ac
28fd0 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 tually.** reques
28fe0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 ted from the ope
28ff0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 rating system is
29000 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
29010 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e SQLite implemen
29020 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 ts this interfac
29030 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 e by calling the
29040 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 xSleep().** met
29050 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 hod of the defau
29060 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d lt [sqlite3_vfs]
29070 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 52 object..**.** R
29080 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 equirements: [H1
29090 30 35 33 33 5d 20 5b 48 31 30 35 33 36 5d 0a 2a 0533] [H10536].*
290a0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c /.int sqlite3_sl
290b0 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a eep(int);../*.**
290c0 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 CAPI3REF: Name
290d0 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f Of The Folder Ho
290e0 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 lding Temporary
290f0 46 69 6c 65 73 20 7b 48 31 30 33 31 30 7d 20 3c Files {H10310} <
29100 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 49 66 S20000>.**.** If
29110 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 this global var
29120 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f iable is made to
29130 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 point to a stri
29140 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 ng which is.** t
29150 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c he name of a fol
29160 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 der (a.k.a. dire
29170 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c ctory), then all
29180 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 temporary files
29190 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 .** created by S
291a0 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 70 6c QLite will be pl
291b0 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 aced in that dir
291c0 65 63 74 6f 72 79 2e 20 20 49 66 20 74 68 69 73 ectory. If this
291d0 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 variable.** is
291e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 a NULL pointer,
291f0 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66 then SQLite perf
29200 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f orms a search fo
29210 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 r an appropriate
29220 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 .** temporary fi
29230 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a le directory..**
29240 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 .** It is not sa
29250 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f fe to read or mo
29260 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 dify this variab
29270 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 le in more than
29280 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 one.** thread at
29290 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20 a time. It is
292a0 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 not safe to read
292b0 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 or modify this
292c0 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 variable.** if a
292d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
292e0 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 ction] is being
292f0 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65 used at the same
29300 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72 time in a separ
29310 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a ate.** thread..*
29320 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 * It is intended
29330 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 that this varia
29340 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a ble be set once.
29350 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 ** as part of pr
29360 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 ocess initializa
29370 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 tion and before
29380 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 any SQLite inter
29390 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 face.** routines
293a0 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 have been calle
293b0 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 d and that this
293c0 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 variable remain
293d0 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 unchanged.** the
293e0 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 reafter..**.** T
293f0 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 he [temp_store_d
29400 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d irectory pragma]
29410 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73 may modify this
29420 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61 variable and ca
29430 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 use.** it to poi
29440 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 nt to memory obt
29450 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 ained from [sqli
29460 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 46 75 te3_malloc]. Fu
29470 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 rthermore,.** th
29480 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 e [temp_store_di
29490 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 rectory pragma]
294a0 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20 74 always assumes t
294b0 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a hat any string.*
294c0 2a 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 * that this vari
294d0 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 able points to i
294e0 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 s held in memory
294f0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a obtained from .
29500 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c ** [sqlite3_mall
29510 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67 oc] and the prag
29520 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 ma may attempt t
29530 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f o free that memo
29540 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c ry.** using [sql
29550 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 ite3_free]..** H
29560 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76 61 ence, if this va
29570 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 riable is modifi
29580 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74 ed directly, eit
29590 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65 her it should be
295a0 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 .** made NULL or
295b0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 made to point t
295c0 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 o memory obtaine
295d0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
295e0 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c malloc].** or el
295f0 73 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 se the use of th
29600 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 e [temp_store_di
29610 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 rectory pragma]
29620 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 should be avoide
29630 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 d..*/.SQLITE_EXT
29640 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 ERN char *sqlite
29650 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3_temp_directory
29660 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
29670 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f F: Test For Auto
29680 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 20 7b 48 31 -Commit Mode {H1
29690 32 39 33 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2930} <S60200>.*
296a0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 * KEYWORDS: {aut
296b0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a ocommit mode}.**
296c0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
296d0 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 get_autocommit()
296e0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
296f0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a ns non-zero or.*
29700 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 * zero if the gi
29710 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e ven database con
29720 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 nection is or is
29730 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d not in autocomm
29740 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 it mode,.** resp
29750 65 63 74 69 76 65 6c 79 2e 20 20 41 75 74 6f 63 ectively. Autoc
29760 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e ommit mode is on
29770 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 by default..**
29780 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 Autocommit mode
29790 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 is disabled by a
297a0 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 [BEGIN] stateme
297b0 6e 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 nt..** Autocommi
297c0 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 t mode is re-ena
297d0 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 bled by a [COMMI
297e0 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d T] or [ROLLBACK]
297f0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 ..**.** If certa
29800 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f in kinds of erro
29810 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 rs occur on a st
29820 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 atement within a
29830 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 multi-statement
29840 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 .** transaction
29850 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e (errors includin
29860 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c g [SQLITE_FULL],
29870 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c [SQLITE_IOERR],
29880 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 .** [SQLITE_NOME
29890 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 M], [SQLITE_BUSY
298a0 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 ], and [SQLITE_I
298b0 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 NTERRUPT]) then
298c0 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 the.** transacti
298d0 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c on might be roll
298e0 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 ed back automati
298f0 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 cally. The only
29900 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 way to.** find
29910 6f 75 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 out whether SQLi
29920 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 te automatically
29930 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 rolled back the
29940 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 transaction aft
29950 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 er.** an error i
29960 73 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 s to use this fu
29970 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 nction..**.** If
29980 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 another thread
29990 63 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f changes the auto
299a0 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 commit status of
299b0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a the database.**
299c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c connection whil
299d0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 e this routine i
299e0 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 s running, then
299f0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
29a00 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 .** is undefined
29a10 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
29a20 65 6e 74 73 3a 20 5b 48 31 32 39 33 31 5d 20 5b ents: [H12931] [
29a30 48 31 32 39 33 32 5d 20 5b 48 31 32 39 33 33 5d H12932] [H12933]
29a40 20 5b 48 31 32 39 33 34 5d 0a 2a 2f 0a 69 6e 74 [H12934].*/.int
29a50 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 sqlite3_get_aut
29a60 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a ocommit(sqlite3*
29a70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
29a80 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74 EF: Find The Dat
29a90 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 abase Handle Of
29aa0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 A Prepared State
29ab0 6d 65 6e 74 20 7b 48 31 33 31 32 30 7d 20 3c 53 ment {H13120} <S
29ac0 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 60600>.**.** The
29ad0 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 sqlite3_db_hand
29ae0 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 le interface ret
29af0 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 urns the [databa
29b00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 se connection] h
29b10 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 andle.** to whic
29b20 68 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 h a [prepared st
29b30 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 atement] belongs
29b40 2e 20 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 . The [database
29b50 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 connection].**
29b60 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
29b70 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 te3_db_handle is
29b80 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 the same [datab
29b90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
29ba0 74 68 61 74 20 77 61 73 20 74 68 65 20 66 69 72 that was the fir
29bb0 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 st argument.** t
29bc0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 o the [sqlite3_p
29bd0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c repare_v2()] cal
29be0 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e l (or its varian
29bf0 74 73 29 20 74 68 61 74 20 77 61 73 20 75 73 65 ts) that was use
29c00 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 d to.** create t
29c10 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 he statement in
29c20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e the first place.
29c30 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
29c40 6e 74 73 3a 20 5b 48 31 33 31 32 33 5d 0a 2a 2f nts: [H13123].*/
29c50 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 .sqlite3 *sqlite
29c60 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 3_db_handle(sqli
29c70 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a te3_stmt*);../*.
29c80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e ** CAPI3REF: Fin
29c90 64 20 74 68 65 20 6e 65 78 74 20 70 72 65 70 61 d the next prepa
29ca0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 7b 48 red statement {H
29cb0 31 33 31 34 30 7d 20 3c 53 36 30 36 30 30 3e 0a 13140} <S60600>.
29cc0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 **.** This inter
29cd0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 face returns a p
29ce0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 65 ointer to the ne
29cf0 78 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 xt [prepared sta
29d00 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a tement] after.**
29d10 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74 65 pStmt associate
29d20 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 d with the [data
29d30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
29d40 20 70 44 62 2e 20 20 49 66 20 70 53 74 6d 74 20 pDb. If pStmt
29d50 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 is NULL.** then
29d60 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 this interface r
29d70 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
29d80 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 70 72 to the first pr
29d90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
29da0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 .** associated w
29db0 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65 ith the database
29dc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e connection pDb.
29dd0 20 20 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64 If no prepared
29de0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 statement.** sa
29df0 74 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64 tisfies the cond
29e00 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 itions of this r
29e10 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72 outine, it retur
29e20 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 ns NULL..**.** T
29e30 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
29e40 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 nection] pointer
29e50 20 44 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a D in a call to.
29e60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 ** [sqlite3_next
29e70 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 _stmt(D,S)] must
29e80 20 72 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 refer to an ope
29e90 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f n database.** co
29ea0 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 nnection and in
29eb0 70 61 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20 particular must
29ec0 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f not be a NULL po
29ed0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 inter..**.** Req
29ee0 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 33 31 uirements: [H131
29ef0 34 33 5d 20 5b 48 31 33 31 34 36 5d 20 5b 48 31 43] [H13146] [H1
29f00 33 31 34 39 5d 20 5b 48 31 33 31 35 32 5d 0a 2a 3149] [H13152].*
29f10 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a /.sqlite3_stmt *
29f20 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d sqlite3_next_stm
29f30 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 t(sqlite3 *pDb,
29f40 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
29f50 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tmt);../*.** CAP
29f60 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e I3REF: Commit An
29f70 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 d Rollback Notif
29f80 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b ication Callback
29f90 73 20 7b 48 31 32 39 35 30 7d 20 3c 53 36 30 34 s {H12950} <S604
29fa0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 00>.**.** The sq
29fb0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f lite3_commit_hoo
29fc0 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 k() interface re
29fd0 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 gisters a callba
29fe0 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 ck.** function t
29ff0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 o be invoked whe
2a000 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 never a transact
2a010 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c ion is [COMMIT |
2a020 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 committed]..**
2a030 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 Any callback set
2a040 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 by a previous c
2a050 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 all to sqlite3_c
2a060 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 ommit_hook().**
2a070 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 for the same dat
2a080 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2a090 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a is overridden..
2a0a0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 ** The sqlite3_r
2a0b0 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 ollback_hook() i
2a0c0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 nterface registe
2a0d0 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a rs a callback.**
2a0e0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
2a0f0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 invoked whenever
2a100 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 a transaction i
2a110 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f s [ROLLBACK | ro
2a120 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 41 lled back]..** A
2a130 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 ny callback set
2a140 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 by a previous ca
2a150 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ll to sqlite3_co
2a160 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 mmit_hook().** f
2a170 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 or the same data
2a180 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
2a190 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a is overridden..*
2a1a0 2a 20 54 68 65 20 70 41 72 67 20 61 72 67 75 6d * The pArg argum
2a1b0 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 68 ent is passed th
2a1c0 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c rough to the cal
2a1d0 6c 62 61 63 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 lback..** If the
2a1e0 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 callback on a c
2a1f0 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 ommit hook funct
2a200 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d ion returns non-
2a210 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 zero,.** then th
2a220 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 e commit is conv
2a230 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c erted into a rol
2a240 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 lback..**.** If
2a250 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e another function
2a260 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 was previously
2a270 72 65 67 69 73 74 65 72 65 64 2c 20 69 74 73 0a registered, its.
2a280 2a 2a 20 70 41 72 67 20 76 61 6c 75 65 20 69 73 ** pArg value is
2a290 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 returned. Othe
2a2a0 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 rwise NULL is re
2a2b0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 turned..**.** Th
2a2c0 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 e callback imple
2a2d0 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e mentation must n
2a2e0 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 ot do anything t
2a2f0 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a hat will modify.
2a300 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ** the database
2a310 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 connection that
2a320 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c invoked the call
2a330 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f back. Any actio
2a340 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 ns.** to modify
2a350 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
2a360 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 nection must be
2a370 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 deferred until a
2a380 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 fter the.** comp
2a390 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 letion of the [s
2a3a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 qlite3_step()] c
2a3b0 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 all that trigger
2a3c0 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a ed the commit.**
2a3d0 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f or rollback hoo
2a3e0 6b 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 k in the first p
2a3f0 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 lace..** Note th
2a400 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 at [sqlite3_prep
2a410 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 are_v2()] and [s
2a420 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 qlite3_step()] b
2a430 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 oth modify their
2a440 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
2a450 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 nections for the
2a460 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 meaning of "mod
2a470 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 ify" in this par
2a480 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 agraph..**.** Re
2a490 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c gistering a NULL
2a4a0 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c function disabl
2a4b0 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e es the callback.
2a4c0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 .**.** When the
2a4d0 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c commit hook call
2a4e0 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 74 back routine ret
2a4f0 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 5b urns zero, the [
2a500 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 COMMIT].** opera
2a510 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77 65 64 20 tion is allowed
2a520 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d to continue norm
2a530 61 6c 6c 79 2e 20 20 49 66 20 74 68 65 20 63 6f ally. If the co
2a540 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 mmit hook.** ret
2a550 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 urns non-zero, t
2a560 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d hen the [COMMIT]
2a570 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e is converted in
2a580 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e to a [ROLLBACK].
2a590 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b .** The rollback
2a5a0 20 68 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64 hook is invoked
2a5b0 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74 on a rollback t
2a5c0 68 61 74 20 72 65 73 75 6c 74 73 20 66 72 6f 6d hat results from
2a5d0 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f a commit.** hoo
2a5e0 6b 20 72 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d k returning non-
2a5f0 7a 65 72 6f 2c 20 6a 75 73 74 20 61 73 20 69 74 zero, just as it
2a600 20 77 6f 75 6c 64 20 62 65 20 77 69 74 68 20 61 would be with a
2a610 6e 79 20 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63 ny other rollbac
2a620 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 k..**.** For the
2a630 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 purposes of thi
2a640 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 s API, a transac
2a650 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 tion is said to
2a660 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c have been.** rol
2a670 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 led back if an e
2a680 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 xplicit "ROLLBAC
2a690 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 K" statement is
2a6a0 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 executed, or.**
2a6b0 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 an error or cons
2a6c0 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e traint causes an
2a6d0 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 implicit rollba
2a6e0 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 ck to occur..**
2a6f0 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c The rollback cal
2a700 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 lback is not inv
2a710 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 oked if a transa
2a720 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f ction is.** auto
2a730 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 matically rolled
2a740 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 back because th
2a750 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
2a760 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e ction is closed.
2a770 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b .** The rollback
2a780 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 callback is not
2a790 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 invoked if a tr
2a7a0 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 ansaction is.**
2a7b0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 rolled back beca
2a7c0 75 73 65 20 61 20 63 6f 6d 6d 69 74 20 63 61 6c use a commit cal
2a7d0 6c 62 61 63 6b 20 72 65 74 75 72 6e 65 64 20 6e lback returned n
2a7e0 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c 74 6f 64 on-zero..** <tod
2a7f0 6f 3e 20 43 68 65 63 6b 20 6f 6e 20 74 68 69 73 o> Check on this
2a800 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 53 </todo>.**.** S
2a810 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c ee also the [sql
2a820 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b ite3_update_hook
2a830 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a ()] interface..*
2a840 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
2a850 73 3a 0a 2a 2a 20 5b 48 31 32 39 35 31 5d 20 5b s:.** [H12951] [
2a860 48 31 32 39 35 32 5d 20 5b 48 31 32 39 35 33 5d H12952] [H12953]
2a870 20 5b 48 31 32 39 35 34 5d 20 5b 48 31 32 39 35 [H12954] [H1295
2a880 35 5d 0a 2a 2a 20 5b 48 31 32 39 36 31 5d 20 5b 5].** [H12961] [
2a890 48 31 32 39 36 32 5d 20 5b 48 31 32 39 36 33 5d H12962] [H12963]
2a8a0 20 5b 48 31 32 39 36 34 5d 0a 2a 2f 0a 76 6f 69 [H12964].*/.voi
2a8b0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 d *sqlite3_commi
2a8c0 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c t_hook(sqlite3*,
2a8d0 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 int(*)(void*),
2a8e0 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 void*);.void *sq
2a8f0 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 lite3_rollback_h
2a900 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f ook(sqlite3*, vo
2a910 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 id(*)(void *), v
2a920 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 oid*);../*.** CA
2a930 50 49 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 PI3REF: Data Cha
2a940 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e nge Notification
2a950 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 Callbacks {H129
2a960 37 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 70} <S60400>.**.
2a970 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 ** The sqlite3_u
2a980 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 pdate_hook() int
2a990 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 erface registers
2a9a0 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 a callback func
2a9b0 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 tion.** with the
2a9c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
2a9d0 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 ction] identifie
2a9e0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 d by the first a
2a9f0 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 rgument.** to be
2aa00 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 invoked wheneve
2aa10 72 20 61 20 72 6f 77 20 69 73 20 75 70 64 61 74 r a row is updat
2aa20 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 ed, inserted or
2aa30 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 deleted..** Any
2aa40 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 callback set by
2aa50 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 a previous call
2aa60 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e to this function
2aa70 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 .** for the same
2aa80 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
2aa90 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 tion is overridd
2aaa0 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 en..**.** The se
2aab0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 cond argument is
2aac0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
2aad0 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e e function to in
2aae0 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 voke when a.** r
2aaf0 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 ow is updated, i
2ab00 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 nserted or delet
2ab10 65 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 ed..** The first
2ab20 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
2ab30 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 callback is a c
2ab40 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 opy of the third
2ab50 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 argument.** to
2ab60 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 sqlite3_update_h
2ab70 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 ook()..** The se
2ab80 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 cond callback ar
2ab90 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 gument is one of
2aba0 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d [SQLITE_INSERT]
2abb0 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 , [SQLITE_DELETE
2abc0 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 ],.** or [SQLITE
2abd0 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 _UPDATE], depend
2abe0 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 ing on the opera
2abf0 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 tion that caused
2ac00 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a the callback.**
2ac10 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a to be invoked..
2ac20 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 ** The third and
2ac30 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 fourth argument
2ac40 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 s to the callbac
2ac50 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 k contain pointe
2ac60 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 rs to the.** dat
2ac70 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 abase and table
2ac80 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 name containing
2ac90 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 the affected row
2aca0 2e 0a 2a 2a 20 54 68 65 20 66 69 6e 61 6c 20 63 ..** The final c
2acb0 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 allback paramete
2acc0 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d r is the [rowid]
2acd0 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 of the row..**
2ace0 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 In the case of a
2acf0 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 n update, this i
2ad00 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 s the [rowid] af
2ad10 74 65 72 20 74 68 65 20 75 70 64 61 74 65 20 74 ter the update t
2ad20 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a akes place..**.*
2ad30 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f * The update hoo
2ad40 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 k is not invoked
2ad50 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 when internal s
2ad60 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 ystem tables are
2ad70 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e .** modified (i.
2ad80 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 e. sqlite_master
2ad90 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 and sqlite_sequ
2ada0 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 ence)..**.** In
2adb0 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c the current impl
2adc0 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65 20 ementation, the
2add0 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 update hook.** i
2ade0 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 s not invoked wh
2adf0 65 6e 20 64 75 70 6c 69 63 61 74 69 6f 6e 20 72 en duplication r
2ae00 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 ows are deleted
2ae10 62 65 63 61 75 73 65 20 6f 66 20 61 6e 0a 2a 2a because of an.**
2ae20 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 7c 20 [ON CONFLICT |
2ae30 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52 45 50 4c ON CONFLICT REPL
2ae40 41 43 45 5d 20 63 6c 61 75 73 65 2e 20 20 4e 6f ACE] clause. No
2ae50 72 20 69 73 20 74 68 65 20 75 70 64 61 74 65 20 r is the update
2ae60 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 hook.** invoked
2ae70 77 68 65 6e 20 72 6f 77 73 20 61 72 65 20 64 65 when rows are de
2ae80 6c 65 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 leted using the
2ae90 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 [truncate optimi
2aea0 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 zation]..** The
2aeb0 65 78 63 65 70 74 69 6f 6e 73 20 64 65 66 69 6e exceptions defin
2aec0 65 64 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 ed in this parag
2aed0 72 61 70 68 20 6d 69 67 68 74 20 63 68 61 6e 67 raph might chang
2aee0 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a e in a future.**
2aef0 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 release of SQLi
2af00 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 te..**.** The up
2af10 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d date hook implem
2af20 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f entation must no
2af30 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 t do anything th
2af40 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a at will modify.*
2af50 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 * the database c
2af60 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 onnection that i
2af70 6e 76 6f 6b 65 64 20 74 68 65 20 75 70 64 61 74 nvoked the updat
2af80 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 74 e hook. Any act
2af90 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 ions.** to modif
2afa0 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 y the database c
2afb0 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 onnection must b
2afc0 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c e deferred until
2afd0 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f after the.** co
2afe0 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 mpletion of the
2aff0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
2b000 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 call that trigg
2b010 65 72 65 64 20 74 68 65 20 75 70 64 61 74 65 20 ered the update
2b020 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 hook..** Note th
2b030 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 at [sqlite3_prep
2b040 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 are_v2()] and [s
2b050 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 qlite3_step()] b
2b060 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 oth modify their
2b070 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
2b080 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 nections for the
2b090 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 meaning of "mod
2b0a0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 ify" in this par
2b0b0 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 49 66 agraph..**.** If
2b0c0 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f another functio
2b0d0 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79 n was previously
2b0e0 20 72 65 67 69 73 74 65 72 65 64 2c 20 69 74 73 registered, its
2b0f0 20 70 41 72 67 20 76 61 6c 75 65 0a 2a 2a 20 69 pArg value.** i
2b100 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 s returned. Oth
2b110 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 erwise NULL is r
2b120 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 eturned..**.** S
2b130 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c ee also the [sql
2b140 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b ite3_commit_hook
2b150 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
2b160 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 _rollback_hook()
2b170 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e ].** interfaces.
2b180 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
2b190 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39 37 31 5d nts:.** [H12971]
2b1a0 20 5b 48 31 32 39 37 33 5d 20 5b 48 31 32 39 37 [H12973] [H1297
2b1b0 35 5d 20 5b 48 31 32 39 37 37 5d 20 5b 48 31 32 5] [H12977] [H12
2b1c0 39 37 39 5d 20 5b 48 31 32 39 38 31 5d 20 5b 48 979] [H12981] [H
2b1d0 31 32 39 38 33 5d 20 5b 48 31 32 39 38 36 5d 0a 12983] [H12986].
2b1e0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 */.void *sqlite3
2b1f0 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 _update_hook(.
2b200 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 sqlite3*, . voi
2b210 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 d(*)(void *,int
2b220 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 ,char const *,ch
2b230 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 ar const *,sqlit
2b240 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 e3_int64),. voi
2b250 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 d*.);../*.** CAP
2b260 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 I3REF: Enable Or
2b270 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64 20 Disable Shared
2b280 50 61 67 65 72 20 43 61 63 68 65 20 7b 48 31 30 Pager Cache {H10
2b290 33 33 30 7d 20 3c 53 33 30 39 30 30 3e 0a 2a 2a 330} <S30900>.**
2b2a0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 KEYWORDS: {shar
2b2b0 65 64 20 63 61 63 68 65 7d 20 7b 73 68 61 72 65 ed cache} {share
2b2c0 64 20 63 61 63 68 65 20 6d 6f 64 65 7d 0a 2a 2a d cache mode}.**
2b2d0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
2b2e0 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 enables or disa
2b2f0 62 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 bles the sharing
2b300 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
2b310 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 cache.** and sc
2b320 68 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 hema data struct
2b330 75 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 ures between [da
2b340 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2b350 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d n | connections]
2b360 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 .** to the same
2b370 64 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e database. Sharin
2b380 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 g is enabled if
2b390 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 the argument is
2b3a0 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 true.** and disa
2b3b0 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 bled if the argu
2b3c0 6d 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 0a 2a ment is false..*
2b3d0 2a 0a 2a 2a 20 43 61 63 68 65 20 73 68 61 72 69 *.** Cache shari
2b3e0 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e ng is enabled an
2b3f0 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61 d disabled for a
2b400 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 n entire process
2b410 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63 ..** This is a c
2b420 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69 hange as of SQLi
2b430 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 te version 3.5.0
2b440 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 . In prior versi
2b450 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a ons of SQLite,.*
2b460 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e * sharing was en
2b470 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 abled or disable
2b480 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 d for each threa
2b490 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a d separately..**
2b4a0 0a 2a 2a 20 54 68 65 20 63 61 63 68 65 20 73 68 .** The cache sh
2b4b0 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 aring mode set b
2b4c0 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 y this interface
2b4d0 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62 effects all sub
2b4e0 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 sequent.** calls
2b4f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 to [sqlite3_ope
2b500 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f n()], [sqlite3_o
2b510 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b pen_v2()], and [
2b520 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
2b530 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 ]..** Existing d
2b540 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2b550 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 ons continue use
2b560 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 the sharing mod
2b570 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e e.** that was in
2b580 20 65 66 66 65 63 74 20 61 74 20 74 68 65 20 74 effect at the t
2b590 69 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f 70 ime they were op
2b5a0 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 ened..**.** Virt
2b5b0 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f ual tables canno
2b5c0 74 20 62 65 20 75 73 65 64 20 77 69 74 68 20 61 t be used with a
2b5d0 20 73 68 61 72 65 64 20 63 61 63 68 65 2e 20 20 shared cache.
2b5e0 57 68 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63 When shared.** c
2b5f0 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 2c ache is enabled,
2b600 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 the [sqlite3_cr
2b610 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 41 eate_module()] A
2b620 50 49 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 PI used to regis
2b630 74 65 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 ter.** virtual t
2b640 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61 79 ables will alway
2b650 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f s return an erro
2b660 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f r..**.** This ro
2b670 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 utine returns [S
2b680 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 QLITE_OK] if sha
2b690 72 65 64 20 63 61 63 68 65 20 77 61 73 20 65 6e red cache was en
2b6a0 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 abled or disable
2b6b0 64 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c d.** successfull
2b6c0 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f y. An [error co
2b6d0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 de] is returned
2b6e0 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a otherwise..**.**
2b6f0 20 53 68 61 72 65 64 20 63 61 63 68 65 20 69 73 Shared cache is
2b700 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 disabled by def
2b710 61 75 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d ault. But this m
2b720 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a ight change in.*
2b730 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 * future release
2b740 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 s of SQLite. Ap
2b750 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 plications that
2b760 63 61 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 care about share
2b770 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 d.** cache setti
2b780 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 ng should set it
2b790 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a explicitly..**.
2b7a0 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 ** See Also: [S
2b7b0 51 4c 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 QLite Shared-Cac
2b7c0 68 65 20 4d 6f 64 65 5d 0a 2a 2a 0a 2a 2a 20 52 he Mode].**.** R
2b7d0 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 equirements: [H1
2b7e0 30 33 33 31 5d 20 5b 48 31 30 33 33 36 5d 20 5b 0331] [H10336] [
2b7f0 48 31 30 33 33 37 5d 20 5b 48 31 30 33 33 39 5d H10337] [H10339]
2b800 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
2b810 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 enable_shared_ca
2b820 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a che(int);../*.**
2b830 20 43 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d CAPI3REF: Attem
2b840 70 74 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 pt To Free Heap
2b850 4d 65 6d 6f 72 79 20 7b 48 31 37 33 34 30 7d 20 Memory {H17340}
2b860 3c 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S30220>.**.** T
2b870 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 he sqlite3_relea
2b880 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 se_memory() inte
2b890 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 rface attempts t
2b8a0 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a o free N bytes.*
2b8b0 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 * of heap memory
2b8c0 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 by deallocating
2b8d0 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d non-essential m
2b8e0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
2b8f0 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65 s.** held by the
2b900 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 database librar
2b910 79 2e 20 7b 45 4e 44 7d 20 20 4d 65 6d 6f 72 79 y. {END} Memory
2b920 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 used to cache d
2b930 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 atabase.** pages
2b940 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 to improve perf
2b950 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 ormance is an ex
2b960 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 ample of non-ess
2b970 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a ential memory..*
2b980 2a 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 * sqlite3_releas
2b990 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 e_memory() retur
2b9a0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
2b9b0 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 bytes actually
2b9c0 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 freed,.** which
2b9d0 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 might be more or
2b9e0 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 61 less than the a
2b9f0 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e mount requested.
2ba00 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
2ba10 6e 74 73 3a 20 5b 48 31 37 33 34 31 5d 20 5b 48 nts: [H17341] [H
2ba20 31 37 33 34 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 17342].*/.int sq
2ba30 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 lite3_release_me
2ba40 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a mory(int);../*.*
2ba50 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6d 70 6f * CAPI3REF: Impo
2ba60 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 se A Limit On He
2ba70 61 70 20 53 69 7a 65 20 7b 48 31 37 33 35 30 7d ap Size {H17350}
2ba80 20 3c 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 <S30220>.**.**
2ba90 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 The sqlite3_soft
2baa0 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 20 69 6e _heap_limit() in
2bab0 74 65 72 66 61 63 65 20 70 6c 61 63 65 73 20 61 terface places a
2bac0 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 0a 2a 2a "soft" limit.**
2bad0 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f on the amount o
2bae0 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 f heap memory th
2baf0 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 at may be alloca
2bb00 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a ted by SQLite..*
2bb10 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c * If an internal
2bb20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 allocation is r
2bb30 65 71 75 65 73 74 65 64 20 74 68 61 74 20 77 6f equested that wo
2bb40 75 6c 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a uld exceed the.*
2bb50 2a 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 * soft heap limi
2bb60 74 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 t, [sqlite3_rele
2bb70 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 ase_memory()] is
2bb80 20 69 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 0a invoked one or.
2bb90 2a 2a 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f ** more times to
2bba0 20 66 72 65 65 20 75 70 20 73 6f 6d 65 20 73 70 free up some sp
2bbb0 61 63 65 20 62 65 66 6f 72 65 20 74 68 65 20 61 ace before the a
2bbc0 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 70 65 72 llocation is per
2bbd0 66 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 formed..**.** Th
2bbe0 65 20 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 e limit is calle
2bbf0 64 20 22 73 6f 66 74 22 2c 20 62 65 63 61 75 73 d "soft", becaus
2bc00 65 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 72 65 e if [sqlite3_re
2bc10 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a lease_memory()].
2bc20 2a 2a 20 63 61 6e 6e 6f 74 20 66 72 65 65 20 73 ** cannot free s
2bc30 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 ufficient memory
2bc40 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 65 20 to prevent the
2bc50 6c 69 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 limit from being
2bc60 20 65 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68 exceeded,.** th
2bc70 65 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f e memory is allo
2bc80 63 61 74 65 64 20 61 6e 79 77 61 79 20 61 6e 64 cated anyway and
2bc90 20 74 68 65 20 63 75 72 72 65 6e 74 20 6f 70 65 the current ope
2bca0 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e ration proceeds.
2bcb0 0a 2a 2a 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 .**.** A negativ
2bcc0 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 e or zero value
2bcd0 66 6f 72 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 for N means that
2bce0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 there is no sof
2bcf0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 t heap limit and
2bd00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c .** [sqlite3_rel
2bd10 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 ease_memory()] w
2bd20 69 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c ill only be call
2bd30 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 ed when memory i
2bd40 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 s exhausted..**
2bd50 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 The default valu
2bd60 65 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 e for the soft h
2bd70 65 61 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 eap limit is zer
2bd80 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 o..**.** SQLite
2bd90 6d 61 6b 65 73 20 61 20 62 65 73 74 20 65 66 66 makes a best eff
2bda0 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 ort to honor the
2bdb0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 soft heap limit
2bdc0 2e 0a 2a 2a 20 42 75 74 20 69 66 20 74 68 65 20 ..** But if the
2bdd0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 soft heap limit
2bde0 63 61 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 cannot be honore
2bdf0 64 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c d, execution wil
2be00 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 l.** continue wi
2be10 74 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e thout error or n
2be20 6f 74 69 66 69 63 61 74 69 6f 6e 2e 20 20 54 68 otification. Th
2be30 69 73 20 69 73 20 77 68 79 20 74 68 65 20 6c 69 is is why the li
2be40 6d 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 mit is.** called
2be50 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e a "soft" limit.
2be60 20 20 49 74 20 69 73 20 61 64 76 69 73 6f 72 79 It is advisory
2be70 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 only..**.** Pri
2be80 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 or to SQLite ver
2be90 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 sion 3.5.0, this
2bea0 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f routine only co
2beb0 6e 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65 nstrained the me
2bec0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 mory.** allocate
2bed0 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 d by a single th
2bee0 72 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20 read - the same
2bef0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 thread in which
2bf00 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 this routine.**
2bf10 72 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 runs. Beginning
2bf20 20 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 with SQLite ver
2bf30 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 sion 3.5.0, the
2bf40 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 soft heap limit
2bf50 69 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f is.** applied to
2bf60 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68 all threads. Th
2bf70 65 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 e value specifie
2bf80 64 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 d for the soft h
2bf90 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 eap limit.** is
2bfa0 61 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f an upper bound o
2bfb0 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f n the total memo
2bfc0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f ry allocation fo
2bfd0 72 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 r all threads. I
2bfe0 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 n.** version 3.5
2bff0 2e 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d .0 there is no m
2c000 65 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d echanism for lim
2c010 69 74 69 6e 67 20 74 68 65 20 68 65 61 70 20 75 iting the heap u
2c020 73 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 sage for.** indi
2c030 76 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a vidual threads..
2c040 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
2c050 74 73 3a 0a 2a 2a 20 5b 48 31 36 33 35 31 5d 20 ts:.** [H16351]
2c060 5b 48 31 36 33 35 32 5d 20 5b 48 31 36 33 35 33 [H16352] [H16353
2c070 5d 20 5b 48 31 36 33 35 34 5d 20 5b 48 31 36 33 ] [H16354] [H163
2c080 35 35 5d 20 5b 48 31 36 33 35 38 5d 0a 2a 2f 0a 55] [H16358].*/.
2c090 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 void sqlite3_sof
2c0a0 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 t_heap_limit(int
2c0b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2c0c0 45 46 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61 EF: Extract Meta
2c0d0 64 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c data About A Col
2c0e0 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 20 7b umn Of A Table {
2c0f0 48 31 32 38 35 30 7d 20 3c 53 36 30 33 30 30 3e H12850} <S60300>
2c100 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
2c110 69 6e 65 20 72 65 74 75 72 6e 73 20 6d 65 74 61 ine returns meta
2c120 64 61 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 data about a spe
2c130 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 cific column of
2c140 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 a specific.** da
2c150 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 63 63 tabase table acc
2c160 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 essible using th
2c170 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
2c180 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a ection] handle.*
2c190 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 * passed as the
2c1a0 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 first function a
2c1b0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 rgument..**.** T
2c1c0 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 he column is ide
2c1d0 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73 ntified by the s
2c1e0 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 econd, third and
2c1f0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
2c200 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 rs to.** this fu
2c210 6e 63 74 69 6f 6e 2e 20 54 68 65 20 73 65 63 6f nction. The seco
2c220 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
2c230 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20 either the name
2c240 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a of the database.
2c250 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c ** (i.e. "main",
2c260 20 22 74 65 6d 70 22 20 6f 72 20 61 6e 20 61 74 "temp" or an at
2c270 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 29 tached database)
2c280 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 containing the
2c290 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 specified.** tab
2c2a0 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 49 66 20 69 le or NULL. If i
2c2b0 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 t is NULL, then
2c2c0 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64 61 74 all attached dat
2c2d0 61 62 61 73 65 73 20 61 72 65 20 73 65 61 72 63 abases are searc
2c2e0 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 hed.** for the t
2c2f0 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73 able using the s
2c300 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 75 73 ame algorithm us
2c310 65 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61 ed by the databa
2c320 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 se engine to.**
2c330 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 resolve unqualif
2c340 69 65 64 20 74 61 62 6c 65 20 72 65 66 65 72 65 ied table refere
2c350 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 nces..**.** The
2c360 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 third and fourth
2c370 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 parameters to t
2c380 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 his function are
2c390 20 74 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63 the table and c
2c3a0 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 olumn.** name of
2c3b0 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c the desired col
2c3c0 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c umn, respectivel
2c3d0 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68 y. Neither of th
2c3e0 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a ese parameters.*
2c3f0 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a * may be NULL..*
2c400 2a 0a 2a 2a 20 4d 65 74 61 64 61 74 61 20 69 73 *.** Metadata is
2c410 20 72 65 74 75 72 6e 65 64 20 62 79 20 77 72 69 returned by wri
2c420 74 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f ting to the memo
2c430 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 ry locations pas
2c440 73 65 64 20 61 73 20 74 68 65 20 35 74 68 0a 2a sed as the 5th.*
2c450 2a 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 * and subsequent
2c460 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 parameters to t
2c470 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 41 6e his function. An
2c480 79 20 6f 66 20 74 68 65 73 65 20 61 72 67 75 6d y of these argum
2c490 65 6e 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e ents may be.** N
2c4a0 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61 ULL, in which ca
2c4b0 73 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e se the correspon
2c4c0 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 ding element of
2c4d0 6d 65 74 61 64 61 74 61 20 69 73 20 6f 6d 69 74 metadata is omit
2c4e0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 ted..**.** <bloc
2c4f0 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c kquote>.** <tabl
2c500 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a e border="1">.**
2c510 20 3c 74 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65 <tr><th> Parame
2c520 74 65 72 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c ter <th> Output<
2c530 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 44 65 br>Type <th> De
2c540 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 scription.**.**
2c550 3c 74 72 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64 <tr><td> 5th <td
2c560 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 > const char* <t
2c570 64 3e 20 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 d> Data type.**
2c580 3c 74 72 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64 <tr><td> 6th <td
2c590 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 > const char* <t
2c5a0 64 3e 20 4e 61 6d 65 20 6f 66 20 64 65 66 61 75 d> Name of defau
2c5b0 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 lt collation seq
2c5c0 75 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 uence.** <tr><td
2c5d0 3e 20 37 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 > 7th <td> int
2c5e0 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 <td> True
2c5f0 20 69 66 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 if column has a
2c600 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 NOT NULL constr
2c610 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e aint.** <tr><td>
2c620 20 38 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 8th <td> int
2c630 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 <td> True
2c640 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 if column is par
2c650 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59 t of the PRIMARY
2c660 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e KEY.** <tr><td>
2c670 20 39 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 9th <td> int
2c680 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 <td> True
2c690 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 if column is [AU
2c6a0 54 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 TOINCREMENT].**
2c6b0 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c </table>.** </bl
2c6c0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
2c6d0 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 The memory point
2c6e0 65 64 20 74 6f 20 62 79 20 74 68 65 20 63 68 61 ed to by the cha
2c6f0 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20 racter pointers
2c700 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65 returned for the
2c710 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 .** declaration
2c720 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 type and collati
2c730 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 76 on sequence is v
2c740 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 alid only until
2c750 74 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c the next.** call
2c760 20 74 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41 to any SQLite A
2c770 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a PI function..**.
2c780 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63 69 66 ** If the specif
2c790 69 65 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 ied table is act
2c7a0 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 6e ually a view, an
2c7b0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 [error code] is
2c7c0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
2c7d0 20 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65 If the specifie
2c7e0 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 d column is "row
2c7f0 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f id", "oid" or "_
2c800 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a rowid_" and an.*
2c810 2a 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 * [INTEGER PRIMA
2c820 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 RY KEY] column h
2c830 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74 as been explicit
2c840 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65 ly declared, the
2c850 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 n the output.**
2c860 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 parameters are s
2c870 65 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69 et for the expli
2c880 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 citly declared c
2c890 6f 6c 75 6d 6e 2e 20 49 66 20 74 68 65 72 65 20 olumn. If there
2c8a0 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 is no.** explici
2c8b0 74 6c 79 20 64 65 63 6c 61 72 65 64 20 5b 49 4e tly declared [IN
2c8c0 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 TEGER PRIMARY KE
2c8d0 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 Y] column, then
2c8e0 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 the output.** pa
2c8f0 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 rameters are set
2c900 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a as follows:.**.
2c910 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 ** <pre>.**
2c920 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 data type: "INTE
2c930 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c GER".** coll
2c940 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 ation sequence:
2c950 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 "BINARY".**
2c960 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 not null: 0.**
2c970 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 primary key:
2c980 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 1.** auto in
2c990 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f crement: 0.** </
2c9a0 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 pre>.**.** This
2c9b0 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 function may loa
2c9c0 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 d one or more sc
2c9d0 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 62 hemas from datab
2c9e0 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20 61 6e ase files. If an
2c9f0 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 73 .** error occurs
2ca00 20 64 75 72 69 6e 67 20 74 68 69 73 20 70 72 6f during this pro
2ca10 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68 65 20 cess, or if the
2ca20 72 65 71 75 65 73 74 65 64 20 74 61 62 6c 65 20 requested table
2ca30 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e or column.** can
2ca40 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e not be found, an
2ca50 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 [error code] is
2ca60 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e returned and an
2ca70 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 6c error message l
2ca80 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64 eft.** in the [d
2ca90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2caa0 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65 74 72 69 on] (to be retri
2cab0 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 eved using sqlit
2cac0 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 0a 2a 2a e3_errmsg())..**
2cad0 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 69 73 20 .** This API is
2cae0 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 only available i
2caf0 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 f the library wa
2cb00 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 s compiled with
2cb10 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 the.** [SQLITE_E
2cb20 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 NABLE_COLUMN_MET
2cb30 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 ADATA] C-preproc
2cb40 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 essor symbol def
2cb50 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c ined..*/.int sql
2cb60 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d ite3_table_colum
2cb70 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71 n_metadata(. sq
2cb80 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
2cb90 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e /* Con
2cba0 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a nection handle *
2cbb0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
2cbc0 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 zDbName,
2cbd0 2f 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65 /* Database name
2cbe0 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f or NULL */. co
2cbf0 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 nst char *zTable
2cc00 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 Name, /* Tab
2cc10 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e le name */. con
2cc20 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e st char *zColumn
2cc30 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 Name, /* Colu
2cc40 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 mn name */. cha
2cc50 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 r const **pzData
2cc60 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 Type, /* OUTP
2cc70 55 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74 UT: Declared dat
2cc80 61 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 a type */. char
2cc90 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 const **pzCollS
2cca0 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 eq, /* OUTPU
2ccb0 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 T: Collation seq
2ccc0 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 uence name */.
2ccd0 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 int *pNotNull,
2cce0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f /* O
2ccf0 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e UTPUT: True if N
2cd00 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 OT NULL constrai
2cd10 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 nt exists */. i
2cd20 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c nt *pPrimaryKey,
2cd30 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 /* OU
2cd40 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f TPUT: True if co
2cd50 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 lumn part of PK
2cd60 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 */. int *pAutoi
2cd70 6e 63 20 20 20 20 20 20 20 20 20 20 20 20 20 20 nc
2cd80 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 /* OUTPUT: True
2cd90 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 if column is au
2cda0 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a to-increment */.
2cdb0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2cdc0 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 EF: Load An Exte
2cdd0 6e 73 69 6f 6e 20 7b 48 31 32 36 30 30 7d 20 3c nsion {H12600} <
2cde0 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S20500>.**.** Th
2cdf0 69 73 20 69 6e 74 65 72 66 61 63 65 20 6c 6f 61 is interface loa
2ce00 64 73 20 61 6e 20 53 51 4c 69 74 65 20 65 78 74 ds an SQLite ext
2ce10 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 66 ension library f
2ce20 72 6f 6d 20 74 68 65 20 6e 61 6d 65 64 20 66 69 rom the named fi
2ce30 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 le..**.** {H1260
2ce40 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 1} The sqlite3_l
2ce50 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 oad_extension()
2ce60 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 interface attemp
2ce70 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a ts to load an.**
2ce80 20 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 SQLite
2ce90 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 extension libra
2cea0 72 79 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 ry contained in
2ceb0 74 68 65 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a the file zFile..
2cec0 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 32 7d 20 54 **.** {H12602} T
2ced0 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 he entry point i
2cee0 73 20 7a 50 72 6f 63 2e 0a 2a 2a 0a 2a 2a 20 7b s zProc..**.** {
2cef0 48 31 32 36 30 33 7d 20 7a 50 72 6f 63 20 6d 61 H12603} zProc ma
2cf00 79 20 62 65 20 30 2c 20 69 6e 20 77 68 69 63 68 y be 0, in which
2cf10 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f case the name o
2cf20 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e f the entry poin
2cf30 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 t.** de
2cf40 66 61 75 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 faults to "sqlit
2cf50 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 e3_extension_ini
2cf60 74 22 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 t"..**.** {H1260
2cf70 34 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 4} The sqlite3_l
2cf80 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 oad_extension()
2cf90 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 interface shall
2cfa0 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 return.**
2cfb0 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f [SQLITE_OK] o
2cfc0 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 n success and [S
2cfd0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 QLITE_ERROR] if
2cfe0 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 something goes w
2cff0 72 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 rong..**.** {H12
2d000 36 30 35 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 605} If an error
2d010 20 6f 63 63 75 72 73 20 61 6e 64 20 70 7a 45 72 occurs and pzEr
2d020 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 rMsg is not 0, t
2d030 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 hen the.**
2d040 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 [sqlite3_loa
2d050 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 d_extension()] i
2d060 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 nterface shall a
2d070 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 20 20 20 ttempt to.**
2d080 20 20 20 20 20 20 66 69 6c 6c 20 2a 70 7a 45 72 fill *pzEr
2d090 72 4d 73 67 20 77 69 74 68 20 65 72 72 6f 72 20 rMsg with error
2d0a0 6d 65 73 73 61 67 65 20 74 65 78 74 20 73 74 6f message text sto
2d0b0 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a red in memory.**
2d0c0 20 20 20 20 20 20 20 20 20 20 6f 62 74 61 69 6e obtain
2d0d0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
2d0e0 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 7b 45 4e 44 _malloc()]. {END
2d0f0 7d 20 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 } The calling f
2d100 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 unction.**
2d110 20 20 20 20 73 68 6f 75 6c 64 20 66 72 65 65 20 should free
2d120 74 68 69 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 this memory by c
2d130 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
2d140 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b free()]..**.** {
2d150 48 31 32 36 30 36 7d 20 45 78 74 65 6e 73 69 6f H12606} Extensio
2d160 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 n loading must b
2d170 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a e enabled using.
2d180 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
2d190 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 ite3_enable_load
2d1a0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 _extension()] pr
2d1b0 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 ior to calling t
2d1c0 68 69 73 20 41 50 49 2c 0a 2a 2a 20 20 20 20 20 his API,.**
2d1d0 20 20 20 20 20 6f 74 68 65 72 77 69 73 65 20 61 otherwise a
2d1e0 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 n error will be
2d1f0 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 returned..*/.int
2d200 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 sqlite3_load_ex
2d210 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 tension(. sqlit
2d220 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
2d230 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65 78 74 /* Load the ext
2d240 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 ension into this
2d250 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
2d260 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 tion */. const
2d270 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 char *zFile,
2d280 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 /* Name of the s
2d290 68 61 72 65 64 20 6c 69 62 72 61 72 79 20 63 6f hared library co
2d2a0 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 ntaining extensi
2d2b0 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 on */. const ch
2d2c0 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a ar *zProc, /*
2d2d0 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 Entry point. D
2d2e0 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c erived from zFil
2d2f0 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 e if 0 */. char
2d300 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20 20 20 **pzErrMsg
2d310 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72 20 6d /* Put error m
2d320 65 73 73 61 67 65 20 68 65 72 65 20 69 66 20 6e essage here if n
2d330 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a ot 0 */.);../*.*
2d340 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 * CAPI3REF: Enab
2d350 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 le Or Disable Ex
2d360 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 tension Loading
2d370 7b 48 31 32 36 32 30 7d 20 3c 53 32 30 35 30 30 {H12620} <S20500
2d380 3e 0a 2a 2a 0a 2a 2a 20 53 6f 20 61 73 20 6e 6f >.**.** So as no
2d390 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 t to open securi
2d3a0 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 ty holes in olde
2d3b0 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 r applications t
2d3c0 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 hat are.** unpre
2d3d0 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77 69 pared to deal wi
2d3e0 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 th extension loa
2d3f0 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 6d ding, and as a m
2d400 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 6e eans of disablin
2d410 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c g.** extension l
2d420 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76 61 oading while eva
2d430 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 luating user-ent
2d440 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66 6f ered SQL, the fo
2d450 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 69 llowing API.** i
2d460 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74 75 s provided to tu
2d470 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f rn the [sqlite3_
2d480 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 load_extension()
2d490 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 ] mechanism on a
2d4a0 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 45 78 nd off..**.** Ex
2d4b0 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 tension loading
2d4c0 69 73 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c is off by defaul
2d4d0 74 2e 20 53 65 65 20 74 69 63 6b 65 74 20 23 31 t. See ticket #1
2d4e0 38 36 33 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 863..**.** {H126
2d4f0 32 31 7d 20 43 61 6c 6c 20 74 68 65 20 73 71 6c 21} Call the sql
2d500 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 ite3_enable_load
2d510 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75 _extension() rou
2d520 74 69 6e 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d tine with onoff=
2d530 3d 31 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 =1.** t
2d540 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e o turn extension
2d550 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 loading on and
2d560 63 61 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f call it with ono
2d570 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a ff==0 to turn.**
2d580 20 20 20 20 20 20 20 20 20 20 69 74 20 62 61 63 it bac
2d590 6b 20 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2a 0a k off again..**.
2d5a0 2a 2a 20 7b 48 31 32 36 32 32 7d 20 45 78 74 65 ** {H12622} Exte
2d5b0 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 nsion loading is
2d5c0 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e off by default.
2d5d0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
2d5e0 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 enable_load_exte
2d5f0 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64 nsion(sqlite3 *d
2d600 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a b, int onoff);..
2d610 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2d620 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f Automatically Lo
2d630 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 73 ad An Extensions
2d640 20 7b 48 31 32 36 34 30 7d 20 3c 53 32 30 35 30 {H12640} <S2050
2d650 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 0>.**.** This AP
2d660 49 20 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64 I can be invoked
2d670 20 61 74 20 70 72 6f 67 72 61 6d 20 73 74 61 72 at program star
2d680 74 75 70 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 tup in order to
2d690 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20 register.** one
2d6a0 6f 72 20 6d 6f 72 65 20 73 74 61 74 69 63 61 6c or more statical
2d6b0 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73 ly linked extens
2d6c0 69 6f 6e 73 20 74 68 61 74 20 77 69 6c 6c 20 62 ions that will b
2d6d0 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74 e available.** t
2d6e0 6f 20 61 6c 6c 20 6e 65 77 20 5b 64 61 74 61 62 o all new [datab
2d6f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d ase connections]
2d700 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 . {END}.**.** Th
2d710 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 is routine store
2d720 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 s a pointer to t
2d730 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20 he extension in
2d740 61 6e 20 61 72 72 61 79 20 74 68 61 74 20 69 73 an array that is
2d750 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f .** obtained fro
2d760 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f m [sqlite3_mallo
2d770 63 28 29 5d 2e 20 20 49 66 20 79 6f 75 20 72 75 c()]. If you ru
2d780 6e 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 20 n a memory leak
2d790 63 68 65 63 6b 65 72 0a 2a 2a 20 6f 6e 20 79 6f checker.** on yo
2d7a0 75 72 20 70 72 6f 67 72 61 6d 20 61 6e 64 20 69 ur program and i
2d7b0 74 20 72 65 70 6f 72 74 73 20 61 20 6c 65 61 6b t reports a leak
2d7c0 20 62 65 63 61 75 73 65 20 6f 66 20 74 68 69 73 because of this
2d7d0 20 61 72 72 61 79 2c 20 69 6e 76 6f 6b 65 0a 2a array, invoke.*
2d7e0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 * [sqlite3_reset
2d7f0 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 _auto_extension(
2d800 29 5d 20 70 72 69 6f 72 20 74 6f 20 73 68 75 74 )] prior to shut
2d810 64 6f 77 6e 20 74 6f 20 66 72 65 65 20 74 68 65 down to free the
2d820 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b memory..**.** {
2d830 48 31 32 36 34 31 7d 20 54 68 69 73 20 66 75 6e H12641} This fun
2d840 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 73 20 ction registers
2d850 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74 an extension ent
2d860 72 79 20 70 6f 69 6e 74 20 74 68 61 74 20 69 73 ry point that is
2d870 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 .** aut
2d880 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b omatically invok
2d890 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65 ed whenever a ne
2d8a0 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e w [database conn
2d8b0 65 63 74 69 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20 ection].**
2d8c0 20 20 20 20 69 73 20 6f 70 65 6e 65 64 20 75 73 is opened us
2d8d0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 ing [sqlite3_ope
2d8e0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f n()], [sqlite3_o
2d8f0 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 pen16()],.**
2d900 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 or [sqlite
2d910 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 3_open_v2()]..**
2d920 0a 2a 2a 20 7b 48 31 32 36 34 32 7d 20 44 75 70 .** {H12642} Dup
2d930 6c 69 63 61 74 65 20 65 78 74 65 6e 73 69 6f 6e licate extension
2d940 73 20 61 72 65 20 64 65 74 65 63 74 65 64 20 73 s are detected s
2d950 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 o calling this r
2d960 6f 75 74 69 6e 65 0a 2a 2a 20 20 20 20 20 20 20 outine.**
2d970 20 20 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 multiple time
2d980 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 s with the same
2d990 65 78 74 65 6e 73 69 6f 6e 20 69 73 20 68 61 72 extension is har
2d9a0 6d 6c 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 mless..**.** {H1
2d9b0 32 36 34 33 7d 20 54 68 69 73 20 72 6f 75 74 69 2643} This routi
2d9c0 6e 65 20 73 74 6f 72 65 73 20 61 20 70 6f 69 6e ne stores a poin
2d9d0 74 65 72 20 74 6f 20 74 68 65 20 65 78 74 65 6e ter to the exten
2d9e0 73 69 6f 6e 20 69 6e 20 61 6e 20 61 72 72 61 79 sion in an array
2d9f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 .** tha
2da00 74 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72 t is obtained fr
2da10 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
2da20 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 oc()]..**.** {H1
2da30 32 36 34 34 7d 20 41 75 74 6f 6d 61 74 69 63 20 2644} Automatic
2da40 65 78 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 extensions apply
2da50 20 61 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 across all thre
2da60 61 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ads..*/.int sqli
2da70 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 te3_auto_extensi
2da80 6f 6e 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 on(void (*xEntry
2da90 50 6f 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a Point)(void));..
2daa0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2dab0 52 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 Reset Automatic
2dac0 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e Extension Loadin
2dad0 67 20 7b 48 31 32 36 36 30 7d 20 3c 53 32 30 35 g {H12660} <S205
2dae0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 00>.**.** This f
2daf0 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 unction disables
2db00 20 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 all previously
2db10 72 65 67 69 73 74 65 72 65 64 20 61 75 74 6f 6d registered autom
2db20 61 74 69 63 0a 2a 2a 20 65 78 74 65 6e 73 69 6f atic.** extensio
2db30 6e 73 2e 20 7b 45 4e 44 7d 20 20 49 74 20 75 6e ns. {END} It un
2db40 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 does the effect
2db50 6f 66 20 61 6c 6c 20 70 72 69 6f 72 0a 2a 2a 20 of all prior.**
2db60 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 [sqlite3_auto_ex
2db70 74 65 6e 73 69 6f 6e 28 29 5d 20 63 61 6c 6c 73 tension()] calls
2db80 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36 31 7d ..**.** {H12661}
2db90 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 This function d
2dba0 69 73 61 62 6c 65 73 20 61 6c 6c 20 70 72 65 76 isables all prev
2dbb0 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 iously registere
2dbc0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 d.** au
2dbd0 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f tomatic extensio
2dbe0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36 ns..**.** {H1266
2dbf0 32 7d 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 2} This function
2dc00 20 64 69 73 61 62 6c 65 73 20 61 75 74 6f 6d 61 disables automa
2dc10 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 tic extensions i
2dc20 6e 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a n all threads..*
2dc30 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 /.void sqlite3_r
2dc40 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 eset_auto_extens
2dc50 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a ion(void);../*.*
2dc60 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 ***** EXPERIMENT
2dc70 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 AL - subject to
2dc80 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e change without n
2dc90 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a otice **********
2dca0 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 ****.**.** The i
2dcb0 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 nterface to the
2dcc0 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 virtual-table me
2dcd0 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65 chanism is curre
2dce0 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a ntly considered.
2dcf0 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d ** to be experim
2dd00 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 ental. The inte
2dd10 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e rface might chan
2dd20 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 ge in incompatib
2dd30 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 le ways..** If t
2dd40 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d his is a problem
2dd50 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 for you, do not
2dd60 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 use the interfa
2dd70 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e ce at this time.
2dd80 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 .**.** When the
2dd90 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 virtual-table me
2dda0 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a chanism stabiliz
2ddb0 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c es, we will decl
2ddc0 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 are the.** inter
2ddd0 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 face fixed, supp
2dde0 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 ort it indefinit
2ddf0 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 ely, and remove
2de00 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f this comment..*/
2de10 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 ../*.** Structur
2de20 65 73 20 75 73 65 64 20 62 79 20 74 68 65 20 76 es used by the v
2de30 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 irtual table int
2de40 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 erface.*/.typede
2de50 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
2de60 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 _vtab sqlite3_vt
2de70 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 ab;.typedef stru
2de80 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 ct sqlite3_index
2de90 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e _info sqlite3_in
2dea0 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 dex_info;.typede
2deb0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
2dec0 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c _vtab_cursor sql
2ded0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 ite3_vtab_cursor
2dee0 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 ;.typedef struct
2def0 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 sqlite3_module
2df00 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a sqlite3_module;.
2df10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2df20 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 4f Virtual Table O
2df30 62 6a 65 63 74 20 7b 48 31 38 30 30 30 7d 20 3c bject {H18000} <
2df40 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f S20400>.** KEYWO
2df50 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 RDS: sqlite3_mod
2df60 75 6c 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62 ule {virtual tab
2df70 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 20 45 58 le module}.** EX
2df80 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a PERIMENTAL.**.**
2df90 20 54 68 69 73 20 73 74 72 75 63 74 75 72 65 2c This structure,
2dfa0 20 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65 sometimes calle
2dfb0 64 20 61 20 61 20 22 76 69 72 74 75 61 6c 20 74 d a a "virtual t
2dfc0 61 62 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a able module", .*
2dfd0 2a 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6d * defines the im
2dfe0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
2dff0 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 a [virtual table
2e000 73 5d 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73 74 s]. .** This st
2e010 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73 ructure consists
2e020 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f mostly of metho
2e030 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c ds for the modul
2e040 65 2e 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 e..**.** A virtu
2e050 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 al table module
2e060 69 73 20 63 72 65 61 74 65 64 20 62 79 20 66 69 is created by fi
2e070 6c 6c 69 6e 67 20 69 6e 20 61 20 70 65 72 73 69 lling in a persi
2e080 73 74 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 stent.** instanc
2e090 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 e of this struct
2e0a0 75 72 65 20 61 6e 64 20 70 61 73 73 69 6e 67 20 ure and passing
2e0b0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 a pointer to tha
2e0c0 74 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f t instance.** to
2e0d0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
2e0e0 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73 _module()] or [s
2e0f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f qlite3_create_mo
2e100 64 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 dule_v2()]..** T
2e110 68 65 20 72 65 67 69 73 74 72 61 74 69 6f 6e 20 he registration
2e120 72 65 6d 61 69 6e 73 20 76 61 6c 69 64 20 75 6e remains valid un
2e130 74 69 6c 20 69 74 20 69 73 20 72 65 70 6c 61 63 til it is replac
2e140 65 64 20 62 79 20 61 20 64 69 66 66 65 72 65 6e ed by a differen
2e150 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75 t.** module or u
2e160 6e 74 69 6c 20 74 68 65 20 5b 64 61 74 61 62 61 ntil the [databa
2e170 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 se connection] c
2e180 6c 6f 73 65 73 2e 20 20 54 68 65 20 63 6f 6e 74 loses. The cont
2e190 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73 ent.** of this s
2e1a0 74 72 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f tructure must no
2e1b0 74 20 63 68 61 6e 67 65 20 77 68 69 6c 65 20 69 t change while i
2e1c0 74 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 t is registered
2e1d0 77 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61 with.** any data
2e1e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e base connection.
2e1f0 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 .*/.struct sqlit
2e200 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e e3_module {. in
2e210 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e t iVersion;. in
2e220 74 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c t (*xCreate)(sql
2e230 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 ite3*, void *pAu
2e240 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 x,.
2e250 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 int argc, cons
2e260 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 t char *const*ar
2e270 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 gv,.
2e280 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 sqlite3_vtab
2e290 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a **ppVTab, char**
2e2a0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e );. int (*xConn
2e2b0 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 ect)(sqlite3*, v
2e2c0 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 oid *pAux,.
2e2d0 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 int ar
2e2e0 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a gc, const char *
2e2f0 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 const*argv,.
2e300 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 sqlit
2e310 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 e3_vtab **ppVTab
2e320 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 , char**);. int
2e330 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 (*xBestIndex)(s
2e340 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 qlite3_vtab *pVT
2e350 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 ab, sqlite3_inde
2e360 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 x_info*);. int
2e370 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 (*xDisconnect)(s
2e380 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 qlite3_vtab *pVT
2e390 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 ab);. int (*xDe
2e3a0 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 stroy)(sqlite3_v
2e3b0 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 tab *pVTab);. i
2e3c0 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 nt (*xOpen)(sqli
2e3d0 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c te3_vtab *pVTab,
2e3e0 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 sqlite3_vtab_cu
2e3f0 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 rsor **ppCursor)
2e400 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 ;. int (*xClose
2e410 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 )(sqlite3_vtab_c
2e420 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 ursor*);. int (
2e430 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 *xFilter)(sqlite
2e440 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 3_vtab_cursor*,
2e450 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 int idxNum, cons
2e460 74 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a t char *idxStr,.
2e470 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2e480 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 int argc, sqlite
2e490 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 3_value **argv);
2e4a0 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 . int (*xNext)(
2e4b0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 sqlite3_vtab_cur
2e4c0 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 sor*);. int (*x
2e4d0 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 Eof)(sqlite3_vta
2e4e0 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e b_cursor*);. in
2e4f0 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c t (*xColumn)(sql
2e500 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 ite3_vtab_cursor
2e510 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 *, sqlite3_conte
2e520 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 xt*, int);. int
2e530 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 (*xRowid)(sqlit
2e540 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c e3_vtab_cursor*,
2e550 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a sqlite3_int64 *
2e560 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 pRowid);. int (
2e570 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 65 *xUpdate)(sqlite
2e580 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 3_vtab *, int, s
2e590 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c qlite3_value **,
2e5a0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a sqlite3_int64 *
2e5b0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69 );. int (*xBegi
2e5c0 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 n)(sqlite3_vtab
2e5d0 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 *pVTab);. int (
2e5e0 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f *xSync)(sqlite3_
2e5f0 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 vtab *pVTab);.
2e600 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 int (*xCommit)(s
2e610 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 qlite3_vtab *pVT
2e620 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f ab);. int (*xRo
2e630 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f llback)(sqlite3_
2e640 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 vtab *pVTab);.
2e650 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 int (*xFindFunct
2e660 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 ion)(sqlite3_vta
2e670 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 b *pVtab, int nA
2e680 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a rg, const char *
2e690 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 zName,.
2e6a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f vo
2e6b0 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 id (**pxFunc)(sq
2e6c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 lite3_context*,i
2e6d0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt,sqlite3_value
2e6e0 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 **),.
2e6f0 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 void
2e700 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e 74 **ppArg);. int
2e710 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 (*xRename)(sqli
2e720 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c te3_vtab *pVtab,
2e730 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 const char *zNe
2e740 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 w);.};../*.** CA
2e750 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 PI3REF: Virtual
2e760 54 61 62 6c 65 20 49 6e 64 65 78 69 6e 67 20 49 Table Indexing I
2e770 6e 66 6f 72 6d 61 74 69 6f 6e 20 7b 48 31 38 31 nformation {H181
2e780 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 00} <S20400>.**
2e790 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 KEYWORDS: sqlite
2e7a0 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a 20 3_index_info.**
2e7b0 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a EXPERIMENTAL.**.
2e7c0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 ** The sqlite3_i
2e7d0 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 ndex_info struct
2e7e0 75 72 65 20 61 6e 64 20 69 74 73 20 73 75 62 73 ure and its subs
2e7f0 74 72 75 63 74 75 72 65 73 20 69 73 20 75 73 65 tructures is use
2e800 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 d to.** pass inf
2e810 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e ormation into an
2e820 64 20 72 65 63 65 69 76 65 20 74 68 65 20 72 65 d receive the re
2e830 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 ply from the [xB
2e840 65 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 estIndex].** met
2e850 68 6f 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61 hod of a [virtua
2e860 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e l table module].
2e870 20 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64 The fields und
2e880 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 er **Inputs** ar
2e890 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 e the.** inputs
2e8a0 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e to xBestIndex an
2e8b0 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e d are read-only.
2e8c0 20 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73 xBestIndex ins
2e8d0 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 erts its.** resu
2e8e0 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f lts into the **O
2e8f0 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e utputs** fields.
2e900 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 .**.** The aCons
2e910 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 72 traint[] array r
2e920 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c 61 ecords WHERE cla
2e930 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 use constraints
2e940 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a 0a of the form:.**.
2e950 2a 2a 20 3c 70 72 65 3e 63 6f 6c 75 6d 6e 20 4f ** <pre>column O
2e960 50 20 65 78 70 72 3c 2f 70 72 65 3e 0a 2a 2a 0a P expr</pre>.**.
2e970 2a 2a 20 77 68 65 72 65 20 4f 50 20 69 73 20 3d ** where OP is =
2e980 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 , <, <=, &
2e990 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 20 20 gt;, or >=.
2e9a0 54 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 6f The particular o
2e9b0 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a 20 73 74 perator is.** st
2e9c0 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73 74 72 61 ored in aConstra
2e9d0 69 6e 74 5b 5d 2e 6f 70 2e 20 20 54 68 65 20 69 int[].op. The i
2e9e0 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 ndex of the colu
2e9f0 6d 6e 20 69 73 20 73 74 6f 72 65 64 20 69 6e 0a mn is stored in.
2ea00 2a 2a 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d ** aConstraint[]
2ea10 2e 69 43 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e 73 .iColumn. aCons
2ea20 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 traint[].usable
2ea30 69 73 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a is TRUE if the.*
2ea40 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 * expr on the ri
2ea50 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 ght-hand side ca
2ea60 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 n be evaluated (
2ea70 61 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e and thus the con
2ea80 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 straint.** is us
2ea90 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 able) and false
2eaa0 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a 2a if it cannot..**
2eab0 0a 2a 2a 20 54 68 65 20 6f 70 74 69 6d 69 7a 65 .** The optimize
2eac0 72 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 r automatically
2ead0 69 6e 76 65 72 74 73 20 74 65 72 6d 73 20 6f 66 inverts terms of
2eae0 20 74 68 65 20 66 6f 72 6d 20 22 65 78 70 72 20 the form "expr
2eaf0 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e OP column".** an
2eb00 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 69 d makes other si
2eb10 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 20 74 6f mplifications to
2eb20 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 the WHERE claus
2eb30 65 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 e in an attempt
2eb40 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e to.** get as man
2eb50 79 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 y WHERE clause t
2eb60 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 6f erms into the fo
2eb70 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 rm shown above a
2eb80 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 54 s possible..** T
2eb90 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d he aConstraint[]
2eba0 20 61 72 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f array only repo
2ebb0 72 74 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 rts WHERE clause
2ebc0 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20 63 6f terms in the co
2ebd0 72 72 65 63 74 0a 2a 2a 20 66 6f 72 6d 20 74 68 rrect.** form th
2ebe0 61 74 20 72 65 66 65 72 20 74 6f 20 74 68 65 20 at refer to the
2ebf0 70 61 72 74 69 63 75 6c 61 72 20 76 69 72 74 75 particular virtu
2ec00 61 6c 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71 al table being q
2ec10 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e ueried..**.** In
2ec20 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 formation about
2ec30 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 the ORDER BY cla
2ec40 75 73 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e use is stored in
2ec50 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 aOrderBy[]..**
2ec60 45 61 63 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 Each term of aOr
2ec70 64 65 72 42 79 20 72 65 63 6f 72 64 73 20 61 20 derBy records a
2ec80 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 column of the OR
2ec90 44 45 52 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a DER BY clause..*
2eca0 2a 0a 2a 2a 20 54 68 65 20 5b 78 42 65 73 74 49 *.** The [xBestI
2ecb0 6e 64 65 78 5d 20 6d 65 74 68 6f 64 20 6d 75 73 ndex] method mus
2ecc0 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61 69 t fill aConstrai
2ecd0 6e 74 55 73 61 67 65 5b 5d 20 77 69 74 68 20 69 ntUsage[] with i
2ece0 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 nformation.** ab
2ecf0 6f 75 74 20 77 68 61 74 20 70 61 72 61 6d 65 74 out what paramet
2ed00 65 72 73 20 74 6f 20 70 61 73 73 20 74 6f 20 78 ers to pass to x
2ed10 46 69 6c 74 65 72 2e 20 20 49 66 20 61 72 67 76 Filter. If argv
2ed20 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 Index>0 then.**
2ed30 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 the right-hand s
2ed40 69 64 65 20 6f 66 20 74 68 65 20 63 6f 72 72 65 ide of the corre
2ed50 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72 sponding aConstr
2ed60 61 69 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75 61 aint[] is evalua
2ed70 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d ted.** and becom
2ed80 65 73 20 74 68 65 20 61 72 67 76 49 6e 64 65 78 es the argvIndex
2ed90 2d 74 68 20 65 6e 74 72 79 20 69 6e 20 61 72 67 -th entry in arg
2eda0 76 2e 20 20 49 66 20 61 43 6f 6e 73 74 72 61 69 v. If aConstrai
2edb0 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a ntUsage[].omit.*
2edc0 2a 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 * is true, then
2edd0 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 the constraint i
2ede0 73 20 61 73 73 75 6d 65 64 20 74 6f 20 62 65 20 s assumed to be
2edf0 66 75 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 fully handled by
2ee00 20 74 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 the.** virtual
2ee10 74 61 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 table and is not
2ee20 20 63 68 65 63 6b 65 64 20 61 67 61 69 6e 20 62 checked again b
2ee30 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 y SQLite..**.**
2ee40 54 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 The idxNum and i
2ee50 64 78 50 74 72 20 76 61 6c 75 65 73 20 61 72 65 dxPtr values are
2ee60 20 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61 recorded and pa
2ee70 73 73 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a ssed into the.**
2ee80 20 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f [xFilter] metho
2ee90 64 2e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 d..** [sqlite3_f
2eea0 72 65 65 28 29 5d 20 69 73 20 75 73 65 64 20 74 ree()] is used t
2eeb0 6f 20 66 72 65 65 20 69 64 78 50 74 72 20 69 66 o free idxPtr if
2eec0 20 61 6e 64 20 6f 6e 6c 79 20 69 66 66 0a 2a 2a and only iff.**
2eed0 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50 74 needToFreeIdxPt
2eee0 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a r is true..**.**
2eef0 20 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 The orderByCons
2ef00 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20 umed means that
2ef10 6f 75 74 70 75 74 20 66 72 6f 6d 20 5b 78 46 69 output from [xFi
2ef20 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69 lter]/[xNext] wi
2ef30 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 ll occur in.** t
2ef40 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72 he correct order
2ef50 20 74 6f 20 73 61 74 69 73 66 79 20 74 68 65 20 to satisfy the
2ef60 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 ORDER BY clause
2ef70 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72 so that no separ
2ef80 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 ate.** sorting s
2ef90 74 65 70 20 69 73 20 72 65 71 75 69 72 65 64 2e tep is required.
2efa0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 73 74 69 6d .**.** The estim
2efb0 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69 atedCost value i
2efc0 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 s an estimate of
2efd0 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 the cost of doi
2efe0 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 ng the.** partic
2eff0 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 ular lookup. A
2f000 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 full scan of a t
2f010 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72 able with N entr
2f020 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a ies should have.
2f030 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 ** a cost of N.
2f040 20 41 20 62 69 6e 61 72 79 20 73 65 61 72 63 68 A binary search
2f050 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e of a table of N
2f060 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 entries should
2f070 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f have a.** cost o
2f080 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 f approximately
2f090 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 log(N)..*/.struc
2f0a0 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f t sqlite3_index_
2f0b0 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 info {. /* Inpu
2f0c0 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e ts */. int nCon
2f0d0 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 straint;
2f0e0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 /* Number of
2f0f0 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 entries in aCons
2f100 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 traint */. stru
2f110 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 ct sqlite3_index
2f120 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 _constraint {.
2f130 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 int iColumn;
2f140 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
2f150 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 Column on left-h
2f160 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 and side of cons
2f170 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 traint */. u
2f180 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b nsigned char op;
2f190 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 /* Cons
2f1a0 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 traint operator
2f1b0 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 */. unsigned
2f1c0 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 char usable;
2f1d0 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 /* True if thi
2f1e0 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 s constraint is
2f1f0 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 usable */. i
2f200 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 nt iTermOffset;
2f210 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 /* Used
2f220 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 internally - xB
2f230 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 estIndex should
2f240 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 ignore */. } *a
2f250 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 Constraint;
2f260 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 /* Table
2f270 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 of WHERE clause
2f280 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 constraints */.
2f290 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 int nOrderBy;
2f2a0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e /* N
2f2b0 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 umber of terms i
2f2c0 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 n the ORDER BY c
2f2d0 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 lause */. struc
2f2e0 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f t sqlite3_index_
2f2f0 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69 orderby {. i
2f300 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 nt iColumn;
2f310 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 /* Colu
2f320 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 mn number */.
2f330 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 unsigned char
2f340 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 desc; /* T
2f350 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46 rue for DESC. F
2f360 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f alse for ASC. */
2f370 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 . } *aOrderBy;
2f380 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
2f390 20 54 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c The ORDER BY cl
2f3a0 61 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 ause */. /* Out
2f3b0 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 puts */. struct
2f3c0 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 sqlite3_index_c
2f3d0 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20 onstraint_usage
2f3e0 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e {. int argvIn
2f3f0 64 65 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f dex; /
2f400 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 * if >0, constra
2f410 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 int is part of a
2f420 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a rgv to xFilter *
2f430 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 /. unsigned c
2f440 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f har omit; /
2f450 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 * Do not code a
2f460 74 65 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f test for this co
2f470 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 nstraint */. }
2f480 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 *aConstraintUsag
2f490 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b e;. int idxNum;
2f4a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2f4b0 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74 /* Number used t
2f4c0 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 69 o identify the i
2f4d0 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a ndex */. char *
2f4e0 69 64 78 53 74 72 3b 20 20 20 20 20 20 20 20 20 idxStr;
2f4f0 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 /* String,
2f500 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 possibly obtaine
2f510 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d d from sqlite3_m
2f520 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e alloc */. int n
2f530 65 65 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b eedToFreeIdxStr;
2f540 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64 /* Free id
2f550 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74 xStr using sqlit
2f560 65 33 5f 66 72 65 65 28 29 20 69 66 20 74 72 75 e3_free() if tru
2f570 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 e */. int order
2f580 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 ByConsumed;
2f590 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74 /* True if out
2f5a0 70 75 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f put is already o
2f5b0 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 rdered */. doub
2f5c0 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 le estimatedCost
2f5d0 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 ; /* Estima
2f5e0 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e ted cost of usin
2f5f0 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a g this index */.
2f600 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 };.#define SQLIT
2f610 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 E_INDEX_CONSTRAI
2f620 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69 NT_EQ 2.#defi
2f630 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f ne SQLITE_INDEX_
2f640 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20 CONSTRAINT_GT
2f650 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 4.#define SQLIT
2f660 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 E_INDEX_CONSTRAI
2f670 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69 NT_LE 8.#defi
2f680 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f ne SQLITE_INDEX_
2f690 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 CONSTRAINT_LT
2f6a0 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 16.#define SQLI
2f6b0 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 TE_INDEX_CONSTRA
2f6c0 49 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65 INT_GE 32.#de
2f6d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 fine SQLITE_INDE
2f6e0 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 X_CONSTRAINT_MAT
2f6f0 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 CH 64../*.** CAP
2f700 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 I3REF: Register
2f710 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 A Virtual Table
2f720 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 7b Implementation {
2f730 48 31 38 32 30 30 7d 20 3c 53 32 30 34 30 30 3e H18200} <S20400>
2f740 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c .** EXPERIMENTAL
2f750 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
2f760 69 6e 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 ine is used to r
2f770 65 67 69 73 74 65 72 20 61 20 6e 65 77 20 5b 76 egister a new [v
2f780 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 irtual table mod
2f790 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a 2a 20 4d 6f ule] name..** Mo
2f7a0 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 dule names must
2f7b0 62 65 20 72 65 67 69 73 74 65 72 65 64 20 62 65 be registered be
2f7c0 66 6f 72 65 0a 2a 2a 20 63 72 65 61 74 69 6e 67 fore.** creating
2f7d0 20 61 20 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 a new [virtual
2f7e0 74 61 62 6c 65 5d 20 75 73 69 6e 67 20 74 68 65 table] using the
2f7f0 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 62 65 66 6f module, or befo
2f800 72 65 20 75 73 69 6e 67 20 61 0a 2a 2a 20 70 72 re using a.** pr
2f810 65 65 78 69 73 74 69 6e 67 20 5b 76 69 72 74 75 eexisting [virtu
2f820 61 6c 20 74 61 62 6c 65 5d 20 66 6f 72 20 74 68 al table] for th
2f830 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 e module..**.**
2f840 54 68 65 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 The module name
2f850 69 73 20 72 65 67 69 73 74 65 72 65 64 20 6f 6e is registered on
2f860 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
2f870 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 onnection] speci
2f880 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 fied.** by the f
2f890 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 irst parameter.
2f8a0 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 The name of the
2f8b0 20 6d 6f 64 75 6c 65 20 69 73 20 67 69 76 65 6e module is given
2f8c0 20 62 79 20 74 68 65 20 0a 2a 2a 20 73 65 63 6f by the .** seco
2f8d0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 nd parameter. T
2f8e0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
2f8f0 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 er is a pointer
2f900 74 6f 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d to.** the implem
2f910 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 entation of the
2f920 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d [virtual table m
2f930 6f 64 75 6c 65 5d 2e 20 20 20 54 68 65 20 66 6f odule]. The fo
2f940 75 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 urth.** paramete
2f950 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 r is an arbitrar
2f960 79 20 63 6c 69 65 6e 74 20 64 61 74 61 20 70 6f y client data po
2f970 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61 inter that is pa
2f980 73 73 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a 20 ssed through.**
2f990 69 6e 74 6f 20 74 68 65 20 5b 78 43 72 65 61 74 into the [xCreat
2f9a0 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 e] and [xConnect
2f9b0 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 74 68 65 ] methods of the
2f9c0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d virtual table m
2f9d0 6f 64 75 6c 65 0a 2a 2a 20 77 68 65 6e 20 61 20 odule.** when a
2f9e0 6e 65 77 20 76 69 72 74 75 61 6c 20 74 61 62 6c new virtual tabl
2f9f0 65 20 69 73 20 62 65 20 62 65 69 6e 67 20 63 72 e is be being cr
2fa00 65 61 74 65 64 20 6f 72 20 72 65 69 6e 69 74 69 eated or reiniti
2fa10 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 alized..**.** Th
2fa20 69 73 20 69 6e 74 65 72 66 61 63 65 20 68 61 73 is interface has
2fa30 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d exactly the sam
2fa40 65 20 65 66 66 65 63 74 20 61 73 20 63 61 6c 6c e effect as call
2fa50 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
2fa60 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 create_module_v2
2fa70 28 29 5d 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 ()] with a NULL
2fa80 63 6c 69 65 6e 74 20 64 61 74 61 20 64 65 73 74 client data dest
2fa90 72 75 63 74 6f 72 2e 0a 2a 2f 0a 53 51 4c 49 54 ructor..*/.SQLIT
2faa0 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 E_EXPERIMENTAL i
2fab0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 nt sqlite3_creat
2fac0 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 e_module(. sqli
2fad0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
2fae0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 /* SQLite
2faf0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 connection to r
2fb00 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 egister module w
2fb10 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 ith */. const c
2fb20 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 har *zName,
2fb30 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 /* Name of t
2fb40 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 he module */. c
2fb50 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 onst sqlite3_mod
2fb60 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 ule *p, /* Met
2fb70 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 hods for the mod
2fb80 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 ule */. void *p
2fb90 43 6c 69 65 6e 74 44 61 74 61 20 20 20 20 20 20 ClientData
2fba0 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 /* Client da
2fbb0 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 ta for xCreate/x
2fbc0 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a 2f Connect */.);../
2fbd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
2fbe0 65 67 69 73 74 65 72 20 41 20 56 69 72 74 75 61 egister A Virtua
2fbf0 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e l Table Implemen
2fc00 74 61 74 69 6f 6e 20 7b 48 31 38 32 31 30 7d 20 tation {H18210}
2fc10 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 <S20400>.** EXPE
2fc20 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 RIMENTAL.**.** T
2fc30 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 his routine is i
2fc40 64 65 6e 74 69 63 61 6c 20 74 6f 20 74 68 65 20 dentical to the
2fc50 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
2fc60 6d 6f 64 75 6c 65 28 29 5d 20 6d 65 74 68 6f 64 module()] method
2fc70 2c 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 ,.** except that
2fc80 20 69 74 20 68 61 73 20 61 6e 20 65 78 74 72 61 it has an extra
2fc90 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 70 parameter to sp
2fca0 65 63 69 66 79 20 0a 2a 2a 20 61 20 64 65 73 74 ecify .** a dest
2fcb0 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 ructor function
2fcc0 66 6f 72 20 74 68 65 20 63 6c 69 65 6e 74 20 64 for the client d
2fcd0 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 20 53 51 ata pointer. SQ
2fce0 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 69 6e 76 Lite will.** inv
2fcf0 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 oke the destruct
2fd00 6f 72 20 66 75 6e 63 74 69 6f 6e 20 28 69 66 20 or function (if
2fd10 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 it is not NULL)
2fd20 77 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 6e when SQLite.** n
2fd30 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 73 20 74 o longer needs t
2fd40 68 65 20 70 43 6c 69 65 6e 74 44 61 74 61 20 70 he pClientData p
2fd50 6f 69 6e 74 65 72 2e 20 20 0a 2a 2f 0a 53 51 4c ointer. .*/.SQL
2fd60 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c ITE_EXPERIMENTAL
2fd70 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 int sqlite3_cre
2fd80 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 ate_module_v2(.
2fd90 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
2fda0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 /* S
2fdb0 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e QLite connection
2fdc0 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 to register mod
2fdd0 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f ule with */. co
2fde0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
2fdf0 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 /* Name
2fe00 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a of the module *
2fe10 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 /. const sqlite
2fe20 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 3_module *p, /
2fe30 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 * Methods for th
2fe40 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f e module */. vo
2fe50 69 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 2c id *pClientData,
2fe60 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 /* Clie
2fe70 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 nt data for xCre
2fe80 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a ate/xConnect */.
2fe90 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 void(*xDestroy
2fea0 29 28 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 )(void*) /*
2feb0 4d 6f 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f Module destructo
2fec0 72 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b r function */.);
2fed0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2fee0 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 : Virtual Table
2fef0 49 6e 73 74 61 6e 63 65 20 4f 62 6a 65 63 74 20 Instance Object
2ff00 7b 48 31 38 30 31 30 7d 20 3c 53 32 30 34 30 30 {H18010} <S20400
2ff10 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 >.** KEYWORDS: s
2ff20 71 6c 69 74 65 33 5f 76 74 61 62 0a 2a 2a 20 45 qlite3_vtab.** E
2ff30 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a XPERIMENTAL.**.*
2ff40 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c * Every [virtual
2ff50 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 table module] i
2ff60 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 mplementation us
2ff70 65 73 20 61 20 73 75 62 63 6c 61 73 73 0a 2a 2a es a subclass.**
2ff80 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e of the followin
2ff90 67 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 64 g structure to d
2ffa0 65 73 63 72 69 62 65 20 61 20 70 61 72 74 69 63 escribe a partic
2ffb0 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 0a 2a 2a ular instance.**
2ffc0 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c of the [virtual
2ffd0 20 74 61 62 6c 65 5d 2e 20 20 45 61 63 68 20 73 table]. Each s
2ffe0 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 ubclass will.**
2fff0 62 65 20 74 61 69 6c 6f 72 65 64 20 74 6f 20 74 be tailored to t
30000 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 he specific need
30010 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 s of the module
30020 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a implementation..
30030 2a 2a 20 54 68 65 20 70 75 72 70 6f 73 65 20 6f ** The purpose o
30040 66 20 74 68 69 73 20 73 75 70 65 72 63 6c 61 73 f this superclas
30050 73 20 69 73 20 74 6f 20 64 65 66 69 6e 65 20 63 s is to define c
30060 65 72 74 61 69 6e 20 66 69 65 6c 64 73 20 74 68 ertain fields th
30070 61 74 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e at are.** common
30080 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 to all module i
30090 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a mplementations..
300a0 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 **.** Virtual ta
300b0 62 6c 65 73 20 6d 65 74 68 6f 64 73 20 63 61 6e bles methods can
300c0 20 73 65 74 20 61 6e 20 65 72 72 6f 72 20 6d 65 set an error me
300d0 73 73 61 67 65 20 62 79 20 61 73 73 69 67 6e 69 ssage by assigni
300e0 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f ng a.** string o
300f0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
30100 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d lite3_mprintf()]
30110 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54 68 to zErrMsg. Th
30120 65 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a e method should.
30130 2a 2a 20 74 61 6b 65 20 63 61 72 65 20 74 68 61 ** take care tha
30140 74 20 61 6e 79 20 70 72 69 6f 72 20 73 74 72 69 t any prior stri
30150 6e 67 20 69 73 20 66 72 65 65 64 20 62 79 20 61 ng is freed by a
30160 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
30170 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 70 72 69 3_free()].** pri
30180 6f 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 or to assigning
30190 61 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20 a new string to
301a0 7a 45 72 72 4d 73 67 2e 20 20 41 66 74 65 72 20 zErrMsg. After
301b0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 the error messag
301c0 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65 e.** is delivere
301d0 64 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65 d up to the clie
301e0 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 nt application,
301f0 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 the string will
30200 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 be automatically
30210 0a 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c .** freed by sql
30220 69 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20 ite3_free() and
30230 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c the zErrMsg fiel
30240 64 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 d will be zeroed
30250 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 ..*/.struct sqli
30260 74 65 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e te3_vtab {. con
30270 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c st sqlite3_modul
30280 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 e *pModule; /*
30290 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74 The module for t
302a0 68 69 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c his virtual tabl
302b0 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b e */. int nRef;
302c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
302d0 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69 /* Used i
302e0 6e 74 65 72 6e 61 6c 6c 79 20 2a 2f 0a 20 20 63 nternally */. c
302f0 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20 har *zErrMsg;
30300 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
30310 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 67 65 20 * Error message
30320 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 from sqlite3_mpr
30330 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 intf() */. /* V
30340 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 irtual table imp
30350 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c lementations wil
30360 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 l typically add
30370 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 additional field
30380 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 s */.};../*.** C
30390 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c API3REF: Virtual
303a0 20 54 61 62 6c 65 20 43 75 72 73 6f 72 20 4f 62 Table Cursor Ob
303b0 6a 65 63 74 20 20 7b 48 31 38 30 32 30 7d 20 3c ject {H18020} <
303c0 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f S20400>.** KEYWO
303d0 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 RDS: sqlite3_vta
303e0 62 5f 63 75 72 73 6f 72 20 7b 76 69 72 74 75 61 b_cursor {virtua
303f0 6c 20 74 61 62 6c 65 20 63 75 72 73 6f 72 7d 0a l table cursor}.
30400 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a ** EXPERIMENTAL.
30410 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 **.** Every [vir
30420 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c tual table modul
30430 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f e] implementatio
30440 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 n uses a subclas
30450 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c s of the.** foll
30460 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 20 owing structure
30470 74 6f 20 64 65 73 63 72 69 62 65 20 63 75 72 73 to describe curs
30480 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74 20 69 ors that point i
30490 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 76 69 72 74 nto the.** [virt
304a0 75 61 6c 20 74 61 62 6c 65 5d 20 61 6e 64 20 61 ual table] and a
304b0 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f re used.** to lo
304c0 6f 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 76 op through the v
304d0 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 irtual table. C
304e0 75 72 73 6f 72 73 20 61 72 65 20 63 72 65 61 74 ursors are creat
304f0 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 ed using the.**
30500 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e [sqlite3_module.
30510 78 4f 70 65 6e 20 7c 20 78 4f 70 65 6e 5d 20 6d xOpen | xOpen] m
30520 65 74 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 ethod of the mod
30530 75 6c 65 20 61 6e 64 20 61 72 65 20 64 65 73 74 ule and are dest
30540 72 6f 79 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 royed.** by the
30550 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e [sqlite3_module.
30560 78 43 6c 6f 73 65 20 7c 20 78 43 6c 6f 73 65 5d xClose | xClose]
30570 20 6d 65 74 68 6f 64 2e 20 20 43 75 73 73 6f 72 method. Cussor
30580 73 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 62 79 s are used.** by
30590 20 74 68 65 20 5b 78 46 69 6c 74 65 72 5d 2c 20 the [xFilter],
305a0 5b 78 4e 65 78 74 5d 2c 20 5b 78 45 6f 66 5d 2c [xNext], [xEof],
305b0 20 5b 78 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64 20 [xColumn], and
305c0 5b 78 52 6f 77 69 64 5d 20 6d 65 74 68 6f 64 73 [xRowid] methods
305d0 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c .** of the modul
305e0 65 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 e. Each module
305f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 implementation w
30600 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 ill define.** th
30610 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63 e content of a c
30620 75 72 73 6f 72 20 73 74 72 75 63 74 75 72 65 20 ursor structure
30630 74 6f 20 73 75 69 74 20 69 74 73 20 6f 77 6e 20 to suit its own
30640 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 needs..**.** Thi
30650 73 20 73 75 70 65 72 63 6c 61 73 73 20 65 78 69 s superclass exi
30660 73 74 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 sts in order to
30670 64 65 66 69 6e 65 20 66 69 65 6c 64 73 20 6f 66 define fields of
30680 20 74 68 65 20 63 75 72 73 6f 72 20 74 68 61 74 the cursor that
30690 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 .** are common t
306a0 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 o all implementa
306b0 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 tions..*/.struct
306c0 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 sqlite3_vtab_cu
306d0 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65 33 rsor {. sqlite3
306e0 5f 76 74 61 62 20 2a 70 56 74 61 62 3b 20 20 20 _vtab *pVtab;
306f0 20 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 /* Virtual ta
30700 62 6c 65 20 6f 66 20 74 68 69 73 20 63 75 72 73 ble of this curs
30710 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 or */. /* Virtu
30720 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 al table impleme
30730 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 ntations will ty
30740 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 pically add addi
30750 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f tional fields */
30760 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .};../*.** CAPI3
30770 52 45 46 3a 20 44 65 63 6c 61 72 65 20 54 68 65 REF: Declare The
30780 20 53 63 68 65 6d 61 20 4f 66 20 41 20 56 69 72 Schema Of A Vir
30790 74 75 61 6c 20 54 61 62 6c 65 20 7b 48 31 38 32 tual Table {H182
307a0 38 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 80} <S20400>.**
307b0 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a EXPERIMENTAL.**.
307c0 2a 2a 20 54 68 65 20 5b 78 43 72 65 61 74 65 5d ** The [xCreate]
307d0 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 and [xConnect]
307e0 6d 65 74 68 6f 64 73 20 6f 66 20 61 0a 2a 2a 20 methods of a.**
307f0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d [virtual table m
30800 6f 64 75 6c 65 5d 20 63 61 6c 6c 20 74 68 69 73 odule] call this
30810 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f interface.** to
30820 20 64 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72 declare the for
30830 6d 61 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61 mat (the names a
30840 6e 64 20 64 61 74 61 74 79 70 65 73 20 6f 66 20 nd datatypes of
30850 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a the columns) of.
30860 2a 2a 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 ** the virtual t
30870 61 62 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65 ables they imple
30880 6d 65 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f ment..*/.SQLITE_
30890 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 EXPERIMENTAL int
308a0 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 sqlite3_declare
308b0 5f 76 74 61 62 28 73 71 6c 69 74 65 33 2a 2c 20 _vtab(sqlite3*,
308c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 51 4c const char *zSQL
308d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
308e0 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20 41 20 46 EF: Overload A F
308f0 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41 20 56 69 unction For A Vi
30900 72 74 75 61 6c 20 54 61 62 6c 65 20 7b 48 31 38 rtual Table {H18
30910 33 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 300} <S20400>.**
30920 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a EXPERIMENTAL.**
30930 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c .** Virtual tabl
30940 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65 20 61 es can provide a
30950 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70 6c 65 lternative imple
30960 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66 75 mentations of fu
30970 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67 nctions.** using
30980 20 74 68 65 20 5b 78 46 69 6e 64 46 75 6e 63 74 the [xFindFunct
30990 69 6f 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 ion] method of t
309a0 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c he [virtual tabl
309b0 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 0a 2a 2a 20 e module]. .**
309c0 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 But global versi
309d0 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 66 75 6e ons of those fun
309e0 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 ctions.** must e
309f0 78 69 73 74 20 69 6e 20 6f 72 64 65 72 20 74 6f xist in order to
30a00 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a be overloaded..
30a10 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 6d **.** This API m
30a20 61 6b 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62 akes sure a glob
30a30 61 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 al version of a
30a40 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 function with a
30a50 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 particular.** na
30a60 6d 65 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 me and number of
30a70 20 70 61 72 61 6d 65 74 65 72 73 20 65 78 69 73 parameters exis
30a80 74 73 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20 ts. If no such
30a90 66 75 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a function exists.
30aa0 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20 41 ** before this A
30ab0 50 49 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 PI is called, a
30ac0 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 new function is
30ad0 63 72 65 61 74 65 64 2e 20 20 54 68 65 20 69 6d created. The im
30ae0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 plementation.**
30af0 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 of the new funct
30b00 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65 ion always cause
30b10 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 s an exception t
30b20 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f o be thrown. So
30b30 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63 .** the new func
30b40 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 tion is not good
30b50 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79 for anything by
30b60 20 69 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e itself. Its on
30b70 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 ly.** purpose is
30b80 20 74 6f 20 62 65 20 61 20 70 6c 61 63 65 68 6f to be a placeho
30b90 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68 lder function th
30ba0 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f at can be overlo
30bb0 61 64 65 64 0a 2a 2a 20 62 79 20 61 20 5b 76 69 aded.** by a [vi
30bc0 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f rtual table]..*/
30bd0 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 .SQLITE_EXPERIME
30be0 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 NTAL int sqlite3
30bf0 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 _overload_functi
30c00 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e on(sqlite3*, con
30c10 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 st char *zFuncNa
30c20 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a me, int nArg);..
30c30 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 /*.** The interf
30c40 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 ace to the virtu
30c50 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 al-table mechani
30c60 73 6d 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65 sm defined above
30c70 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 (back up.** to
30c80 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b a comment remark
30c90 61 62 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 ably similar to
30ca0 74 68 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72 this one) is cur
30cb0 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 rently considere
30cc0 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 d.** to be exper
30cd0 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e imental. The in
30ce0 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 terface might ch
30cf0 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 ange in incompat
30d00 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 ible ways..** If
30d10 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c this is a probl
30d20 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e em for you, do n
30d30 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 ot use the inter
30d40 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d face at this tim
30d50 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 e..**.** When th
30d60 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 e virtual-table
30d70 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c mechanism stabil
30d80 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 izes, we will de
30d90 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 clare the.** int
30da0 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 erface fixed, su
30db0 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e pport it indefin
30dc0 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 itely, and remov
30dd0 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a e this comment..
30de0 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 **.****** EXPERI
30df0 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 MENTAL - subject
30e00 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f to change witho
30e10 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a ut notice ******
30e20 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a ********.*/../*.
30e30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 20 48 ** CAPI3REF: A H
30e40 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e andle To An Open
30e50 20 42 4c 4f 42 20 7b 48 31 37 38 30 30 7d 20 3c BLOB {H17800} <
30e60 53 33 30 32 33 30 3e 0a 2a 2a 20 4b 45 59 57 4f S30230>.** KEYWO
30e70 52 44 53 3a 20 7b 42 4c 4f 42 20 68 61 6e 64 6c RDS: {BLOB handl
30e80 65 7d 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 e} {BLOB handles
30e90 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 }.**.** An insta
30ea0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 nce of this obje
30eb0 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e ct represents an
30ec0 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 68 open BLOB on wh
30ed0 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ich.** [sqlite3_
30ee0 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 blob_open | incr
30ef0 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f emental BLOB I/O
30f00 5d 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d ] can be perform
30f10 65 64 2e 0a 2a 2a 20 4f 62 6a 65 63 74 73 20 6f ed..** Objects o
30f20 66 20 74 68 69 73 20 74 79 70 65 20 61 72 65 20 f this type are
30f30 63 72 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 created by [sqli
30f40 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d te3_blob_open()]
30f50 0a 2a 2a 20 61 6e 64 20 64 65 73 74 72 6f 79 65 .** and destroye
30f60 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c d by [sqlite3_bl
30f70 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 ob_close()]..**
30f80 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f The [sqlite3_blo
30f90 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 b_read()] and [s
30fa0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 qlite3_blob_writ
30fb0 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a e()] interfaces.
30fc0 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 ** can be used t
30fd0 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 o read or write
30fe0 73 6d 61 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e small subsection
30ff0 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e 0a 2a s of the BLOB..*
31000 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 * The [sqlite3_b
31010 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 lob_bytes()] int
31020 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 erface returns t
31030 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42 he size of the B
31040 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f LOB in bytes..*/
31050 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
31060 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c sqlite3_blob sql
31070 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a ite3_blob;../*.*
31080 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e * CAPI3REF: Open
31090 20 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72 A BLOB For Incr
310a0 65 6d 65 6e 74 61 6c 20 49 2f 4f 20 7b 48 31 37 emental I/O {H17
310b0 38 31 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 810} <S30230>.**
310c0 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 .** This interfa
310d0 63 65 73 20 6f 70 65 6e 73 20 61 20 5b 42 4c 4f ces opens a [BLO
310e0 42 20 68 61 6e 64 6c 65 20 7c 20 68 61 6e 64 6c B handle | handl
310f0 65 5d 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 6c e] to the BLOB l
31100 6f 63 61 74 65 64 0a 2a 2a 20 69 6e 20 72 6f 77 ocated.** in row
31110 20 69 52 6f 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43 iRow, column zC
31120 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 20 7a 54 61 olumn, table zTa
31130 62 6c 65 20 69 6e 20 64 61 74 61 62 61 73 65 20 ble in database
31140 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65 72 zDb;.** in other
31150 20 77 6f 72 64 73 2c 20 74 68 65 20 73 61 6d 65 words, the same
31160 20 42 4c 4f 42 20 74 68 61 74 20 77 6f 75 6c 64 BLOB that would
31170 20 62 65 20 73 65 6c 65 63 74 65 64 20 62 79 3a be selected by:
31180 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 .**.** <pre>.**
31190 20 20 20 20 53 45 4c 45 43 54 20 7a 43 6f 6c 75 SELECT zColu
311a0 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 mn FROM zDb.zTab
311b0 6c 65 20 57 48 45 52 45 20 5b 72 6f 77 69 64 5d le WHERE [rowid]
311c0 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 = iRow;.** </pr
311d0 65 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 e> {END}.**.** I
311e0 66 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 f the flags para
311f0 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 meter is non-zer
31200 6f 2c 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 o, then the BLOB
31210 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 is opened for r
31220 65 61 64 0a 2a 2a 20 61 6e 64 20 77 72 69 74 65 ead.** and write
31230 20 61 63 63 65 73 73 2e 20 49 66 20 69 74 20 69 access. If it i
31240 73 20 7a 65 72 6f 2c 20 74 68 65 20 42 4c 4f 42 s zero, the BLOB
31250 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 is opened for r
31260 65 61 64 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a ead access..**.*
31270 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 * Note that the
31280 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 database name is
31290 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 6e 61 6d not the filenam
312a0 65 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 0a e that contains.
312b0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ** the database
312c0 62 75 74 20 72 61 74 68 65 72 20 74 68 65 20 73 but rather the s
312d0 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 6f 66 20 ymbolic name of
312e0 74 68 65 20 64 61 74 61 62 61 73 65 20 74 68 61 the database tha
312f0 74 0a 2a 2a 20 69 73 20 61 73 73 69 67 6e 65 64 t.** is assigned
31300 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 when the databa
31310 73 65 20 69 73 20 63 6f 6e 6e 65 63 74 65 64 20 se is connected
31320 75 73 69 6e 67 20 5b 41 54 54 41 43 48 5d 2e 0a using [ATTACH]..
31330 2a 2a 20 46 6f 72 20 74 68 65 20 6d 61 69 6e 20 ** For the main
31340 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 74 database file, t
31350 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 he database name
31360 20 69 73 20 22 6d 61 69 6e 22 2e 0a 2a 2a 20 46 is "main"..** F
31370 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 2c 20 or TEMP tables,
31380 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d the database nam
31390 65 20 69 73 20 22 74 65 6d 70 22 2e 0a 2a 2a 0a e is "temp"..**.
313a0 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b ** On success, [
313b0 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 SQLITE_OK] is re
313c0 74 75 72 6e 65 64 20 61 6e 64 20 74 68 65 20 6e turned and the n
313d0 65 77 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d ew [BLOB handle]
313e0 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 74 is written.** t
313f0 6f 20 2a 70 70 42 6c 6f 62 2e 20 4f 74 68 65 72 o *ppBlob. Other
31400 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 wise an [error c
31410 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 ode] is returned
31420 20 61 6e 64 20 2a 70 70 42 6c 6f 62 20 69 73 20 and *ppBlob is
31430 73 65 74 0a 2a 2a 20 74 6f 20 62 65 20 61 20 6e set.** to be a n
31440 75 6c 6c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 ull pointer..**
31450 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 This function se
31460 74 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 ts the [database
31470 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 72 connection] err
31480 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 or code and mess
31490 61 67 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c age.** accessibl
314a0 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 e via [sqlite3_e
314b0 72 72 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 rrcode()] and [s
314c0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d qlite3_errmsg()]
314d0 20 61 6e 64 20 72 65 6c 61 74 65 64 0a 2a 2a 20 and related.**
314e0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 4e 6f 74 65 functions. Note
314f0 20 74 68 61 74 20 74 68 65 20 2a 70 70 42 6c 6f that the *ppBlo
31500 62 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 6c b variable is al
31510 77 61 79 73 20 69 6e 69 74 69 61 6c 69 7a 65 64 ways initialized
31520 20 69 6e 20 61 0a 2a 2a 20 77 61 79 20 74 68 61 in a.** way tha
31530 74 20 6d 61 6b 65 73 20 69 74 20 73 61 66 65 20 t makes it safe
31540 74 6f 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 to invoke [sqlit
31550 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d e3_blob_close()]
31560 20 6f 6e 20 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72 on *ppBlob.** r
31570 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 egardless of the
31580 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c success or fail
31590 75 72 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 ure of this rout
315a0 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ine..**.** If th
315b0 65 20 72 6f 77 20 74 68 61 74 20 61 20 42 4c 4f e row that a BLO
315c0 42 20 68 61 6e 64 6c 65 20 70 6f 69 6e 74 73 20 B handle points
315d0 74 6f 20 69 73 20 6d 6f 64 69 66 69 65 64 20 62 to is modified b
315e0 79 20 61 6e 0a 2a 2a 20 5b 55 50 44 41 54 45 5d y an.** [UPDATE]
315f0 2c 20 5b 44 45 4c 45 54 45 5d 2c 20 6f 72 20 62 , [DELETE], or b
31600 79 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 y [ON CONFLICT]
31610 73 69 64 65 2d 65 66 66 65 63 74 73 0a 2a 2a 20 side-effects.**
31620 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 68 61 then the BLOB ha
31630 6e 64 6c 65 20 69 73 20 6d 61 72 6b 65 64 20 61 ndle is marked a
31640 73 20 22 65 78 70 69 72 65 64 22 2e 0a 2a 2a 20 s "expired"..**
31650 54 68 69 73 20 69 73 20 74 72 75 65 20 69 66 20 This is true if
31660 61 6e 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 any column of th
31670 65 20 72 6f 77 20 69 73 20 63 68 61 6e 67 65 64 e row is changed
31680 2c 20 65 76 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a , even a column.
31690 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 74 68 ** other than th
316a0 65 20 6f 6e 65 20 74 68 65 20 42 4c 4f 42 20 68 e one the BLOB h
316b0 61 6e 64 6c 65 20 69 73 20 6f 70 65 6e 20 6f 6e andle is open on
316c0 2e 0a 2a 2a 20 43 61 6c 6c 73 20 74 6f 20 5b 73 ..** Calls to [s
316d0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 qlite3_blob_read
316e0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
316f0 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 66 _blob_write()] f
31700 6f 72 0a 2a 2a 20 61 20 65 78 70 69 72 65 64 20 or.** a expired
31710 42 4c 4f 42 20 68 61 6e 64 6c 65 20 66 61 69 6c BLOB handle fail
31720 20 77 69 74 68 20 61 6e 20 72 65 74 75 72 6e 20 with an return
31730 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f code of [SQLITE_
31740 41 42 4f 52 54 5d 2e 0a 2a 2a 20 43 68 61 6e 67 ABORT]..** Chang
31750 65 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 es written into
31760 61 20 42 4c 4f 42 20 70 72 69 6f 72 20 74 6f 20 a BLOB prior to
31770 74 68 65 20 42 4c 4f 42 20 65 78 70 69 72 69 6e the BLOB expirin
31780 67 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f 6c g are not.** rol
31790 6c 62 61 63 6b 20 62 79 20 74 68 65 20 65 78 70 lback by the exp
317a0 69 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 42 iration of the B
317b0 4c 4f 42 2e 20 20 53 75 63 68 20 63 68 61 6e 67 LOB. Such chang
317c0 65 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c es will eventual
317d0 6c 79 0a 2a 2a 20 63 6f 6d 6d 69 74 20 69 66 20 ly.** commit if
317e0 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 the transaction
317f0 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d continues to com
31800 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 pletion..**.** U
31810 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f se the [sqlite3_
31820 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e blob_bytes()] in
31830 74 65 72 66 61 63 65 20 74 6f 20 64 65 74 65 72 terface to deter
31840 6d 69 6e 65 20 74 68 65 20 73 69 7a 65 20 6f 66 mine the size of
31850 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 65 64 20 62 .** the opened b
31860 6c 6f 62 2e 20 20 54 68 65 20 73 69 7a 65 20 6f lob. The size o
31870 66 20 61 20 62 6c 6f 62 20 6d 61 79 20 6e 6f 74 f a blob may not
31880 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 74 be changed by t
31890 68 69 73 0a 2a 2a 20 75 6e 64 65 72 66 61 63 65 his.** underface
318a0 2e 20 20 55 73 65 20 74 68 65 20 5b 55 50 44 41 . Use the [UPDA
318b0 54 45 5d 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 TE] SQL command
318c0 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 73 69 to change the si
318d0 7a 65 20 6f 66 20 61 0a 2a 2a 20 62 6c 6f 62 2e ze of a.** blob.
318e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 .**.** The [sqli
318f0 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f te3_bind_zeroblo
31900 62 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 b()] and [sqlite
31910 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 3_result_zeroblo
31920 62 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a b()] interfaces.
31930 2a 2a 20 61 6e 64 20 74 68 65 20 62 75 69 6c 74 ** and the built
31940 2d 69 6e 20 5b 7a 65 72 6f 62 6c 6f 62 5d 20 53 -in [zeroblob] S
31950 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 QL function can
31960 62 65 20 75 73 65 64 2c 20 69 66 20 64 65 73 69 be used, if desi
31970 72 65 64 2c 0a 2a 2a 20 74 6f 20 63 72 65 61 74 red,.** to creat
31980 65 20 61 6e 20 65 6d 70 74 79 2c 20 7a 65 72 6f e an empty, zero
31990 2d 66 69 6c 6c 65 64 20 62 6c 6f 62 20 69 6e 20 -filled blob in
319a0 77 68 69 63 68 20 74 6f 20 72 65 61 64 20 6f 72 which to read or
319b0 20 77 72 69 74 65 20 75 73 69 6e 67 0a 2a 2a 20 write using.**
319c0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a this interface..
319d0 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 61 **.** To avoid a
319e0 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 2c 20 resource leak,
319f0 65 76 65 72 79 20 6f 70 65 6e 20 5b 42 4c 4f 42 every open [BLOB
31a00 20 68 61 6e 64 6c 65 5d 20 73 68 6f 75 6c 64 20 handle] should
31a10 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 62 65 eventually.** be
31a20 20 72 65 6c 65 61 73 65 64 20 62 79 20 61 20 63 released by a c
31a30 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
31a40 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a blob_close()]..*
31a50 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
31a60 73 3a 0a 2a 2a 20 5b 48 31 37 38 31 33 5d 20 5b s:.** [H17813] [
31a70 48 31 37 38 31 34 5d 20 5b 48 31 37 38 31 36 5d H17814] [H17816]
31a80 20 5b 48 31 37 38 31 39 5d 20 5b 48 31 37 38 32 [H17819] [H1782
31a90 31 5d 20 5b 48 31 37 38 32 34 5d 0a 2a 2f 0a 69 1] [H17824].*/.i
31aa0 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f nt sqlite3_blob_
31ab0 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a open(. sqlite3*
31ac0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a ,. const char *
31ad0 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 zDb,. const cha
31ae0 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e r *zTable,. con
31af0 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e st char *zColumn
31b00 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 ,. sqlite3_int6
31b10 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 4 iRow,. int fl
31b20 61 67 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62 ags,. sqlite3_b
31b30 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a lob **ppBlob.);.
31b40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
31b50 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48 61 Close A BLOB Ha
31b60 6e 64 6c 65 20 7b 48 31 37 38 33 30 7d 20 3c 53 ndle {H17830} <S
31b70 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 30230>.**.** Clo
31b80 73 65 73 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f ses an open [BLO
31b90 42 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a B handle]..**.**
31ba0 20 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f 42 20 Closing a BLOB
31bb0 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20 shall cause the
31bc0 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 current transact
31bd0 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a ion to commit.**
31be0 20 69 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f if there are no
31bf0 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20 6e 6f other BLOBs, no
31c00 20 70 65 6e 64 69 6e 67 20 70 72 65 70 61 72 65 pending prepare
31c10 64 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e d statements, an
31c20 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 d the.** databas
31c30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
31c40 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d in [autocommit m
31c50 6f 64 65 5d 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 ode]..** If any
31c60 77 72 69 74 65 73 20 77 65 72 65 20 6d 61 64 65 writes were made
31c70 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20 74 68 to the BLOB, th
31c80 65 79 20 6d 69 67 68 74 20 62 65 20 68 65 6c 64 ey might be held
31c90 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75 6e 74 in cache.** unt
31ca0 69 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f 70 65 il the close ope
31cb0 72 61 74 69 6f 6e 20 69 66 20 74 68 65 79 20 77 ration if they w
31cc0 69 6c 6c 20 66 69 74 2e 0a 2a 2a 0a 2a 2a 20 43 ill fit..**.** C
31cd0 6c 6f 73 69 6e 67 20 74 68 65 20 42 4c 4f 42 20 losing the BLOB
31ce0 6f 66 74 65 6e 20 66 6f 72 63 65 73 20 74 68 65 often forces the
31cf0 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 75 74 20 changes.** out
31d00 74 6f 20 64 69 73 6b 20 61 6e 64 20 73 6f 20 69 to disk and so i
31d10 66 20 61 6e 79 20 49 2f 4f 20 65 72 72 6f 72 73 f any I/O errors
31d20 20 6f 63 63 75 72 2c 20 74 68 65 79 20 77 69 6c occur, they wil
31d30 6c 20 6c 69 6b 65 6c 79 20 6f 63 63 75 72 0a 2a l likely occur.*
31d40 2a 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 * at the time wh
31d50 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 73 20 63 en the BLOB is c
31d60 6c 6f 73 65 64 2e 20 20 41 6e 79 20 65 72 72 6f losed. Any erro
31d70 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 64 75 rs that occur du
31d80 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73 69 6e 67 20 ring.** closing
31d90 61 72 65 20 72 65 70 6f 72 74 65 64 20 61 73 20 are reported as
31da0 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 a non-zero retur
31db0 6e 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 n value..**.** T
31dc0 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 he BLOB is close
31dd0 64 20 75 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c d unconditionall
31de0 79 2e 20 20 45 76 65 6e 20 69 66 20 74 68 69 73 y. Even if this
31df0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
31e00 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 .** an error cod
31e10 65 2c 20 74 68 65 20 42 4c 4f 42 20 69 73 20 73 e, the BLOB is s
31e20 74 69 6c 6c 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a till closed..**.
31e30 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 ** Calling this
31e40 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 6e routine with a n
31e50 75 6c 6c 20 70 6f 69 6e 74 65 72 20 28 77 68 69 ull pointer (whi
31e60 63 68 20 61 73 20 77 6f 75 6c 64 20 62 65 20 72 ch as would be r
31e70 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 66 61 eturned.** by fa
31e80 69 6c 65 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 iled call to [sq
31e90 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 lite3_blob_open(
31ea0 29 5d 29 20 69 73 20 61 20 68 61 72 6d 6c 65 73 )]) is a harmles
31eb0 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 52 s no-op..**.** R
31ec0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
31ed0 5b 48 31 37 38 33 33 5d 20 5b 48 31 37 38 33 36 [H17833] [H17836
31ee0 5d 20 5b 48 31 37 38 33 39 5d 0a 2a 2f 0a 69 6e ] [H17839].*/.in
31ef0 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 t sqlite3_blob_c
31f00 6c 6f 73 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f lose(sqlite3_blo
31f10 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 b *);../*.** CAP
31f20 49 33 52 45 46 3a 20 52 65 74 75 72 6e 20 54 68 I3REF: Return Th
31f30 65 20 53 69 7a 65 20 4f 66 20 41 6e 20 4f 70 65 e Size Of An Ope
31f40 6e 20 42 4c 4f 42 20 7b 48 31 37 38 34 30 7d 20 n BLOB {H17840}
31f50 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 52 <S30230>.**.** R
31f60 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 eturns the size
31f70 69 6e 20 62 79 74 65 73 20 6f 66 20 74 68 65 20 in bytes of the
31f80 42 4c 4f 42 20 61 63 63 65 73 73 69 62 6c 65 20 BLOB accessible
31f90 76 69 61 20 74 68 65 20 0a 2a 2a 20 73 75 63 63 via the .** succ
31fa0 65 73 73 66 75 6c 6c 79 20 6f 70 65 6e 65 64 20 essfully opened
31fb0 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e [BLOB handle] in
31fc0 20 69 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 its only argume
31fd0 6e 74 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 63 72 nt. The.** incr
31fe0 65 6d 65 6e 74 61 6c 20 62 6c 6f 62 20 49 2f 4f emental blob I/O
31ff0 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 6f 6e routines can on
32000 6c 79 20 72 65 61 64 20 6f 72 20 6f 76 65 72 77 ly read or overw
32010 72 69 74 69 6e 67 20 65 78 69 73 74 69 6e 67 0a riting existing.
32020 2a 2a 20 62 6c 6f 62 20 63 6f 6e 74 65 6e 74 3b ** blob content;
32030 20 74 68 65 79 20 63 61 6e 6e 6f 74 20 63 68 61 they cannot cha
32040 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 nge the size of
32050 61 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 54 68 a blob..**.** Th
32060 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 is routine only
32070 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 works on a [BLOB
32080 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 handle] which h
32090 61 73 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a as been created.
320a0 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73 75 ** by a prior su
320b0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f ccessful call to
320c0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f [sqlite3_blob_o
320d0 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68 pen()] and which
320e0 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e has not.** been
320f0 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 closed by [sqli
32100 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 te3_blob_close()
32110 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20 ]. Passing any
32120 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e other pointer in
32130 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74 .** to this rout
32140 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75 ine results in u
32150 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f ndefined and pro
32160 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c bably undesirabl
32170 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a e behavior..**.*
32180 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
32190 2a 2a 20 5b 48 31 37 38 34 33 5d 0a 2a 2f 0a 69 ** [H17843].*/.i
321a0 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f nt sqlite3_blob_
321b0 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 62 6c bytes(sqlite3_bl
321c0 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ob *);../*.** CA
321d0 50 49 33 52 45 46 3a 20 52 65 61 64 20 44 61 74 PI3REF: Read Dat
321e0 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49 6e a From A BLOB In
321f0 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 48 31 37 crementally {H17
32200 38 35 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 850} <S30230>.**
32210 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f .** This functio
32220 6e 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 61 n is used to rea
32230 64 20 64 61 74 61 20 66 72 6f 6d 20 61 6e 20 6f d data from an o
32240 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 pen [BLOB handle
32250 5d 20 69 6e 74 6f 20 61 0a 2a 2a 20 63 61 6c 6c ] into a.** call
32260 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66 66 er-supplied buff
32270 65 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 20 64 er. N bytes of d
32280 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 69 ata are copied i
32290 6e 74 6f 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 nto buffer Z.**
322a0 66 72 6f 6d 20 74 68 65 20 6f 70 65 6e 20 42 4c from the open BL
322b0 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 OB, starting at
322c0 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a offset iOffset..
322d0 2a 2a 0a 2a 2a 20 49 66 20 6f 66 66 73 65 74 20 **.** If offset
322e0 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 iOffset is less
322f0 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f than N bytes fro
32300 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 m the end of the
32310 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 BLOB,.** [SQLIT
32320 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 E_ERROR] is retu
32330 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 rned and no data
32340 20 69 73 20 72 65 61 64 2e 20 20 49 66 20 4e 20 is read. If N
32350 6f 72 20 69 4f 66 66 73 65 74 20 69 73 0a 2a 2a or iOffset is.**
32360 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c less than zero,
32370 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
32380 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 is returned and
32390 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61 64 2e no data is read.
323a0 0a 2a 2a 20 54 68 65 20 73 69 7a 65 20 6f 66 20 .** The size of
323b0 74 68 65 20 62 6c 6f 62 20 28 61 6e 64 20 68 65 the blob (and he
323c0 6e 63 65 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 nce the maximum
323d0 76 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 value of N+iOffs
323e0 65 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 et).** can be de
323f0 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 termined using t
32400 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 he [sqlite3_blob
32410 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 _bytes()] interf
32420 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 74 ace..**.** An at
32430 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 66 72 tempt to read fr
32440 6f 6d 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42 om an expired [B
32450 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c LOB handle] fail
32460 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 s with an.** err
32470 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 or code of [SQLI
32480 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a TE_ABORT]..**.**
32490 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 53 51 4c On success, SQL
324a0 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e ITE_OK is return
324b0 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 ed..** Otherwise
324c0 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 , an [error code
324d0 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 ] or an [extende
324e0 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 d error code] is
324f0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
32500 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e This routine on
32510 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 ly works on a [B
32520 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 LOB handle] whic
32530 68 20 68 61 73 20 62 65 65 6e 20 63 72 65 61 74 h has been creat
32540 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 ed.** by a prior
32550 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c successful call
32560 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f to [sqlite3_blo
32570 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 b_open()] and wh
32580 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 ich has not.** b
32590 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 een closed by [s
325a0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 qlite3_blob_clos
325b0 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 e()]. Passing a
325c0 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 ny other pointer
325d0 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 in.** to this r
325e0 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20 69 outine results i
325f0 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 n undefined and
32600 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 probably undesir
32610 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a able behavior..*
32620 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
32630 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 sqlite3_blob_wri
32640 74 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 te()]..**.** Req
32650 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
32660 31 37 38 35 33 5d 20 5b 48 31 37 38 35 36 5d 20 17853] [H17856]
32670 5b 48 31 37 38 35 39 5d 20 5b 48 31 37 38 36 32 [H17859] [H17862
32680 5d 20 5b 48 31 37 38 36 33 5d 20 5b 48 31 37 38 ] [H17863] [H178
32690 36 35 5d 20 5b 48 31 37 38 36 38 5d 0a 2a 2f 0a 65] [H17868].*/.
326a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 int sqlite3_blob
326b0 5f 72 65 61 64 28 73 71 6c 69 74 65 33 5f 62 6c _read(sqlite3_bl
326c0 6f 62 20 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20 69 ob *, void *Z, i
326d0 6e 74 20 4e 2c 20 69 6e 74 20 69 4f 66 66 73 65 nt N, int iOffse
326e0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
326f0 52 45 46 3a 20 57 72 69 74 65 20 44 61 74 61 20 REF: Write Data
32700 49 6e 74 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 Into A BLOB Incr
32710 65 6d 65 6e 74 61 6c 6c 79 20 7b 48 31 37 38 37 ementally {H1787
32720 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 0} <S30230>.**.*
32730 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 * This function
32740 69 73 20 75 73 65 64 20 74 6f 20 77 72 69 74 65 is used to write
32750 20 64 61 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70 data into an op
32760 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d en [BLOB handle]
32770 20 66 72 6f 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65 from a.** calle
32780 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 r-supplied buffe
32790 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 20 64 61 r. N bytes of da
327a0 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 66 72 ta are copied fr
327b0 6f 6d 20 74 68 65 20 62 75 66 66 65 72 20 5a 0a om the buffer Z.
327c0 2a 2a 20 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e ** into the open
327d0 20 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 BLOB, starting
327e0 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 at offset iOffse
327f0 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 t..**.** If the
32800 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 70 61 [BLOB handle] pa
32810 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 ssed as the firs
32820 74 20 61 72 67 75 6d 65 6e 74 20 77 61 73 20 6e t argument was n
32830 6f 74 20 6f 70 65 6e 65 64 20 66 6f 72 0a 2a 2a ot opened for.**
32840 20 77 72 69 74 69 6e 67 20 28 74 68 65 20 66 6c writing (the fl
32850 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f ags parameter to
32860 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f [sqlite3_blob_o
32870 70 65 6e 28 29 5d 20 77 61 73 20 7a 65 72 6f 29 pen()] was zero)
32880 2c 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 ,.** this functi
32890 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 on returns [SQLI
328a0 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a TE_READONLY]..**
328b0 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f .** This functio
328c0 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 n may only modif
328d0 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f y the contents o
328e0 66 20 74 68 65 20 42 4c 4f 42 3b 20 69 74 20 69 f the BLOB; it i
328f0 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c s.** not possibl
32900 65 20 74 6f 20 69 6e 63 72 65 61 73 65 20 74 68 e to increase th
32910 65 20 73 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 e size of a BLOB
32920 20 75 73 69 6e 67 20 74 68 69 73 20 41 50 49 2e using this API.
32930 0a 2a 2a 20 49 66 20 6f 66 66 73 65 74 20 69 4f .** If offset iO
32940 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 ffset is less th
32950 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 an N bytes from
32960 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 the end of the B
32970 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f LOB,.** [SQLITE_
32980 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e ERROR] is return
32990 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 ed and no data i
329a0 73 20 77 72 69 74 74 65 6e 2e 20 20 49 66 20 4e s written. If N
329b0 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e is.** less than
329c0 20 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45 52 zero [SQLITE_ER
329d0 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 ROR] is returned
329e0 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 and no data is
329f0 77 72 69 74 74 65 6e 2e 0a 2a 2a 20 54 68 65 20 written..** The
32a00 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 size of the BLOB
32a10 20 28 61 6e 64 20 68 65 6e 63 65 20 74 68 65 20 (and hence the
32a20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 maximum value of
32a30 20 4e 2b 69 4f 66 66 73 65 74 29 0a 2a 2a 20 63 N+iOffset).** c
32a40 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 an be determined
32a50 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 using the [sqli
32a60 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 te3_blob_bytes()
32a70 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a ] interface..**.
32a80 2a 2a 20 41 6e 20 61 74 74 65 6d 70 74 20 74 6f ** An attempt to
32a90 20 77 72 69 74 65 20 74 6f 20 61 6e 20 65 78 70 write to an exp
32aa0 69 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c ired [BLOB handl
32ab0 65 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e e] fails with an
32ac0 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 6f .** error code o
32ad0 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d f [SQLITE_ABORT]
32ae0 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 65 . Writes to the
32af0 20 42 4c 4f 42 20 74 68 61 74 20 6f 63 63 75 72 BLOB that occur
32b00 72 65 64 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 red.** before th
32b10 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 e [BLOB handle]
32b20 65 78 70 69 72 65 64 20 61 72 65 20 6e 6f 74 20 expired are not
32b30 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79 20 74 rolled back by t
32b40 68 65 0a 2a 2a 20 65 78 70 69 72 61 74 69 6f 6e he.** expiration
32b50 20 6f 66 20 74 68 65 20 68 61 6e 64 6c 65 2c 20 of the handle,
32b60 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 though of course
32b70 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20 6d those changes m
32b80 69 67 68 74 0a 2a 2a 20 68 61 76 65 20 62 65 65 ight.** have bee
32b90 6e 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 n overwritten by
32ba0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 the statement t
32bb0 68 61 74 20 65 78 70 69 72 65 64 20 74 68 65 20 hat expired the
32bc0 42 4c 4f 42 20 68 61 6e 64 6c 65 0a 2a 2a 20 6f BLOB handle.** o
32bd0 72 20 62 79 20 6f 74 68 65 72 20 69 6e 64 65 70 r by other indep
32be0 65 6e 64 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 endent statement
32bf0 73 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 s..**.** On succ
32c00 65 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 ess, SQLITE_OK i
32c10 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f s returned..** O
32c20 74 68 65 72 77 69 73 65 2c 20 61 6e 20 20 5b 65 therwise, an [e
32c30 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e rror code] or an
32c40 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 [extended error
32c50 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e code] is return
32c60 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 ed..**.** This r
32c70 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b outine only work
32c80 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e s on a [BLOB han
32c90 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20 62 dle] which has b
32ca0 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 een created.** b
32cb0 79 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 y a prior succes
32cc0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 sful call to [sq
32cd0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 lite3_blob_open(
32ce0 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61 73 )] and which has
32cf0 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f not.** been clo
32d00 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f sed by [sqlite3_
32d10 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 blob_close()].
32d20 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 Passing any othe
32d30 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 r pointer in.**
32d40 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 to this routine
32d50 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 results in undef
32d60 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c ined and probabl
32d70 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 y undesirable be
32d80 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 havior..**.** Se
32d90 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
32da0 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 2e 0a 2a _blob_read()]..*
32db0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
32dc0 73 3a 0a 2a 2a 20 5b 48 31 37 38 37 33 5d 20 5b s:.** [H17873] [
32dd0 48 31 37 38 37 34 5d 20 5b 48 31 37 38 37 35 5d H17874] [H17875]
32de0 20 5b 48 31 37 38 37 36 5d 20 5b 48 31 37 38 37 [H17876] [H1787
32df0 37 5d 20 5b 48 31 37 38 37 39 5d 20 5b 48 31 37 7] [H17879] [H17
32e00 38 38 32 5d 20 5b 48 31 37 38 38 35 5d 0a 2a 2a 882] [H17885].**
32e10 20 5b 48 31 37 38 38 38 5d 0a 2a 2f 0a 69 6e 74 [H17888].*/.int
32e20 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 sqlite3_blob_wr
32e30 69 74 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 ite(sqlite3_blob
32e40 20 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a *, const void *
32e50 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f z, int n, int iO
32e60 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ffset);../*.** C
32e70 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c API3REF: Virtual
32e80 20 46 69 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a File System Obj
32e90 65 63 74 73 20 7b 48 31 31 32 30 30 7d 20 3c 53 ects {H11200} <S
32ea0 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 20 76 20100>.**.** A v
32eb0 69 72 74 75 61 6c 20 66 69 6c 65 73 79 73 74 65 irtual filesyste
32ec0 6d 20 28 56 46 53 29 20 69 73 20 61 6e 20 5b 73 m (VFS) is an [s
32ed0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
32ee0 63 74 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 ct.** that SQLit
32ef0 65 20 75 73 65 73 20 74 6f 20 69 6e 74 65 72 61 e uses to intera
32f00 63 74 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 75 ct.** with the u
32f10 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 nderlying operat
32f20 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 4d 6f 73 ing system. Mos
32f30 74 20 53 51 4c 69 74 65 20 62 75 69 6c 64 73 20 t SQLite builds
32f40 63 6f 6d 65 20 77 69 74 68 20 61 0a 2a 2a 20 73 come with a.** s
32f50 69 6e 67 6c 65 20 64 65 66 61 75 6c 74 20 56 46 ingle default VF
32f60 53 20 74 68 61 74 20 69 73 20 61 70 70 72 6f 70 S that is approp
32f70 72 69 61 74 65 20 66 6f 72 20 74 68 65 20 68 6f riate for the ho
32f80 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 st computer..**
32f90 4e 65 77 20 56 46 53 65 73 20 63 61 6e 20 62 65 New VFSes can be
32fa0 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 registered and
32fb0 65 78 69 73 74 69 6e 67 20 56 46 53 65 73 20 63 existing VFSes c
32fc0 61 6e 20 62 65 20 75 6e 72 65 67 69 73 74 65 72 an be unregister
32fd0 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f ed..** The follo
32fe0 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20 wing interfaces
32ff0 61 72 65 20 70 72 6f 76 69 64 65 64 2e 0a 2a 2a are provided..**
33000 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
33010 76 66 73 5f 66 69 6e 64 28 29 20 69 6e 74 65 72 vfs_find() inter
33020 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 face returns a p
33030 6f 69 6e 74 65 72 20 74 6f 20 61 20 56 46 53 20 ointer to a VFS
33040 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 0a given its name..
33050 2a 2a 20 4e 61 6d 65 73 20 61 72 65 20 63 61 73 ** Names are cas
33060 65 20 73 65 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 e sensitive..**
33070 4e 61 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d 74 Names are zero-t
33080 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 erminated UTF-8
33090 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 49 66 20 74 strings..** If t
330a0 68 65 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 here is no match
330b0 2c 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 , a NULL pointer
330c0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
330d0 20 49 66 20 7a 56 66 73 4e 61 6d 65 20 69 73 20 If zVfsName is
330e0 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 64 65 NULL then the de
330f0 66 61 75 6c 74 20 56 46 53 20 69 73 20 72 65 74 fault VFS is ret
33100 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 urned..**.** New
33110 20 56 46 53 65 73 20 61 72 65 20 72 65 67 69 73 VFSes are regis
33120 74 65 72 65 64 20 77 69 74 68 20 73 71 6c 69 74 tered with sqlit
33130 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 e3_vfs_register(
33140 29 2e 0a 2a 2a 20 45 61 63 68 20 6e 65 77 20 56 )..** Each new V
33150 46 53 20 62 65 63 6f 6d 65 73 20 74 68 65 20 64 FS becomes the d
33160 65 66 61 75 6c 74 20 56 46 53 20 69 66 20 74 68 efault VFS if th
33170 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 e makeDflt flag
33180 69 73 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20 73 is set..** The s
33190 61 6d 65 20 56 46 53 20 63 61 6e 20 62 65 20 72 ame VFS can be r
331a0 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 egistered multip
331b0 6c 65 20 74 69 6d 65 73 20 77 69 74 68 6f 75 74 le times without
331c0 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20 54 6f 20 6d injury..** To m
331d0 61 6b 65 20 61 6e 20 65 78 69 73 74 69 6e 67 20 ake an existing
331e0 56 46 53 20 69 6e 74 6f 20 74 68 65 20 64 65 66 VFS into the def
331f0 61 75 6c 74 20 56 46 53 2c 20 72 65 67 69 73 74 ault VFS, regist
33200 65 72 20 69 74 20 61 67 61 69 6e 0a 2a 2a 20 77 er it again.** w
33210 69 74 68 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 ith the makeDflt
33220 20 66 6c 61 67 20 73 65 74 2e 20 20 49 66 20 74 flag set. If t
33230 77 6f 20 64 69 66 66 65 72 65 6e 74 20 56 46 53 wo different VFS
33240 65 73 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 73 es with the.** s
33250 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 72 65 67 ame name are reg
33260 69 73 74 65 72 65 64 2c 20 74 68 65 20 62 65 68 istered, the beh
33270 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e avior is undefin
33280 65 64 2e 20 20 49 66 20 61 0a 2a 2a 20 56 46 53 ed. If a.** VFS
33290 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 77 is registered w
332a0 69 74 68 20 61 20 6e 61 6d 65 20 74 68 61 74 20 ith a name that
332b0 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d is NULL or an em
332c0 70 74 79 20 73 74 72 69 6e 67 2c 0a 2a 2a 20 74 pty string,.** t
332d0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 hen the behavior
332e0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a is undefined..*
332f0 2a 0a 2a 2a 20 55 6e 72 65 67 69 73 74 65 72 20 *.** Unregister
33300 61 20 56 46 53 20 77 69 74 68 20 74 68 65 20 73 a VFS with the s
33310 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 qlite3_vfs_unreg
33320 69 73 74 65 72 28 29 20 69 6e 74 65 72 66 61 63 ister() interfac
33330 65 2e 0a 2a 2a 20 49 66 20 74 68 65 20 64 65 66 e..** If the def
33340 61 75 6c 74 20 56 46 53 20 69 73 20 75 6e 72 65 ault VFS is unre
33350 67 69 73 74 65 72 65 64 2c 20 61 6e 6f 74 68 65 gistered, anothe
33360 72 20 56 46 53 20 69 73 20 63 68 6f 73 65 6e 20 r VFS is chosen
33370 61 73 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c as.** the defaul
33380 74 2e 20 20 54 68 65 20 63 68 6f 69 63 65 20 66 t. The choice f
33390 6f 72 20 74 68 65 20 6e 65 77 20 56 46 53 20 69 or the new VFS i
333a0 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a s arbitrary..**.
333b0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
333c0 0a 2a 2a 20 5b 48 31 31 32 30 33 5d 20 5b 48 31 .** [H11203] [H1
333d0 31 32 30 36 5d 20 5b 48 31 31 32 30 39 5d 20 5b 1206] [H11209] [
333e0 48 31 31 32 31 32 5d 20 5b 48 31 31 32 31 35 5d H11212] [H11215]
333f0 20 5b 48 31 31 32 31 38 5d 0a 2a 2f 0a 73 71 6c [H11218].*/.sql
33400 69 74 65 33 5f 76 66 73 20 2a 73 71 6c 69 74 65 ite3_vfs *sqlite
33410 33 5f 76 66 73 5f 66 69 6e 64 28 63 6f 6e 73 74 3_vfs_find(const
33420 20 63 68 61 72 20 2a 7a 56 66 73 4e 61 6d 65 29 char *zVfsName)
33430 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 ;.int sqlite3_vf
33440 73 5f 72 65 67 69 73 74 65 72 28 73 71 6c 69 74 s_register(sqlit
33450 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 61 6b e3_vfs*, int mak
33460 65 44 66 6c 74 29 3b 0a 69 6e 74 20 73 71 6c 69 eDflt);.int sqli
33470 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 te3_vfs_unregist
33480 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 29 er(sqlite3_vfs*)
33490 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
334a0 46 3a 20 4d 75 74 65 78 65 73 20 7b 48 31 37 30 F: Mutexes {H170
334b0 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 00} <S20000>.**.
334c0 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f ** The SQLite co
334d0 72 65 20 75 73 65 73 20 74 68 65 73 65 20 72 6f re uses these ro
334e0 75 74 69 6e 65 73 20 66 6f 72 20 74 68 72 65 61 utines for threa
334f0 64 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e 69 7a 61 d.** synchroniza
33500 74 69 6f 6e 2e 20 54 68 6f 75 67 68 20 74 68 65 tion. Though the
33510 79 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 y are intended f
33520 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 or internal.** u
33530 73 65 20 62 79 20 53 51 4c 69 74 65 2c 20 63 6f se by SQLite, co
33540 64 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 de that links ag
33550 61 69 6e 73 74 20 53 51 4c 69 74 65 20 69 73 0a ainst SQLite is.
33560 2a 2a 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 ** permitted to
33570 75 73 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 use any of these
33580 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a routines..**.**
33590 20 54 68 65 20 53 51 4c 69 74 65 20 73 6f 75 72 The SQLite sour
335a0 63 65 20 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73 ce code contains
335b0 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d multiple implem
335c0 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6f 66 20 entations.** of
335d0 74 68 65 73 65 20 6d 75 74 65 78 20 72 6f 75 74 these mutex rout
335e0 69 6e 65 73 2e 20 20 41 6e 20 61 70 70 72 6f 70 ines. An approp
335f0 72 69 61 74 65 20 69 6d 70 6c 65 6d 65 6e 74 61 riate implementa
33600 74 69 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c 65 63 tion.** is selec
33610 74 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c ted automaticall
33620 79 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d y at compile-tim
33630 65 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e e. The followin
33640 67 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 g.** implementat
33650 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62 ions are availab
33660 6c 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 le in the SQLite
33670 20 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c core:.**.** <ul
33680 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 >.** <li> SQLI
33690 54 45 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 TE_MUTEX_OS2.**
336a0 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 <li> SQLITE_MU
336b0 54 45 58 5f 50 54 48 52 45 41 44 0a 2a 2a 20 3c TEX_PTHREAD.** <
336c0 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 li> SQLITE_MUT
336d0 45 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 EX_W32.** <li>
336e0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f SQLITE_MUTEX_NO
336f0 4f 50 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a OP.** </ul>.**.*
33700 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 * The SQLITE_MUT
33710 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e EX_NOOP implemen
33720 74 61 74 69 6f 6e 20 69 73 20 61 20 73 65 74 20 tation is a set
33730 6f 66 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 74 of routines.** t
33740 68 61 74 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c hat does no real
33750 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73 20 locking and is
33760 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 appropriate for
33770 75 73 65 20 69 6e 0a 2a 2a 20 61 20 73 69 6e 67 use in.** a sing
33780 6c 65 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c le-threaded appl
33790 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 53 51 ication. The SQ
337a0 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a LITE_MUTEX_OS2,.
337b0 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f ** SQLITE_MUTEX_
337c0 50 54 48 52 45 41 44 2c 20 61 6e 64 20 53 51 4c PTHREAD, and SQL
337d0 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 20 69 6d ITE_MUTEX_W32 im
337e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a plementations.**
337f0 20 61 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 are appropriate
33800 20 66 6f 72 20 75 73 65 20 6f 6e 20 4f 53 2f 32 for use on OS/2
33810 2c 20 55 6e 69 78 2c 20 61 6e 64 20 57 69 6e 64 , Unix, and Wind
33820 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 53 51 ows..**.** If SQ
33830 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
33840 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 with the SQLITE
33850 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 20 70 72 _MUTEX_APPDEF pr
33860 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d 61 eprocessor.** ma
33870 63 72 6f 20 64 65 66 69 6e 65 64 20 28 77 69 74 cro defined (wit
33880 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d 55 54 45 h "-DSQLITE_MUTE
33890 58 5f 41 50 50 44 45 46 3d 31 22 29 2c 20 74 68 X_APPDEF=1"), th
338a0 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20 69 en no mutex.** i
338b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 mplementation is
338c0 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68 20 74 included with t
338d0 68 65 20 6c 69 62 72 61 72 79 2e 20 49 6e 20 74 he library. In t
338e0 68 69 73 20 63 61 73 65 20 74 68 65 0a 2a 2a 20 his case the.**
338f0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
33900 20 73 75 70 70 6c 79 20 61 20 63 75 73 74 6f 6d supply a custom
33910 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 mutex implement
33920 61 74 69 6f 6e 20 75 73 69 6e 67 20 74 68 65 0a ation using the.
33930 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ** [SQLITE_CONFI
33940 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 20 G_MUTEX] option
33950 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 of the sqlite3_c
33960 6f 6e 66 69 67 28 29 20 66 75 6e 63 74 69 6f 6e onfig() function
33970 0a 2a 2a 20 62 65 66 6f 72 65 20 63 61 6c 6c 69 .** before calli
33980 6e 67 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 ng sqlite3_initi
33990 61 6c 69 7a 65 28 29 20 6f 72 20 61 6e 79 20 6f alize() or any o
339a0 74 68 65 72 20 70 75 62 6c 69 63 20 73 71 6c 69 ther public sqli
339b0 74 65 33 5f 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e te3_.** function
339c0 20 74 68 61 74 20 63 61 6c 6c 73 20 73 71 6c 69 that calls sqli
339d0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
339e0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 31 7d ..**.** {H17011}
339f0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 The sqlite3_mut
33a00 65 78 5f 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 ex_alloc() routi
33a10 6e 65 20 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e ne allocates a n
33a20 65 77 0a 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20 ew.** mutex and
33a30 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
33a40 72 20 74 6f 20 69 74 2e 20 7b 48 31 37 30 31 32 r to it. {H17012
33a50 7d 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 } If it returns
33a60 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d 65 61 NULL.** that mea
33a70 6e 73 20 74 68 61 74 20 61 20 6d 75 74 65 78 20 ns that a mutex
33a80 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 61 6c 6c could not be all
33a90 6f 63 61 74 65 64 2e 20 7b 48 31 37 30 31 33 7d ocated. {H17013}
33aa0 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 SQLite.** will
33ab0 75 6e 77 69 6e 64 20 69 74 73 20 73 74 61 63 6b unwind its stack
33ac0 20 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 65 and return an e
33ad0 72 72 6f 72 2e 20 7b 48 31 37 30 31 34 7d 20 54 rror. {H17014} T
33ae0 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 he argument.** t
33af0 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f o sqlite3_mutex_
33b00 61 6c 6c 6f 63 28 29 20 69 73 20 6f 6e 65 20 6f alloc() is one o
33b10 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 f these integer
33b20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a constants:.**.**
33b30 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 <ul>.** <li> S
33b40 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 QLITE_MUTEX_FAST
33b50 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 .** <li> SQLITE
33b60 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 _MUTEX_RECURSIVE
33b70 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 .** <li> SQLITE
33b80 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 _MUTEX_STATIC_MA
33b90 53 54 45 52 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 STER.** <li> SQ
33ba0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 LITE_MUTEX_STATI
33bb0 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 20 53 C_MEM.** <li> S
33bc0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 QLITE_MUTEX_STAT
33bd0 49 43 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 3e 20 IC_MEM2.** <li>
33be0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 SQLITE_MUTEX_ST
33bf0 41 54 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c 6c 69 ATIC_PRNG.** <li
33c00 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f > SQLITE_MUTEX_
33c10 53 54 41 54 49 43 5f 4c 52 55 0a 2a 2a 20 3c 6c STATIC_LRU.** <l
33c20 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 i> SQLITE_MUTEX
33c30 5f 53 54 41 54 49 43 5f 4c 52 55 32 0a 2a 2a 20 _STATIC_LRU2.**
33c40 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 </ul>.**.** {H17
33c50 30 31 35 7d 20 54 68 65 20 66 69 72 73 74 20 74 015} The first t
33c60 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 75 wo constants cau
33c70 73 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 se sqlite3_mutex
33c80 5f 61 6c 6c 6f 63 28 29 20 74 6f 20 63 72 65 61 _alloc() to crea
33c90 74 65 0a 2a 2a 20 61 20 6e 65 77 20 6d 75 74 65 te.** a new mute
33ca0 78 2e 20 20 54 68 65 20 6e 65 77 20 6d 75 74 65 x. The new mute
33cb0 78 20 69 73 20 72 65 63 75 72 73 69 76 65 20 77 x is recursive w
33cc0 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 hen SQLITE_MUTEX
33cd0 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 69 73 _RECURSIVE.** is
33ce0 20 75 73 65 64 20 62 75 74 20 6e 6f 74 20 6e 65 used but not ne
33cf0 63 65 73 73 61 72 69 6c 79 20 73 6f 20 77 68 65 cessarily so whe
33d00 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 n SQLITE_MUTEX_F
33d10 41 53 54 20 69 73 20 75 73 65 64 2e 20 7b 45 4e AST is used. {EN
33d20 44 7d 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 D}.** The mutex
33d30 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 implementation d
33d40 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 oes not need to
33d50 6d 61 6b 65 20 61 20 64 69 73 74 69 6e 63 74 69 make a distincti
33d60 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 on.** between SQ
33d70 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 LITE_MUTEX_RECUR
33d80 53 49 56 45 20 61 6e 64 20 53 51 4c 49 54 45 5f SIVE and SQLITE_
33d90 4d 55 54 45 58 5f 46 41 53 54 20 69 66 20 69 74 MUTEX_FAST if it
33da0 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e does.** not wan
33db0 74 20 74 6f 2e 20 20 7b 48 31 37 30 31 36 7d 20 t to. {H17016}
33dc0 42 75 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 But SQLite will
33dd0 6f 6e 6c 79 20 72 65 71 75 65 73 74 20 61 20 72 only request a r
33de0 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 20 69 ecursive mutex i
33df0 6e 0a 2a 2a 20 63 61 73 65 73 20 77 68 65 72 65 n.** cases where
33e00 20 69 74 20 72 65 61 6c 6c 79 20 6e 65 65 64 73 it really needs
33e10 20 6f 6e 65 2e 20 20 7b 45 4e 44 7d 20 49 66 20 one. {END} If
33e20 61 20 66 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63 a faster non-rec
33e30 75 72 73 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20 ursive mutex.**
33e40 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 implementation i
33e50 73 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74 s available on t
33e60 68 65 20 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d he host platform
33e70 2c 20 74 68 65 20 6d 75 74 65 78 20 73 75 62 73 , the mutex subs
33e80 79 73 74 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 ystem.** might r
33e90 65 74 75 72 6e 20 73 75 63 68 20 61 20 6d 75 74 eturn such a mut
33ea0 65 78 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 ex in response t
33eb0 6f 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 o SQLITE_MUTEX_F
33ec0 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 AST..**.** {H170
33ed0 31 37 7d 20 54 68 65 20 6f 74 68 65 72 20 61 6c 17} The other al
33ee0 6c 6f 77 65 64 20 70 61 72 61 6d 65 74 65 72 73 lowed parameters
33ef0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 to sqlite3_mute
33f00 78 5f 61 6c 6c 6f 63 28 29 20 65 61 63 68 20 72 x_alloc() each r
33f10 65 74 75 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 eturn.** a point
33f20 65 72 20 74 6f 20 61 20 73 74 61 74 69 63 20 70 er to a static p
33f30 72 65 65 78 69 73 74 69 6e 67 20 6d 75 74 65 78 reexisting mutex
33f40 2e 20 7b 45 4e 44 7d 20 20 46 6f 75 72 20 73 74 . {END} Four st
33f50 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72 65 atic mutexes are
33f60 0a 2a 2a 20 75 73 65 64 20 62 79 20 74 68 65 20 .** used by the
33f70 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f 6e 20 current version
33f80 6f 66 20 53 51 4c 69 74 65 2e 20 20 46 75 74 75 of SQLite. Futu
33f90 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 re versions of S
33fa0 51 4c 69 74 65 0a 2a 2a 20 6d 61 79 20 61 64 64 QLite.** may add
33fb0 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61 74 additional stat
33fc0 69 63 20 6d 75 74 65 78 65 73 2e 20 20 53 74 61 ic mutexes. Sta
33fd0 74 69 63 20 6d 75 74 65 78 65 73 20 61 72 65 20 tic mutexes are
33fe0 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 for internal.**
33ff0 75 73 65 20 62 79 20 53 51 4c 69 74 65 20 6f 6e use by SQLite on
34000 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e ly. Application
34010 73 20 74 68 61 74 20 75 73 65 20 53 51 4c 69 74 s that use SQLit
34020 65 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 e mutexes should
34030 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79 20 74 68 65 .** use only the
34040 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65 73 dynamic mutexes
34050 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c returned by SQL
34060 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 6f ITE_MUTEX_FAST o
34070 72 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 r.** SQLITE_MUTE
34080 58 5f 52 45 43 55 52 53 49 56 45 2e 0a 2a 2a 0a X_RECURSIVE..**.
34090 2a 2a 20 7b 48 31 37 30 31 38 7d 20 4e 6f 74 65 ** {H17018} Note
340a0 20 74 68 61 74 20 69 66 20 6f 6e 65 20 6f 66 20 that if one of
340b0 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 the dynamic mute
340c0 78 20 70 61 72 61 6d 65 74 65 72 73 20 28 53 51 x parameters (SQ
340d0 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a LITE_MUTEX_FAST.
340e0 2a 2a 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54 ** or SQLITE_MUT
340f0 45 58 5f 52 45 43 55 52 53 49 56 45 29 20 69 73 EX_RECURSIVE) is
34100 20 75 73 65 64 20 74 68 65 6e 20 73 71 6c 69 74 used then sqlit
34110 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 e3_mutex_alloc()
34120 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 64 69 .** returns a di
34130 66 66 65 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e fferent mutex on
34140 20 65 76 65 72 79 20 63 61 6c 6c 2e 20 20 7b 48 every call. {H
34150 31 37 30 33 34 7d 20 42 75 74 20 66 6f 72 20 74 17034} But for t
34160 68 65 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 he static.** mut
34170 65 78 20 74 79 70 65 73 2c 20 74 68 65 20 73 61 ex types, the sa
34180 6d 65 20 6d 75 74 65 78 20 69 73 20 72 65 74 75 me mutex is retu
34190 72 6e 65 64 20 6f 6e 20 65 76 65 72 79 20 63 61 rned on every ca
341a0 6c 6c 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 74 ll that has.** t
341b0 68 65 20 73 61 6d 65 20 74 79 70 65 20 6e 75 6d he same type num
341c0 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 ber..**.** {H170
341d0 31 39 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 19} The sqlite3_
341e0 6d 75 74 65 78 5f 66 72 65 65 28 29 20 72 6f 75 mutex_free() rou
341f0 74 69 6e 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 tine deallocates
34200 20 61 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a a previously.**
34210 20 61 6c 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d allocated dynam
34220 69 63 20 6d 75 74 65 78 2e 20 7b 48 31 37 30 32 ic mutex. {H1702
34230 30 7d 20 53 51 4c 69 74 65 20 69 73 20 63 61 72 0} SQLite is car
34240 65 66 75 6c 20 74 6f 20 64 65 61 6c 6c 6f 63 61 eful to dealloca
34250 74 65 20 65 76 65 72 79 0a 2a 2a 20 64 79 6e 61 te every.** dyna
34260 6d 69 63 20 6d 75 74 65 78 20 74 68 61 74 20 69 mic mutex that i
34270 74 20 61 6c 6c 6f 63 61 74 65 73 2e 20 7b 41 31 t allocates. {A1
34280 37 30 32 31 7d 20 54 68 65 20 64 79 6e 61 6d 69 7021} The dynami
34290 63 20 6d 75 74 65 78 65 73 20 6d 75 73 74 20 6e c mutexes must n
342a0 6f 74 20 62 65 20 69 6e 0a 2a 2a 20 75 73 65 20 ot be in.** use
342b0 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 64 65 when they are de
342c0 61 6c 6c 6f 63 61 74 65 64 2e 20 7b 41 31 37 30 allocated. {A170
342d0 32 32 7d 20 41 74 74 65 6d 70 74 69 6e 67 20 74 22} Attempting t
342e0 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 20 73 o deallocate a s
342f0 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20 72 tatic.** mutex r
34300 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 esults in undefi
34310 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 20 7b 48 ned behavior. {H
34320 31 37 30 32 33 7d 20 53 51 4c 69 74 65 20 6e 65 17023} SQLite ne
34330 76 65 72 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a ver deallocates.
34340 2a 2a 20 61 20 73 74 61 74 69 63 20 6d 75 74 65 ** a static mute
34350 78 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 x. {END}.**.** T
34360 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 he sqlite3_mutex
34370 5f 65 6e 74 65 72 28 29 20 61 6e 64 20 73 71 6c _enter() and sql
34380 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 ite3_mutex_try()
34390 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 routines attemp
343a0 74 0a 2a 2a 20 74 6f 20 65 6e 74 65 72 20 61 20 t.** to enter a
343b0 6d 75 74 65 78 2e 20 7b 48 31 37 30 32 34 7d 20 mutex. {H17024}
343c0 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 If another threa
343d0 64 20 69 73 20 61 6c 72 65 61 64 79 20 77 69 74 d is already wit
343e0 68 69 6e 20 74 68 65 20 6d 75 74 65 78 2c 0a 2a hin the mutex,.*
343f0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f * sqlite3_mutex_
34400 65 6e 74 65 72 28 29 20 77 69 6c 6c 20 62 6c 6f enter() will blo
34410 63 6b 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d ck and sqlite3_m
34420 75 74 65 78 5f 74 72 79 28 29 20 77 69 6c 6c 20 utex_try() will
34430 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 return.** SQLITE
34440 5f 42 55 53 59 2e 20 7b 48 31 37 30 32 35 7d 20 _BUSY. {H17025}
34450 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 The sqlite3_mut
34460 65 78 5f 74 72 79 28 29 20 69 6e 74 65 72 66 61 ex_try() interfa
34470 63 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ce returns [SQLI
34480 54 45 5f 4f 4b 5d 0a 2a 2a 20 75 70 6f 6e 20 73 TE_OK].** upon s
34490 75 63 63 65 73 73 66 75 6c 20 65 6e 74 72 79 2e uccessful entry.
344a0 20 20 7b 48 31 37 30 32 36 7d 20 4d 75 74 65 78 {H17026} Mutex
344b0 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 es created using
344c0 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 .** SQLITE_MUTEX
344d0 5f 52 45 43 55 52 53 49 56 45 20 63 61 6e 20 62 _RECURSIVE can b
344e0 65 20 65 6e 74 65 72 65 64 20 6d 75 6c 74 69 70 e entered multip
344f0 6c 65 20 74 69 6d 65 73 20 62 79 20 74 68 65 20 le times by the
34500 73 61 6d 65 20 74 68 72 65 61 64 2e 0a 2a 2a 20 same thread..**
34510 7b 48 31 37 30 32 37 7d 20 49 6e 20 73 75 63 68 {H17027} In such
34520 20 63 61 73 65 73 20 74 68 65 2c 0a 2a 2a 20 6d cases the,.** m
34530 75 74 65 78 20 6d 75 73 74 20 62 65 20 65 78 69 utex must be exi
34540 74 65 64 20 61 6e 20 65 71 75 61 6c 20 6e 75 6d ted an equal num
34550 62 65 72 20 6f 66 20 74 69 6d 65 73 20 62 65 66 ber of times bef
34560 6f 72 65 20 61 6e 6f 74 68 65 72 20 74 68 72 65 ore another thre
34570 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74 65 72 2e ad.** can enter.
34580 20 20 7b 41 31 37 30 32 38 7d 20 49 66 20 74 68 {A17028} If th
34590 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 74 72 e same thread tr
345a0 69 65 73 20 74 6f 20 65 6e 74 65 72 20 61 6e 79 ies to enter any
345b0 20 6f 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f other.** kind o
345c0 66 20 6d 75 74 65 78 20 6d 6f 72 65 20 74 68 61 f mutex more tha
345d0 6e 20 6f 6e 63 65 2c 20 74 68 65 20 62 65 68 61 n once, the beha
345e0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 vior is undefine
345f0 64 2e 0a 2a 2a 20 7b 48 31 37 30 32 39 7d 20 53 d..** {H17029} S
34600 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 QLite will never
34610 20 65 78 68 69 62 69 74 0a 2a 2a 20 73 75 63 68 exhibit.** such
34620 20 62 65 68 61 76 69 6f 72 20 69 6e 20 69 74 73 behavior in its
34630 20 6f 77 6e 20 75 73 65 20 6f 66 20 6d 75 74 65 own use of mute
34640 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 xes..**.** Some
34650 73 79 73 74 65 6d 73 20 28 66 6f 72 20 65 78 61 systems (for exa
34660 6d 70 6c 65 2c 20 57 69 6e 64 6f 77 73 20 39 35 mple, Windows 95
34670 29 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 ) do not support
34680 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a the operation.*
34690 2a 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 * implemented by
346a0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 sqlite3_mutex_t
346b0 72 79 28 29 2e 20 20 4f 6e 20 74 68 6f 73 65 20 ry(). On those
346c0 73 79 73 74 65 6d 73 2c 20 73 71 6c 69 74 65 33 systems, sqlite3
346d0 5f 6d 75 74 65 78 5f 74 72 79 28 29 0a 2a 2a 20 _mutex_try().**
346e0 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 will always retu
346f0 72 6e 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 rn SQLITE_BUSY.
34700 20 7b 48 31 37 30 33 30 7d 20 54 68 65 20 53 51 {H17030} The SQ
34710 4c 69 74 65 20 63 6f 72 65 20 6f 6e 6c 79 20 65 Lite core only e
34720 76 65 72 20 75 73 65 73 0a 2a 2a 20 73 71 6c 69 ver uses.** sqli
34730 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 te3_mutex_try()
34740 61 73 20 61 6e 20 6f 70 74 69 6d 69 7a 61 74 69 as an optimizati
34750 6f 6e 20 73 6f 20 74 68 69 73 20 69 73 20 61 63 on so this is ac
34760 63 65 70 74 61 62 6c 65 20 62 65 68 61 76 69 6f ceptable behavio
34770 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 33 31 r..**.** {H17031
34780 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 } The sqlite3_mu
34790 74 65 78 5f 6c 65 61 76 65 28 29 20 72 6f 75 74 tex_leave() rout
347a0 69 6e 65 20 65 78 69 74 73 20 61 20 6d 75 74 65 ine exits a mute
347b0 78 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 70 72 x that was.** pr
347c0 65 76 69 6f 75 73 6c 79 20 65 6e 74 65 72 65 64 eviously entered
347d0 20 62 79 20 74 68 65 20 73 61 6d 65 20 74 68 72 by the same thr
347e0 65 61 64 2e 20 20 7b 41 31 37 30 33 32 7d 20 54 ead. {A17032} T
347f0 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 he behavior.** i
34800 73 20 75 6e 64 65 66 69 6e 65 64 20 69 66 20 74 s undefined if t
34810 68 65 20 6d 75 74 65 78 20 69 73 20 6e 6f 74 20 he mutex is not
34820 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 currently entere
34830 64 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c d by the.** call
34840 69 6e 67 20 74 68 72 65 61 64 20 6f 72 20 69 73 ing thread or is
34850 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 61 not currently a
34860 6c 6c 6f 63 61 74 65 64 2e 20 20 7b 48 31 37 30 llocated. {H170
34870 33 33 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 33} SQLite will.
34880 2a 2a 20 6e 65 76 65 72 20 64 6f 20 65 69 74 68 ** never do eith
34890 65 72 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 er. {END}.**.**
348a0 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 If the argument
348b0 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 to sqlite3_mutex
348c0 5f 65 6e 74 65 72 28 29 2c 20 73 71 6c 69 74 65 _enter(), sqlite
348d0 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 2c 20 6f 3_mutex_try(), o
348e0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 r.** sqlite3_mut
348f0 65 78 5f 6c 65 61 76 65 28 29 20 69 73 20 61 20 ex_leave() is a
34900 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 NULL pointer, th
34910 65 6e 20 61 6c 6c 20 74 68 72 65 65 20 72 6f 75 en all three rou
34920 74 69 6e 65 73 0a 2a 2a 20 62 65 68 61 76 65 20 tines.** behave
34930 61 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a as no-ops..**.**
34940 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
34950 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 te3_mutex_held()
34960 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6d ] and [sqlite3_m
34970 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e utex_notheld()].
34980 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 .*/.sqlite3_mute
34990 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 x *sqlite3_mutex
349a0 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 _alloc(int);.voi
349b0 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f d sqlite3_mutex_
349c0 66 72 65 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 free(sqlite3_mut
349d0 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 ex*);.void sqlit
349e0 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 73 e3_mutex_enter(s
349f0 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a qlite3_mutex*);.
34a00 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 int sqlite3_mute
34a10 78 5f 74 72 79 28 73 71 6c 69 74 65 33 5f 6d 75 x_try(sqlite3_mu
34a20 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 tex*);.void sqli
34a30 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 te3_mutex_leave(
34a40 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b sqlite3_mutex*);
34a50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
34a60 3a 20 4d 75 74 65 78 20 4d 65 74 68 6f 64 73 20 : Mutex Methods
34a70 4f 62 6a 65 63 74 20 7b 48 31 37 31 32 30 7d 20 Object {H17120}
34a80 3c 53 32 30 31 33 30 3e 0a 2a 2a 20 45 58 50 45 <S20130>.** EXPE
34a90 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 RIMENTAL.**.** A
34aa0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
34ab0 69 73 20 73 74 72 75 63 74 75 72 65 20 64 65 66 is structure def
34ac0 69 6e 65 73 20 74 68 65 20 6c 6f 77 2d 6c 65 76 ines the low-lev
34ad0 65 6c 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 el routines.** u
34ae0 73 65 64 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 sed to allocate
34af0 61 6e 64 20 75 73 65 20 6d 75 74 65 78 65 73 2e and use mutexes.
34b00 0a 2a 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 .**.** Usually,
34b10 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 the default mute
34b20 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e x implementation
34b30 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 53 51 s provided by SQ
34b40 4c 69 74 65 20 61 72 65 0a 2a 2a 20 73 75 66 66 Lite are.** suff
34b50 69 63 69 65 6e 74 2c 20 68 6f 77 65 76 65 72 20 icient, however
34b60 74 68 65 20 75 73 65 72 20 68 61 73 20 74 68 65 the user has the
34b70 20 6f 70 74 69 6f 6e 20 6f 66 20 73 75 62 73 74 option of subst
34b80 69 74 75 74 69 6e 67 20 61 20 63 75 73 74 6f 6d ituting a custom
34b90 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
34ba0 6f 6e 20 66 6f 72 20 73 70 65 63 69 61 6c 69 7a on for specializ
34bb0 65 64 20 64 65 70 6c 6f 79 6d 65 6e 74 73 20 6f ed deployments o
34bc0 72 20 73 79 73 74 65 6d 73 20 66 6f 72 20 77 68 r systems for wh
34bd0 69 63 68 20 53 51 4c 69 74 65 0a 2a 2a 20 64 6f ich SQLite.** do
34be0 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 es not provide a
34bf0 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d suitable implem
34c00 65 6e 74 61 74 69 6f 6e 2e 20 49 6e 20 74 68 69 entation. In thi
34c10 73 20 63 61 73 65 2c 20 74 68 65 20 75 73 65 72 s case, the user
34c20 0a 2a 2a 20 63 72 65 61 74 65 73 20 61 6e 64 20 .** creates and
34c30 70 6f 70 75 6c 61 74 65 73 20 61 6e 20 69 6e 73 populates an ins
34c40 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 tance of this st
34c50 72 75 63 74 75 72 65 20 74 6f 20 70 61 73 73 0a ructure to pass.
34c60 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ** to sqlite3_co
34c70 6e 66 69 67 28 29 20 61 6c 6f 6e 67 20 77 69 74 nfig() along wit
34c80 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f h the [SQLITE_CO
34c90 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 NFIG_MUTEX] opti
34ca0 6f 6e 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 on..** Additiona
34cb0 6c 6c 79 2c 20 61 6e 20 69 6e 73 74 61 6e 63 65 lly, an instance
34cc0 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 of this structu
34cd0 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 re can be used a
34ce0 73 20 61 6e 0a 2a 2a 20 6f 75 74 70 75 74 20 76 s an.** output v
34cf0 61 72 69 61 62 6c 65 20 77 68 65 6e 20 71 75 65 ariable when que
34d00 72 79 69 6e 67 20 74 68 65 20 73 79 73 74 65 6d rying the system
34d10 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 for the current
34d20 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d mutex.** implem
34d30 65 6e 74 61 74 69 6f 6e 2c 20 75 73 69 6e 67 20 entation, using
34d40 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 the [SQLITE_CONF
34d50 49 47 5f 47 45 54 4d 55 54 45 58 5d 20 6f 70 74 IG_GETMUTEX] opt
34d60 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ion..**.** The x
34d70 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 MutexInit method
34d80 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 defined by this
34d90 20 73 74 72 75 63 74 75 72 65 20 69 73 20 69 6e structure is in
34da0 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 voked as.** part
34db0 20 6f 66 20 73 79 73 74 65 6d 20 69 6e 69 74 69 of system initi
34dc0 61 6c 69 7a 61 74 69 6f 6e 20 62 79 20 74 68 65 alization by the
34dd0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
34de0 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 2e 0a ize() function..
34df0 2a 2a 20 7b 48 31 37 30 30 31 7d 20 54 68 65 20 ** {H17001} The
34e00 78 4d 75 74 65 78 49 6e 69 74 20 72 6f 75 74 69 xMutexInit routi
34e10 6e 65 20 73 68 61 6c 6c 20 62 65 20 63 61 6c 6c ne shall be call
34e20 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 63 ed by SQLite onc
34e30 65 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 65 66 e for each.** ef
34e40 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 fective call to
34e50 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c [sqlite3_initial
34e60 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 ize()]..**.** Th
34e70 65 20 78 4d 75 74 65 78 45 6e 64 20 6d 65 74 68 e xMutexEnd meth
34e80 6f 64 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 od defined by th
34e90 69 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20 is structure is
34ea0 69 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 invoked as.** pa
34eb0 72 74 20 6f 66 20 73 79 73 74 65 6d 20 73 68 75 rt of system shu
34ec0 74 64 6f 77 6e 20 62 79 20 74 68 65 20 73 71 6c tdown by the sql
34ed0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 ite3_shutdown()
34ee0 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 0a 2a 2a function. The.**
34ef0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
34f00 6f 66 20 74 68 69 73 20 6d 65 74 68 6f 64 20 69 of this method i
34f10 73 20 65 78 70 65 63 74 65 64 20 74 6f 20 72 65 s expected to re
34f20 6c 65 61 73 65 20 61 6c 6c 20 6f 75 74 73 74 61 lease all outsta
34f30 6e 64 69 6e 67 0a 2a 2a 20 72 65 73 6f 75 72 63 nding.** resourc
34f40 65 73 20 6f 62 74 61 69 6e 65 64 20 62 79 20 74 es obtained by t
34f50 68 65 20 6d 75 74 65 78 20 6d 65 74 68 6f 64 73 he mutex methods
34f60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c implementation,
34f70 20 65 73 70 65 63 69 61 6c 6c 79 0a 2a 2a 20 74 especially.** t
34f80 68 6f 73 65 20 6f 62 74 61 69 6e 65 64 20 62 79 hose obtained by
34f90 20 74 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20 the xMutexInit
34fa0 6d 65 74 68 6f 64 2e 20 7b 48 31 37 30 30 33 7d method. {H17003}
34fb0 20 54 68 65 20 78 4d 75 74 65 78 45 6e 64 28 29 The xMutexEnd()
34fc0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 73 68 .** interface sh
34fd0 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 6f all be invoked o
34fe0 6e 63 65 20 66 6f 72 20 65 61 63 68 20 63 61 6c nce for each cal
34ff0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 68 l to [sqlite3_sh
35000 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a utdown()]..**.**
35010 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 73 The remaining s
35020 65 76 65 6e 20 6d 65 74 68 6f 64 73 20 64 65 66 even methods def
35030 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 74 72 ined by this str
35040 75 63 74 75 72 65 20 28 78 4d 75 74 65 78 41 6c ucture (xMutexAl
35050 6c 6f 63 2c 0a 2a 2a 20 78 4d 75 74 65 78 46 72 loc,.** xMutexFr
35060 65 65 2c 20 78 4d 75 74 65 78 45 6e 74 65 72 2c ee, xMutexEnter,
35070 20 78 4d 75 74 65 78 54 72 79 2c 20 78 4d 75 74 xMutexTry, xMut
35080 65 78 4c 65 61 76 65 2c 20 78 4d 75 74 65 78 48 exLeave, xMutexH
35090 65 6c 64 20 61 6e 64 0a 2a 2a 20 78 4d 75 74 65 eld and.** xMute
350a0 78 4e 6f 74 68 65 6c 64 29 20 69 6d 70 6c 65 6d xNotheld) implem
350b0 65 6e 74 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e ent the followin
350c0 67 20 69 6e 74 65 72 66 61 63 65 73 20 28 72 65 g interfaces (re
350d0 73 70 65 63 74 69 76 65 6c 79 29 3a 0a 2a 2a 0a spectively):.**.
350e0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 ** <ul>.** <li
350f0 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 > [sqlite3_mute
35100 78 5f 61 6c 6c 6f 63 28 29 5d 20 3c 2f 6c 69 3e x_alloc()] </li>
35110 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c .** <li> [sql
35120 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 ite3_mutex_free(
35130 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c )] </li>.** <l
35140 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 i> [sqlite3_mut
35150 65 78 5f 65 6e 74 65 72 28 29 5d 20 3c 2f 6c 69 ex_enter()] </li
35160 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 >.** <li> [sq
35170 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 lite3_mutex_try(
35180 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c )] </li>.** <l
35190 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 i> [sqlite3_mut
351a0 65 78 5f 6c 65 61 76 65 28 29 5d 20 3c 2f 6c 69 ex_leave()] </li
351b0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 >.** <li> [sq
351c0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 lite3_mutex_held
351d0 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c ()] </li>.** <
351e0 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 li> [sqlite3_mu
351f0 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 20 3c tex_notheld()] <
35200 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a /li>.** </ul>.**
35210 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 .** The only dif
35220 66 65 72 65 6e 63 65 20 69 73 20 74 68 61 74 20 ference is that
35230 74 68 65 20 70 75 62 6c 69 63 20 73 71 6c 69 74 the public sqlit
35240 65 33 5f 58 58 58 20 66 75 6e 63 74 69 6f 6e 73 e3_XXX functions
35250 20 65 6e 75 6d 65 72 61 74 65 64 0a 2a 2a 20 61 enumerated.** a
35260 62 6f 76 65 20 73 69 6c 65 6e 74 6c 79 20 69 67 bove silently ig
35270 6e 6f 72 65 20 61 6e 79 20 69 6e 76 6f 63 61 74 nore any invocat
35280 69 6f 6e 73 20 74 68 61 74 20 70 61 73 73 20 61 ions that pass a
35290 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e NULL pointer in
352a0 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 76 61 stead.** of a va
352b0 6c 69 64 20 6d 75 74 65 78 20 68 61 6e 64 6c 65 lid mutex handle
352c0 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 . The implementa
352d0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 6d 65 74 tions of the met
352e0 68 6f 64 73 20 64 65 66 69 6e 65 64 0a 2a 2a 20 hods defined.**
352f0 62 79 20 74 68 69 73 20 73 74 72 75 63 74 75 72 by this structur
35300 65 20 61 72 65 20 6e 6f 74 20 72 65 71 75 69 72 e are not requir
35310 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 74 68 69 ed to handle thi
35320 73 20 63 61 73 65 2c 20 74 68 65 20 72 65 73 75 s case, the resu
35330 6c 74 73 0a 2a 2a 20 6f 66 20 70 61 73 73 69 6e lts.** of passin
35340 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 g a NULL pointer
35350 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 76 61 instead of a va
35360 6c 69 64 20 6d 75 74 65 78 20 68 61 6e 64 6c 65 lid mutex handle
35370 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 0a 2a are undefined.*
35380 2a 20 28 69 2e 65 2e 20 69 74 20 69 73 20 61 63 * (i.e. it is ac
35390 63 65 70 74 61 62 6c 65 20 74 6f 20 70 72 6f 76 ceptable to prov
353a0 69 64 65 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 ide an implement
353b0 61 74 69 6f 6e 20 74 68 61 74 20 73 65 67 66 61 ation that segfa
353c0 75 6c 74 73 20 69 66 0a 2a 2a 20 69 74 20 69 73 ults if.** it is
353d0 20 70 61 73 73 65 64 20 61 20 4e 55 4c 4c 20 70 passed a NULL p
353e0 6f 69 6e 74 65 72 29 2e 0a 2a 2f 0a 74 79 70 65 ointer)..*/.type
353f0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
35400 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 e3_mutex_methods
35410 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d sqlite3_mutex_m
35420 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 ethods;.struct s
35430 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
35440 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 28 2a 78 hods {. int (*x
35450 4d 75 74 65 78 49 6e 69 74 29 28 76 6f 69 64 29 MutexInit)(void)
35460 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 ;. int (*xMutex
35470 45 6e 64 29 28 76 6f 69 64 29 3b 0a 20 20 73 71 End)(void);. sq
35480 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 28 2a 78 lite3_mutex *(*x
35490 4d 75 74 65 78 41 6c 6c 6f 63 29 28 69 6e 74 29 MutexAlloc)(int)
354a0 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 ;. void (*xMute
354b0 78 46 72 65 65 29 28 73 71 6c 69 74 65 33 5f 6d xFree)(sqlite3_m
354c0 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 utex *);. void
354d0 28 2a 78 4d 75 74 65 78 45 6e 74 65 72 29 28 73 (*xMutexEnter)(s
354e0 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b qlite3_mutex *);
354f0 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 54 . int (*xMutexT
35500 72 79 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 ry)(sqlite3_mute
35510 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 x *);. void (*x
35520 4d 75 74 65 78 4c 65 61 76 65 29 28 73 71 6c 69 MutexLeave)(sqli
35530 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 te3_mutex *);.
35540 69 6e 74 20 28 2a 78 4d 75 74 65 78 48 65 6c 64 int (*xMutexHeld
35550 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 )(sqlite3_mutex
35560 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 *);. int (*xMut
35570 65 78 4e 6f 74 68 65 6c 64 29 28 73 71 6c 69 74 exNotheld)(sqlit
35580 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d 3b 0a e3_mutex *);.};.
35590 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
355a0 20 4d 75 74 65 78 20 56 65 72 69 66 69 63 61 74 Mutex Verificat
355b0 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48 31 ion Routines {H1
355c0 37 30 38 30 7d 20 3c 53 32 30 31 33 30 3e 20 3c 7080} <S20130> <
355d0 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S30800>.**.** Th
355e0 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f e sqlite3_mutex_
355f0 68 65 6c 64 28 29 20 61 6e 64 20 73 71 6c 69 74 held() and sqlit
35600 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 e3_mutex_notheld
35610 28 29 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 () routines.** a
35620 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 re intended for
35630 75 73 65 20 69 6e 73 69 64 65 20 61 73 73 65 72 use inside asser
35640 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 t() statements.
35650 7b 48 31 37 30 38 31 7d 20 54 68 65 20 53 51 4c {H17081} The SQL
35660 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65 ite core.** neve
35670 72 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 r uses these rou
35680 74 69 6e 65 73 20 65 78 63 65 70 74 20 69 6e 73 tines except ins
35690 69 64 65 20 61 6e 20 61 73 73 65 72 74 28 29 20 ide an assert()
356a0 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 and applications
356b0 0a 2a 2a 20 61 72 65 20 61 64 76 69 73 65 64 20 .** are advised
356c0 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65 to follow the le
356d0 61 64 20 6f 66 20 74 68 65 20 63 6f 72 65 2e 20 ad of the core.
356e0 20 7b 48 31 37 30 38 32 7d 20 54 68 65 20 63 6f {H17082} The co
356f0 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69 re only.** provi
35700 64 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 des implementati
35710 6f 6e 73 20 66 6f 72 20 74 68 65 73 65 20 72 6f ons for these ro
35720 75 74 69 6e 65 73 20 77 68 65 6e 20 69 74 20 69 utines when it i
35730 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 s compiled.** wi
35740 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 44 45 th the SQLITE_DE
35750 42 55 47 20 66 6c 61 67 2e 20 20 7b 41 31 37 30 BUG flag. {A170
35760 38 37 7d 20 45 78 74 65 72 6e 61 6c 20 6d 75 74 87} External mut
35770 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ex implementatio
35780 6e 73 0a 2a 2a 20 61 72 65 20 6f 6e 6c 79 20 72 ns.** are only r
35790 65 71 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69 equired to provi
357a0 64 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 de these routine
357b0 73 20 69 66 20 53 51 4c 49 54 45 5f 44 45 42 55 s if SQLITE_DEBU
357c0 47 20 69 73 0a 2a 2a 20 64 65 66 69 6e 65 64 20 G is.** defined
357d0 61 6e 64 20 69 66 20 4e 44 45 42 55 47 20 69 73 and if NDEBUG is
357e0 20 6e 6f 74 20 64 65 66 69 6e 65 64 2e 0a 2a 2a not defined..**
357f0 0a 2a 2a 20 7b 48 31 37 30 38 33 7d 20 54 68 65 .** {H17083} The
35800 73 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 se routines shou
35810 6c 64 20 72 65 74 75 72 6e 20 74 72 75 65 20 69 ld return true i
35820 66 20 74 68 65 20 6d 75 74 65 78 20 69 6e 20 74 f the mutex in t
35830 68 65 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a heir argument.**
35840 20 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20 is held or not
35850 68 65 6c 64 2c 20 72 65 73 70 65 63 74 69 76 65 held, respective
35860 6c 79 2c 20 62 79 20 74 68 65 20 63 61 6c 6c 69 ly, by the calli
35870 6e 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a ng thread..**.**
35880 20 7b 58 31 37 30 38 34 7d 20 54 68 65 20 69 6d {X17084} The im
35890 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 plementation is
358a0 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 not required to
358b0 70 72 6f 76 69 64 65 64 20 76 65 72 73 69 6f 6e provided version
358c0 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 72 6f s of these.** ro
358d0 75 74 69 6e 65 73 20 74 68 61 74 20 61 63 74 75 utines that actu
358e0 61 6c 6c 79 20 77 6f 72 6b 2e 20 49 66 20 74 68 ally work. If th
358f0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
35900 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 does not provid
35910 65 20 77 6f 72 6b 69 6e 67 0a 2a 2a 20 76 65 72 e working.** ver
35920 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 20 72 sions of these r
35930 6f 75 74 69 6e 65 73 2c 20 69 74 20 73 68 6f 75 outines, it shou
35940 6c 64 20 61 74 20 6c 65 61 73 74 20 70 72 6f 76 ld at least prov
35950 69 64 65 20 73 74 75 62 73 20 74 68 61 74 20 61 ide stubs that a
35960 6c 77 61 79 73 0a 2a 2a 20 72 65 74 75 72 6e 20 lways.** return
35970 74 72 75 65 20 73 6f 20 74 68 61 74 20 6f 6e 65 true so that one
35980 20 64 6f 65 73 20 6e 6f 74 20 67 65 74 20 73 70 does not get sp
35990 75 72 69 6f 75 73 20 61 73 73 65 72 74 69 6f 6e urious assertion
359a0 20 66 61 69 6c 75 72 65 73 2e 0a 2a 2a 0a 2a 2a failures..**.**
359b0 20 7b 48 31 37 30 38 35 7d 20 49 66 20 74 68 65 {H17085} If the
359c0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c argument to sql
359d0 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 ite3_mutex_held(
359e0 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e ) is a NULL poin
359f0 74 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 ter then.** the
35a00 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 72 routine should r
35a10 65 74 75 72 6e 20 31 2e 20 20 7b 45 4e 44 7d 20 eturn 1. {END}
35a20 54 68 69 73 20 73 65 65 6d 73 20 63 6f 75 6e 74 This seems count
35a30 65 72 2d 69 6e 74 75 69 74 69 76 65 20 73 69 6e er-intuitive sin
35a40 63 65 0a 2a 2a 20 63 6c 65 61 72 6c 79 20 74 68 ce.** clearly th
35a50 65 20 6d 75 74 65 78 20 63 61 6e 6e 6f 74 20 62 e mutex cannot b
35a60 65 20 68 65 6c 64 20 69 66 20 69 74 20 64 6f 65 e held if it doe
35a70 73 20 6e 6f 74 20 65 78 69 73 74 2e 20 20 42 75 s not exist. Bu
35a80 74 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 65 61 t the.** the rea
35a90 73 6f 6e 20 74 68 65 20 6d 75 74 65 78 20 64 6f son the mutex do
35aa0 65 73 20 6e 6f 74 20 65 78 69 73 74 20 69 73 20 es not exist is
35ab0 62 65 63 61 75 73 65 20 74 68 65 20 62 75 69 6c because the buil
35ac0 64 20 69 73 20 6e 6f 74 0a 2a 2a 20 75 73 69 6e d is not.** usin
35ad0 67 20 6d 75 74 65 78 65 73 2e 20 20 41 6e 64 20 g mutexes. And
35ae0 77 65 20 64 6f 20 6e 6f 74 20 77 61 6e 74 20 74 we do not want t
35af0 68 65 20 61 73 73 65 72 74 28 29 20 63 6f 6e 74 he assert() cont
35b00 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 61 aining the.** ca
35b10 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 ll to sqlite3_mu
35b20 74 65 78 5f 68 65 6c 64 28 29 20 74 6f 20 66 61 tex_held() to fa
35b30 69 6c 2c 20 73 6f 20 61 20 6e 6f 6e 2d 7a 65 72 il, so a non-zer
35b40 6f 20 72 65 74 75 72 6e 20 69 73 0a 2a 2a 20 74 o return is.** t
35b50 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 74 he appropriate t
35b60 68 69 6e 67 20 74 6f 20 64 6f 2e 20 20 7b 48 31 hing to do. {H1
35b70 37 30 38 36 7d 20 54 68 65 20 73 71 6c 69 74 65 7086} The sqlite
35b80 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 3_mutex_notheld(
35b90 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 73 ).** interface s
35ba0 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74 75 72 hould also retur
35bb0 6e 20 31 20 77 68 65 6e 20 67 69 76 65 6e 20 61 n 1 when given a
35bc0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a NULL pointer..*
35bd0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 /.int sqlite3_mu
35be0 74 65 78 5f 68 65 6c 64 28 73 71 6c 69 74 65 33 tex_held(sqlite3
35bf0 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71 _mutex*);.int sq
35c00 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 lite3_mutex_noth
35c10 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 eld(sqlite3_mute
35c20 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 x*);../*.** CAPI
35c30 33 52 45 46 3a 20 4d 75 74 65 78 20 54 79 70 65 3REF: Mutex Type
35c40 73 20 7b 48 31 37 30 30 31 7d 20 3c 48 31 37 30 s {H17001} <H170
35c50 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 00>.**.** The [s
35c60 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c qlite3_mutex_all
35c70 6f 63 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 oc()] interface
35c80 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
35c90 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 69 63 68 rgument.** which
35ca0 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 is one of these
35cb0 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e integer constan
35cc0 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 ts..**.** The se
35cd0 74 20 6f 66 20 73 74 61 74 69 63 20 6d 75 74 65 t of static mute
35ce0 78 65 73 20 6d 61 79 20 63 68 61 6e 67 65 20 66 xes may change f
35cf0 72 6f 6d 20 6f 6e 65 20 53 51 4c 69 74 65 20 72 rom one SQLite r
35d00 65 6c 65 61 73 65 20 74 6f 20 74 68 65 0a 2a 2a elease to the.**
35d10 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 next. Applicat
35d20 69 6f 6e 73 20 74 68 61 74 20 6f 76 65 72 72 69 ions that overri
35d30 64 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 de the built-in
35d40 6d 75 74 65 78 20 6c 6f 67 69 63 20 6d 75 73 74 mutex logic must
35d50 20 62 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 be.** prepared
35d60 74 6f 20 61 63 63 6f 6d 6d 6f 64 61 74 65 20 61 to accommodate a
35d70 64 64 69 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 dditional static
35d80 20 6d 75 74 65 78 65 73 2e 0a 2a 2f 0a 23 64 65 mutexes..*/.#de
35d90 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 fine SQLITE_MUTE
35da0 58 5f 46 41 53 54 20 20 20 20 20 20 20 20 20 20 X_FAST
35db0 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0.#define SQL
35dc0 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 ITE_MUTEX_RECURS
35dd0 49 56 45 20 20 20 20 20 20 20 20 31 0a 23 64 65 IVE 1.#de
35de0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 fine SQLITE_MUTE
35df0 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 20 X_STATIC_MASTER
35e00 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 2.#define SQL
35e10 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 ITE_MUTEX_STATIC
35e20 5f 4d 45 4d 20 20 20 20 20 20 20 33 20 20 2f 2a _MEM 3 /*
35e30 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
35e40 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
35e50 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 ITE_MUTEX_STATIC
35e60 5f 4d 45 4d 32 20 20 20 20 20 20 34 20 20 2f 2a _MEM2 4 /*
35e70 20 4e 4f 54 20 55 53 45 44 20 2a 2f 0a 23 64 65 NOT USED */.#de
35e80 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 fine SQLITE_MUTE
35e90 58 5f 53 54 41 54 49 43 5f 4f 50 45 4e 20 20 20 X_STATIC_OPEN
35ea0 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 4 /* sqlite3
35eb0 42 74 72 65 65 4f 70 65 6e 28 29 20 2a 2f 0a 23 BtreeOpen() */.#
35ec0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 define SQLITE_MU
35ed0 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 20 TEX_STATIC_PRNG
35ee0 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 5 /* sqlit
35ef0 65 33 5f 72 61 6e 64 6f 6d 28 29 20 2a 2f 0a 23 e3_random() */.#
35f00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 define SQLITE_MU
35f10 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 20 20 TEX_STATIC_LRU
35f20 20 20 20 20 20 36 20 20 2f 2a 20 6c 72 75 20 70 6 /* lru p
35f30 61 67 65 20 6c 69 73 74 20 2a 2f 0a 23 64 65 66 age list */.#def
35f40 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 ine SQLITE_MUTEX
35f50 5f 53 54 41 54 49 43 5f 4c 52 55 32 20 20 20 20 _STATIC_LRU2
35f60 20 20 37 20 20 2f 2a 20 6c 72 75 20 70 61 67 65 7 /* lru page
35f70 20 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 list */../*.**
35f80 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 CAPI3REF: Retrie
35f90 76 65 20 74 68 65 20 6d 75 74 65 78 20 66 6f 72 ve the mutex for
35fa0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a database conn
35fb0 65 63 74 69 6f 6e 20 7b 48 31 37 30 30 32 7d 20 ection {H17002}
35fc0 3c 48 31 37 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <H17000>.**.** T
35fd0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 his interface re
35fe0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
35ff0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 the [sqlite3_mut
36000 65 78 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 ex] object that
36010 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 65 73 20 61 .** serializes a
36020 63 63 65 73 73 20 74 6f 20 74 68 65 20 5b 64 61 ccess to the [da
36030 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
36040 6e 5d 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 n] given in the
36050 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 65 6e argument.** when
36060 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 the [threading
36070 6d 6f 64 65 5d 20 69 73 20 53 65 72 69 61 6c 69 mode] is Seriali
36080 7a 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b zed..** If the [
36090 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
360a0 69 73 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 is Single-thread
360b0 20 6f 72 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 or Multi-thread
360c0 20 74 68 65 6e 20 74 68 69 73 0a 2a 2a 20 72 6f then this.** ro
360d0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 utine returns a
360e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f NULL pointer..*/
360f0 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a .sqlite3_mutex *
36100 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 sqlite3_db_mutex
36110 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
36120 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 77 ** CAPI3REF: Low
36130 2d 4c 65 76 65 6c 20 43 6f 6e 74 72 6f 6c 20 4f -Level Control O
36140 66 20 44 61 74 61 62 61 73 65 20 46 69 6c 65 73 f Database Files
36150 20 7b 48 31 31 33 30 30 7d 20 3c 53 33 30 38 30 {H11300} <S3080
36160 30 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 31 0>.**.** {H11301
36170 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 } The [sqlite3_f
36180 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 ile_control()] i
36190 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 nterface makes a
361a0 20 64 69 72 65 63 74 20 63 61 6c 6c 20 74 6f 20 direct call to
361b0 74 68 65 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 the.** xFileCont
361c0 72 6f 6c 20 6d 65 74 68 6f 64 20 66 6f 72 20 74 rol method for t
361d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d he [sqlite3_io_m
361e0 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 ethods] object a
361f0 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 ssociated.** wit
36200 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 h a particular d
36210 61 74 61 62 61 73 65 20 69 64 65 6e 74 69 66 69 atabase identifi
36220 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 ed by the second
36230 20 61 72 67 75 6d 65 6e 74 2e 20 7b 48 31 31 33 argument. {H113
36240 30 32 7d 20 54 68 65 0a 2a 2a 20 6e 61 6d 65 20 02} The.** name
36250 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 of the database
36260 69 73 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 is the name assi
36270 67 6e 65 64 20 74 6f 20 74 68 65 20 64 61 74 61 gned to the data
36280 62 61 73 65 20 62 79 20 74 68 65 0a 2a 2a 20 3c base by the.** <
36290 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f 61 74 74 a href="lang_att
362a0 61 63 68 2e 68 74 6d 6c 22 3e 41 54 54 41 43 48 ach.html">ATTACH
362b0 3c 2f 61 3e 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 </a> SQL command
362c0 20 74 68 61 74 20 6f 70 65 6e 65 64 20 74 68 65 that opened the
362d0 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 7b 48 .** database. {H
362e0 31 31 33 30 33 7d 20 54 6f 20 63 6f 6e 74 72 6f 11303} To contro
362f0 6c 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 l the main datab
36300 61 73 65 20 66 69 6c 65 2c 20 75 73 65 20 74 68 ase file, use th
36310 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 0a 2a 2a e name "main".**
36320 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 or a NULL point
36330 65 72 2e 20 7b 48 31 31 33 30 34 7d 20 54 68 65 er. {H11304} The
36340 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 third and fourt
36350 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 h parameters to
36360 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 this routine.**
36370 61 72 65 20 70 61 73 73 65 64 20 64 69 72 65 63 are passed direc
36380 74 6c 79 20 74 68 72 6f 75 67 68 20 74 6f 20 74 tly through to t
36390 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 he second and th
363a0 69 72 64 20 70 61 72 61 6d 65 74 65 72 73 20 6f ird parameters o
363b0 66 0a 2a 2a 20 74 68 65 20 78 46 69 6c 65 43 6f f.** the xFileCo
363c0 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 20 7b ntrol method. {
363d0 48 31 31 33 30 35 7d 20 54 68 65 20 72 65 74 75 H11305} The retu
363e0 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 rn value of the
363f0 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 0a 2a 2a 20 xFileControl.**
36400 6d 65 74 68 6f 64 20 62 65 63 6f 6d 65 73 20 74 method becomes t
36410 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
36420 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e of this routine.
36430 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 36 7d 20 .**.** {H11306}
36440 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 If the second pa
36450 72 61 6d 65 74 65 72 20 28 7a 44 62 4e 61 6d 65 rameter (zDbName
36460 29 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 ) does not match
36470 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 6e 79 the name of any
36480 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62 61 73 .** open databas
36490 65 20 66 69 6c 65 2c 20 74 68 65 6e 20 53 51 4c e file, then SQL
364a0 49 54 45 5f 45 52 52 4f 52 20 69 73 20 72 65 74 ITE_ERROR is ret
364b0 75 72 6e 65 64 2e 20 7b 48 31 31 33 30 37 7d 20 urned. {H11307}
364c0 54 68 69 73 20 65 72 72 6f 72 0a 2a 2a 20 63 6f This error.** co
364d0 64 65 20 69 73 20 6e 6f 74 20 72 65 6d 65 6d 62 de is not rememb
364e0 65 72 65 64 20 61 6e 64 20 77 69 6c 6c 20 6e 6f ered and will no
364f0 74 20 62 65 20 72 65 63 61 6c 6c 65 64 20 62 79 t be recalled by
36500 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 [sqlite3_errcod
36510 65 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 e()].** or [sqli
36520 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 20 7b te3_errmsg()]. {
36530 41 31 31 33 30 38 7d 20 54 68 65 20 75 6e 64 65 A11308} The unde
36540 72 6c 79 69 6e 67 20 78 46 69 6c 65 43 6f 6e 74 rlying xFileCont
36550 72 6f 6c 20 6d 65 74 68 6f 64 20 6d 69 67 68 74 rol method might
36560 0a 2a 2a 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 .** also return
36570 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 7b SQLITE_ERROR. {
36580 41 31 31 33 30 39 7d 20 54 68 65 72 65 20 69 73 A11309} There is
36590 20 6e 6f 20 77 61 79 20 74 6f 20 64 69 73 74 69 no way to disti
365a0 6e 67 75 69 73 68 20 62 65 74 77 65 65 6e 0a 2a nguish between.*
365b0 2a 20 61 6e 20 69 6e 63 6f 72 72 65 63 74 20 7a * an incorrect z
365c0 44 62 4e 61 6d 65 20 61 6e 64 20 61 6e 20 53 51 DbName and an SQ
365d0 4c 49 54 45 5f 45 52 52 4f 52 20 72 65 74 75 72 LITE_ERROR retur
365e0 6e 20 66 72 6f 6d 20 74 68 65 20 75 6e 64 65 72 n from the under
365f0 6c 79 69 6e 67 0a 2a 2a 20 78 46 69 6c 65 43 6f lying.** xFileCo
36600 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 7b 45 ntrol method. {E
36610 4e 44 7d 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c ND}.**.** See al
36620 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 so: [SQLITE_FCNT
36630 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 0a 2a 2f 0a L_LOCKSTATE].*/.
36640 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 int sqlite3_file
36650 5f 63 6f 6e 74 72 6f 6c 28 73 71 6c 69 74 65 33 _control(sqlite3
36660 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
36670 44 62 4e 61 6d 65 2c 20 69 6e 74 20 6f 70 2c 20 DbName, int op,
36680 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 void*);../*.** C
36690 41 50 49 33 52 45 46 3a 20 54 65 73 74 69 6e 67 API3REF: Testing
366a0 20 49 6e 74 65 72 66 61 63 65 20 7b 48 31 31 34 Interface {H114
366b0 30 30 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 00} <S30800>.**.
366c0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 74 ** The sqlite3_t
366d0 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 20 69 6e est_control() in
366e0 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 terface is used
366f0 74 6f 20 72 65 61 64 20 6f 75 74 20 69 6e 74 65 to read out inte
36700 72 6e 61 6c 0a 2a 2a 20 73 74 61 74 65 20 6f 66 rnal.** state of
36710 20 53 51 4c 69 74 65 20 61 6e 64 20 74 6f 20 69 SQLite and to i
36720 6e 6a 65 63 74 20 66 61 75 6c 74 73 20 69 6e 74 nject faults int
36730 6f 20 53 51 4c 69 74 65 20 66 6f 72 20 74 65 73 o SQLite for tes
36740 74 69 6e 67 0a 2a 2a 20 70 75 72 70 6f 73 65 73 ting.** purposes
36750 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 . The first par
36760 61 6d 65 74 65 72 20 69 73 20 61 6e 20 6f 70 65 ameter is an ope
36770 72 61 74 69 6f 6e 20 63 6f 64 65 20 74 68 61 74 ration code that
36780 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 74 determines.** t
36790 68 65 20 6e 75 6d 62 65 72 2c 20 6d 65 61 6e 69 he number, meani
367a0 6e 67 2c 20 61 6e 64 20 6f 70 65 72 61 74 69 6f ng, and operatio
367b0 6e 20 6f 66 20 61 6c 6c 20 73 75 62 73 65 71 75 n of all subsequ
367c0 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 2e 0a ent parameters..
367d0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 **.** This inter
367e0 66 61 63 65 20 69 73 20 6e 6f 74 20 66 6f 72 20 face is not for
367f0 75 73 65 20 62 79 20 61 70 70 6c 69 63 61 74 69 use by applicati
36800 6f 6e 73 2e 20 20 49 74 20 65 78 69 73 74 73 20 ons. It exists
36810 73 6f 6c 65 6c 79 0a 2a 2a 20 66 6f 72 20 76 65 solely.** for ve
36820 72 69 66 79 69 6e 67 20 74 68 65 20 63 6f 72 72 rifying the corr
36830 65 63 74 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 ect operation of
36840 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 the SQLite libr
36850 61 72 79 2e 20 20 44 65 70 65 6e 64 69 6e 67 0a ary. Depending.
36860 2a 2a 20 6f 6e 20 68 6f 77 20 74 68 65 20 53 51 ** on how the SQ
36870 4c 69 74 65 20 6c 69 62 72 61 72 79 20 69 73 20 Lite library is
36880 63 6f 6d 70 69 6c 65 64 2c 20 74 68 69 73 20 69 compiled, this i
36890 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 6e nterface might n
368a0 6f 74 20 65 78 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 ot exist..**.**
368b0 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 The details of t
368c0 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 he operation cod
368d0 65 73 2c 20 74 68 65 69 72 20 6d 65 61 6e 69 6e es, their meanin
368e0 67 73 2c 20 74 68 65 20 70 61 72 61 6d 65 74 65 gs, the paramete
368f0 72 73 0a 2a 2a 20 74 68 65 79 20 74 61 6b 65 2c rs.** they take,
36900 20 61 6e 64 20 77 68 61 74 20 74 68 65 79 20 64 and what they d
36910 6f 20 61 72 65 20 61 6c 6c 20 73 75 62 6a 65 63 o are all subjec
36920 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 t to change with
36930 6f 75 74 20 6e 6f 74 69 63 65 2e 0a 2a 2a 20 55 out notice..** U
36940 6e 6c 69 6b 65 20 6d 6f 73 74 20 6f 66 20 74 68 nlike most of th
36950 65 20 53 51 4c 69 74 65 20 41 50 49 2c 20 74 68 e SQLite API, th
36960 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e is function is n
36970 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f ot guaranteed to
36980 0a 2a 2a 20 6f 70 65 72 61 74 65 20 63 6f 6e 73 .** operate cons
36990 69 73 74 65 6e 74 6c 79 20 66 72 6f 6d 20 6f 6e istently from on
369a0 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 e release to the
369b0 20 6e 65 78 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 next..*/.int sq
369c0 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 lite3_test_contr
369d0 6f 6c 28 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b ol(int op, ...);
369e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
369f0 3a 20 54 65 73 74 69 6e 67 20 49 6e 74 65 72 66 : Testing Interf
36a00 61 63 65 20 4f 70 65 72 61 74 69 6f 6e 20 43 6f ace Operation Co
36a10 64 65 73 20 7b 48 31 31 34 31 30 7d 20 3c 48 31 des {H11410} <H1
36a20 31 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 1400>.**.** Thes
36a30 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 e constants are
36a40 74 68 65 20 76 61 6c 69 64 20 6f 70 65 72 61 74 the valid operat
36a50 69 6f 6e 20 63 6f 64 65 20 70 61 72 61 6d 65 74 ion code paramet
36a60 65 72 73 20 75 73 65 64 0a 2a 2a 20 61 73 20 74 ers used.** as t
36a70 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
36a80 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 65 t to [sqlite3_te
36a90 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d 2e 0a 2a st_control()]..*
36aa0 2a 0a 2a 2a 20 54 68 65 73 65 20 70 61 72 61 6d *.** These param
36ab0 65 74 65 72 73 20 61 6e 64 20 74 68 65 69 72 20 eters and their
36ac0 6d 65 61 6e 69 6e 67 73 20 61 72 65 20 73 75 62 meanings are sub
36ad0 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 0a 2a ject to change.*
36ae0 2a 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 * without notice
36af0 2e 20 20 54 68 65 73 65 20 76 61 6c 75 65 73 20 . These values
36b00 61 72 65 20 66 6f 72 20 74 65 73 74 69 6e 67 20 are for testing
36b10 70 75 72 70 6f 73 65 73 20 6f 6e 6c 79 2e 0a 2a purposes only..*
36b20 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 * Applications s
36b30 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 61 6e hould not use an
36b40 79 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d y of these param
36b50 65 74 65 72 73 20 6f 72 20 74 68 65 0a 2a 2a 20 eters or the.**
36b60 5b 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f [sqlite3_test_co
36b70 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 ntrol()] interfa
36b80 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ce..*/.#define S
36b90 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 50 QLITE_TESTCTRL_P
36ba0 52 4e 47 5f 53 41 56 45 20 20 20 20 20 20 20 20 RNG_SAVE
36bb0 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 5.#defin
36bc0 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 e SQLITE_TESTCTR
36bd0 4c 5f 50 52 4e 47 5f 52 45 53 54 4f 52 45 20 20 L_PRNG_RESTORE
36be0 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 6.#de
36bf0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 fine SQLITE_TEST
36c00 43 54 52 4c 5f 50 52 4e 47 5f 52 45 53 45 54 20 CTRL_PRNG_RESET
36c10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 7.
36c20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
36c30 45 53 54 43 54 52 4c 5f 42 49 54 56 45 43 5f 54 ESTCTRL_BITVEC_T
36c40 45 53 54 20 20 20 20 20 20 20 20 20 20 20 20 20 EST
36c50 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 8.#define SQLIT
36c60 45 5f 54 45 53 54 43 54 52 4c 5f 46 41 55 4c 54 E_TESTCTRL_FAULT
36c70 5f 49 4e 53 54 41 4c 4c 20 20 20 20 20 20 20 20 _INSTALL
36c80 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 9.#define SQ
36c90 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 42 45 LITE_TESTCTRL_BE
36ca0 4e 49 47 4e 5f 4d 41 4c 4c 4f 43 5f 48 4f 4f 4b NIGN_MALLOC_HOOK
36cb0 53 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 S 10.#define
36cc0 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c SQLITE_TESTCTRL
36cd0 5f 50 45 4e 44 49 4e 47 5f 42 59 54 45 20 20 20 _PENDING_BYTE
36ce0 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 11.#def
36cf0 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 ine SQLITE_TESTC
36d00 54 52 4c 5f 41 53 53 45 52 54 20 20 20 20 20 20 TRL_ASSERT
36d10 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 12.#
36d20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 define SQLITE_TE
36d30 53 54 43 54 52 4c 5f 41 4c 57 41 59 53 20 20 20 STCTRL_ALWAYS
36d40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 1
36d50 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 3../*.** CAPI3RE
36d60 46 3a 20 53 51 4c 69 74 65 20 52 75 6e 74 69 6d F: SQLite Runtim
36d70 65 20 53 74 61 74 75 73 20 7b 48 31 37 32 30 30 e Status {H17200
36d80 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 45 58 } <S60200>.** EX
36d90 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a PERIMENTAL.**.**
36da0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 This interface
36db0 69 73 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 is used to retri
36dc0 65 76 65 20 72 75 6e 74 69 6d 65 20 73 74 61 74 eve runtime stat
36dd0 75 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a us information.*
36de0 2a 20 61 62 6f 75 74 20 74 68 65 20 70 72 65 66 * about the pref
36df0 6f 72 6d 61 6e 63 65 20 6f 66 20 53 51 4c 69 74 ormance of SQLit
36e00 65 2c 20 61 6e 64 20 6f 70 74 69 6f 6e 61 6c 6c e, and optionall
36e10 79 20 74 6f 20 72 65 73 65 74 20 76 61 72 69 6f y to reset vario
36e20 75 73 0a 2a 2a 20 68 69 67 68 77 61 74 65 72 20 us.** highwater
36e30 6d 61 72 6b 73 2e 20 20 54 68 65 20 66 69 72 73 marks. The firs
36e40 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e t argument is an
36e50 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 66 6f integer code fo
36e60 72 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 66 69 r.** the specifi
36e70 63 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 6d c parameter to m
36e80 65 61 73 75 72 65 2e 20 20 52 65 63 6f 67 6e 69 easure. Recogni
36e90 7a 65 64 20 69 6e 74 65 67 65 72 20 63 6f 64 65 zed integer code
36ea0 73 0a 2a 2a 20 61 72 65 20 6f 66 20 74 68 65 20 s.** are of the
36eb0 66 6f 72 6d 20 5b 53 51 4c 49 54 45 5f 53 54 41 form [SQLITE_STA
36ec0 54 55 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 20 TUS_MEMORY_USED
36ed0 7c 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f | SQLITE_STATUS_
36ee0 2e 2e 2e 5d 2e 0a 2a 2a 20 54 68 65 20 63 75 72 ...]..** The cur
36ef0 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 74 68 rent value of th
36f00 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 72 e parameter is r
36f10 65 74 75 72 6e 65 64 20 69 6e 74 6f 20 2a 70 43 eturned into *pC
36f20 75 72 72 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 68 urrent..** The h
36f30 69 67 68 65 73 74 20 72 65 63 6f 72 64 65 64 20 ighest recorded
36f40 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 value is returne
36f50 64 20 69 6e 20 2a 70 48 69 67 68 77 61 74 65 72 d in *pHighwater
36f60 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 72 65 73 . If the.** res
36f70 65 74 46 6c 61 67 20 69 73 20 74 72 75 65 2c 20 etFlag is true,
36f80 74 68 65 6e 20 74 68 65 20 68 69 67 68 65 73 74 then the highest
36f90 20 72 65 63 6f 72 64 20 76 61 6c 75 65 20 69 73 record value is
36fa0 20 72 65 73 65 74 20 61 66 74 65 72 0a 2a 2a 20 reset after.**
36fb0 2a 70 48 69 67 68 77 61 74 65 72 20 69 73 20 77 *pHighwater is w
36fc0 72 69 74 74 65 6e 2e 20 53 6f 6d 65 20 70 61 72 ritten. Some par
36fd0 61 6d 65 74 65 72 73 20 64 6f 20 6e 6f 74 20 72 ameters do not r
36fe0 65 63 6f 72 64 20 74 68 65 20 68 69 67 68 65 73 ecord the highes
36ff0 74 0a 2a 2a 20 76 61 6c 75 65 2e 20 20 46 6f 72 t.** value. For
37000 20 74 68 6f 73 65 20 70 61 72 61 6d 65 74 65 72 those parameter
37010 73 0a 2a 2a 20 6e 6f 74 68 69 6e 67 20 69 73 20 s.** nothing is
37020 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 48 written into *pH
37030 69 67 68 77 61 74 65 72 20 61 6e 64 20 74 68 65 ighwater and the
37040 20 72 65 73 65 74 46 6c 61 67 20 69 73 20 69 67 resetFlag is ig
37050 6e 6f 72 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 20 nored..** Other
37060 70 61 72 61 6d 65 74 65 72 73 20 72 65 63 6f 72 parameters recor
37070 64 20 6f 6e 6c 79 20 74 68 65 20 68 69 67 68 77 d only the highw
37080 61 74 65 72 20 6d 61 72 6b 20 61 6e 64 20 6e 6f ater mark and no
37090 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a t the current.**
370a0 20 76 61 6c 75 65 2e 20 20 46 6f 72 20 74 68 65 value. For the
370b0 73 65 20 6c 61 74 74 65 72 20 70 61 72 61 6d 65 se latter parame
370c0 74 65 72 73 20 6e 6f 74 68 69 6e 67 20 69 73 20 ters nothing is
370d0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 43 written into *pC
370e0 75 72 72 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 urrent..**.** Th
370f0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 is routine retur
37100 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 20 6f 6e 20 ns SQLITE_OK on
37110 73 75 63 63 65 73 73 20 61 6e 64 20 61 20 6e 6f success and a no
37120 6e 2d 7a 65 72 6f 0a 2a 2a 20 5b 65 72 72 6f 72 n-zero.** [error
37130 20 63 6f 64 65 5d 20 6f 6e 20 66 61 69 6c 75 72 code] on failur
37140 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f e..**.** This ro
37150 75 74 69 6e 65 20 69 73 20 74 68 72 65 61 64 73 utine is threads
37160 61 66 65 20 62 75 74 20 69 73 20 6e 6f 74 20 61 afe but is not a
37170 74 6f 6d 69 63 2e 20 20 54 68 69 73 20 72 6f 75 tomic. This rou
37180 74 69 6e 65 20 63 61 6e 0a 2a 2a 20 63 61 6c 6c tine can.** call
37190 65 64 20 77 68 69 6c 65 20 6f 74 68 65 72 20 74 ed while other t
371a0 68 72 65 61 64 73 20 61 72 65 20 72 75 6e 6e 69 hreads are runni
371b0 6e 67 20 74 68 65 20 73 61 6d 65 20 6f 72 20 64 ng the same or d
371c0 69 66 66 65 72 65 6e 74 20 53 51 4c 69 74 65 0a ifferent SQLite.
371d0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 ** interfaces.
371e0 48 6f 77 65 76 65 72 20 74 68 65 20 76 61 6c 75 However the valu
371f0 65 73 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a es returned in *
37200 70 43 75 72 72 65 6e 74 20 61 6e 64 0a 2a 2a 20 pCurrent and.**
37210 2a 70 48 69 67 68 77 61 74 65 72 20 72 65 66 6c *pHighwater refl
37220 65 63 74 20 74 68 65 20 73 74 61 74 75 73 20 6f ect the status o
37230 66 20 53 51 4c 69 74 65 20 61 74 20 64 69 66 66 f SQLite at diff
37240 65 72 65 6e 74 20 70 6f 69 6e 74 73 20 69 6e 20 erent points in
37250 74 69 6d 65 0a 2a 2a 20 61 6e 64 20 69 74 20 69 time.** and it i
37260 73 20 70 6f 73 73 69 62 6c 65 20 74 68 61 74 20 s possible that
37270 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 6d another thread m
37280 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 ight change the
37290 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 20 parameter.** in
372a0 62 65 74 77 65 65 6e 20 74 68 65 20 74 69 6d 65 between the time
372b0 73 20 77 68 65 6e 20 2a 70 43 75 72 72 65 6e 74 s when *pCurrent
372c0 20 61 6e 64 20 2a 70 48 69 67 68 77 61 74 65 72 and *pHighwater
372d0 20 61 72 65 20 77 72 69 74 74 65 6e 2e 0a 2a 2a are written..**
372e0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
372f0 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 qlite3_db_status
37300 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 ()].*/.SQLITE_EX
37310 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 PERIMENTAL int s
37320 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 69 6e qlite3_status(in
37330 74 20 6f 70 2c 20 69 6e 74 20 2a 70 43 75 72 72 t op, int *pCurr
37340 65 6e 74 2c 20 69 6e 74 20 2a 70 48 69 67 68 77 ent, int *pHighw
37350 61 74 65 72 2c 20 69 6e 74 20 72 65 73 65 74 46 ater, int resetF
37360 6c 61 67 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 lag);.../*.** CA
37370 50 49 33 52 45 46 3a 20 53 74 61 74 75 73 20 50 PI3REF: Status P
37380 61 72 61 6d 65 74 65 72 73 20 7b 48 31 37 32 35 arameters {H1725
37390 30 7d 20 3c 48 31 37 32 30 30 3e 0a 2a 2a 20 45 0} <H17200>.** E
373a0 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a XPERIMENTAL.**.*
373b0 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 * These integer
373c0 63 6f 6e 73 74 61 6e 74 73 20 64 65 73 69 67 6e constants design
373d0 61 74 65 20 76 61 72 69 6f 75 73 20 72 75 6e 2d ate various run-
373e0 74 69 6d 65 20 73 74 61 74 75 73 20 70 61 72 61 time status para
373f0 6d 65 74 65 72 73 0a 2a 2a 20 74 68 61 74 20 63 meters.** that c
37400 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 62 an be returned b
37410 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 y [sqlite3_statu
37420 73 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e s()]..**.** <dl>
37430 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 .** <dt>SQLITE_S
37440 54 41 54 55 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 TATUS_MEMORY_USE
37450 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 D</dt>.** <dd>Th
37460 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 is parameter is
37470 74 68 65 20 63 75 72 72 65 6e 74 20 61 6d 6f 75 the current amou
37480 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 20 63 68 65 nt of memory che
37490 63 6b 65 64 20 6f 75 74 0a 2a 2a 20 75 73 69 6e cked out.** usin
374a0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f g [sqlite3_mallo
374b0 63 28 29 5d 2c 20 65 69 74 68 65 72 20 64 69 72 c()], either dir
374c0 65 63 74 6c 79 20 6f 72 20 69 6e 64 69 72 65 63 ectly or indirec
374d0 74 6c 79 2e 20 20 54 68 65 0a 2a 2a 20 66 69 67 tly. The.** fig
374e0 75 72 65 20 69 6e 63 6c 75 64 65 73 20 63 61 6c ure includes cal
374f0 6c 73 20 6d 61 64 65 20 74 6f 20 5b 73 71 6c 69 ls made to [sqli
37500 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 79 te3_malloc()] by
37510 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
37520 0a 2a 2a 20 61 6e 64 20 69 6e 74 65 72 6e 61 6c .** and internal
37530 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 20 62 79 memory usage by
37540 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 the SQLite libr
37550 61 72 79 2e 20 20 53 63 72 61 74 63 68 20 6d 65 ary. Scratch me
37560 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 6c mory.** controll
37570 65 64 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f ed by [SQLITE_CO
37580 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e NFIG_SCRATCH] an
37590 64 20 61 75 78 69 6c 69 61 72 79 20 70 61 67 65 d auxiliary page
375a0 2d 63 61 63 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 -cache.** memory
375b0 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 5b controlled by [
375c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 SQLITE_CONFIG_PA
375d0 47 45 43 41 43 48 45 5d 20 69 73 20 6e 6f 74 20 GECACHE] is not
375e0 69 6e 63 6c 75 64 65 64 20 69 6e 0a 2a 2a 20 74 included in.** t
375f0 68 69 73 20 70 61 72 61 6d 65 74 65 72 2e 20 20 his parameter.
37600 54 68 65 20 61 6d 6f 75 6e 74 20 72 65 74 75 72 The amount retur
37610 6e 65 64 20 69 73 20 74 68 65 20 73 75 6d 20 6f ned is the sum o
37620 66 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e f the allocation
37630 0a 2a 2a 20 73 69 7a 65 73 20 61 73 20 72 65 70 .** sizes as rep
37640 6f 72 74 65 64 20 62 79 20 74 68 65 20 78 53 69 orted by the xSi
37650 7a 65 20 6d 65 74 68 6f 64 20 69 6e 20 5b 73 71 ze method in [sq
37660 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
37670 73 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c s].</dd>.**.** <
37680 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 dt>SQLITE_STATUS
37690 5f 4d 41 4c 4c 4f 43 5f 53 49 5a 45 3c 2f 64 74 _MALLOC_SIZE</dt
376a0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 >.** <dd>This pa
376b0 72 61 6d 65 74 65 72 20 72 65 63 6f 72 64 73 20 rameter records
376c0 74 68 65 20 6c 61 72 67 65 73 74 20 6d 65 6d 6f the largest memo
376d0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 ry allocation re
376e0 71 75 65 73 74 0a 2a 2a 20 68 61 6e 64 65 64 20 quest.** handed
376f0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c to [sqlite3_mall
37700 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 oc()] or [sqlite
37710 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 28 6f 72 3_realloc()] (or
37720 20 74 68 65 69 72 0a 2a 2a 20 69 6e 74 65 72 6e their.** intern
37730 61 6c 20 65 71 75 69 76 61 6c 65 6e 74 73 29 2e al equivalents).
37740 20 20 4f 6e 6c 79 20 74 68 65 20 76 61 6c 75 65 Only the value
37750 20 72 65 74 75 72 6e 65 64 20 69 6e 20 74 68 65 returned in the
37760 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74 65 72 20 .** *pHighwater
37770 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 parameter to [sq
37780 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 20 lite3_status()]
37790 69 73 20 6f 66 20 69 6e 74 65 72 65 73 74 2e 20 is of interest.
377a0 20 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 77 .** The value w
377b0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 ritten into the
377c0 2a 70 43 75 72 72 65 6e 74 20 70 61 72 61 6d 65 *pCurrent parame
377d0 74 65 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ter is undefined
377e0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
377f0 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 >SQLITE_STATUS_P
37800 41 47 45 43 41 43 48 45 5f 55 53 45 44 3c 2f 64 AGECACHE_USED</d
37810 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 t>.** <dd>This p
37820 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 arameter returns
37830 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 the number of p
37840 61 67 65 73 20 75 73 65 64 20 6f 75 74 20 6f 66 ages used out of
37850 20 74 68 65 0a 2a 2a 20 5b 70 61 67 65 63 61 63 the.** [pagecac
37860 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
37870 74 6f 72 5d 20 74 68 61 74 20 77 61 73 20 63 6f tor] that was co
37880 6e 66 69 67 75 72 65 64 20 75 73 69 6e 67 20 0a nfigured using .
37890 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ** [SQLITE_CONFI
378a0 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 20 20 54 G_PAGECACHE]. T
378b0 68 65 0a 2a 2a 20 76 61 6c 75 65 20 72 65 74 75 he.** value retu
378c0 72 6e 65 64 20 69 73 20 69 6e 20 70 61 67 65 73 rned is in pages
378d0 2c 20 6e 6f 74 20 69 6e 20 62 79 74 65 73 2e 3c , not in bytes.<
378e0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
378f0 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 QLITE_STATUS_PAG
37900 45 43 41 43 48 45 5f 4f 56 45 52 46 4c 4f 57 3c ECACHE_OVERFLOW<
37910 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 /dt>.** <dd>This
37920 20 70 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 parameter retur
37930 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
37940 20 62 79 74 65 73 20 6f 66 20 70 61 67 65 20 63 bytes of page c
37950 61 63 68 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 ache.** allocati
37960 6f 6e 20 77 68 69 63 68 20 63 6f 75 6c 64 20 6e on which could n
37970 6f 74 20 62 65 20 73 74 61 74 69 73 66 69 65 64 ot be statisfied
37980 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f by the [SQLITE_
37990 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 CONFIG_PAGECACHE
379a0 5d 0a 2a 2a 20 62 75 66 66 65 72 20 61 6e 64 20 ].** buffer and
379b0 77 68 65 72 65 20 66 6f 72 63 65 64 20 74 6f 20 where forced to
379c0 6f 76 65 72 66 6c 6f 77 20 74 6f 20 5b 73 71 6c overflow to [sql
379d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 ite3_malloc()].
379e0 20 54 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 The.** returned
379f0 20 76 61 6c 75 65 20 69 6e 63 6c 75 64 65 73 20 value includes
37a00 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 74 68 61 74 allocations that
37a10 20 6f 76 65 72 66 6c 6f 77 65 64 20 62 65 63 61 overflowed beca
37a20 75 73 65 20 74 68 65 79 0a 2a 2a 20 77 68 65 72 use they.** wher
37a30 65 20 74 6f 6f 20 6c 61 72 67 65 20 28 74 68 65 e too large (the
37a40 79 20 77 65 72 65 20 6c 61 72 67 65 72 20 74 68 y were larger th
37a50 61 6e 20 74 68 65 20 22 73 7a 22 20 70 61 72 61 an the "sz" para
37a60 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c meter to.** [SQL
37a70 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 ITE_CONFIG_PAGEC
37a80 41 43 48 45 5d 29 20 61 6e 64 20 61 6c 6c 6f 63 ACHE]) and alloc
37a90 61 74 69 6f 6e 73 20 74 68 61 74 20 6f 76 65 72 ations that over
37aa0 66 6c 6f 77 65 64 20 62 65 63 61 75 73 65 0a 2a flowed because.*
37ab0 2a 20 6e 6f 20 73 70 61 63 65 20 77 61 73 20 6c * no space was l
37ac0 65 66 74 20 69 6e 20 74 68 65 20 70 61 67 65 20 eft in the page
37ad0 63 61 63 68 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a cache.</dd>.**.*
37ae0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 * <dt>SQLITE_STA
37af0 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f 53 49 TUS_PAGECACHE_SI
37b00 5a 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 ZE</dt>.** <dd>T
37b10 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 his parameter re
37b20 63 6f 72 64 73 20 74 68 65 20 6c 61 72 67 65 73 cords the larges
37b30 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 t memory allocat
37b40 69 6f 6e 20 72 65 71 75 65 73 74 0a 2a 2a 20 68 ion request.** h
37b50 61 6e 64 65 64 20 74 6f 20 5b 70 61 67 65 63 61 anded to [pageca
37b60 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 che memory alloc
37b70 61 74 6f 72 5d 2e 20 20 4f 6e 6c 79 20 74 68 65 ator]. Only the
37b80 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
37b90 69 6e 20 74 68 65 0a 2a 2a 20 2a 70 48 69 67 68 in the.** *pHigh
37ba0 77 61 74 65 72 20 70 61 72 61 6d 65 74 65 72 20 water parameter
37bb0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 to [sqlite3_stat
37bc0 75 73 28 29 5d 20 69 73 20 6f 66 20 69 6e 74 65 us()] is of inte
37bd0 72 65 73 74 2e 20 20 0a 2a 2a 20 54 68 65 20 76 rest. .** The v
37be0 61 6c 75 65 20 77 72 69 74 74 65 6e 20 69 6e 74 alue written int
37bf0 6f 20 74 68 65 20 2a 70 43 75 72 72 65 6e 74 20 o the *pCurrent
37c00 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 6e 64 parameter is und
37c10 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a efined.</dd>.**.
37c20 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 ** <dt>SQLITE_ST
37c30 41 54 55 53 5f 53 43 52 41 54 43 48 5f 55 53 45 ATUS_SCRATCH_USE
37c40 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 D</dt>.** <dd>Th
37c50 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 74 is parameter ret
37c60 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
37c70 6f 66 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 75 of allocations u
37c80 73 65 64 20 6f 75 74 20 6f 66 20 74 68 65 0a 2a sed out of the.*
37c90 2a 20 5b 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 * [scratch memor
37ca0 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e y allocator] con
37cb0 66 69 67 75 72 65 64 20 75 73 69 6e 67 0a 2a 2a figured using.**
37cc0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
37cd0 53 43 52 41 54 43 48 5d 2e 20 20 54 68 65 20 76 SCRATCH]. The v
37ce0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 alue returned is
37cf0 20 69 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c in allocations,
37d00 20 6e 6f 74 0a 2a 2a 20 69 6e 20 62 79 74 65 73 not.** in bytes
37d10 2e 20 20 53 69 6e 63 65 20 61 20 73 69 6e 67 6c . Since a singl
37d20 65 20 74 68 72 65 61 64 20 6d 61 79 20 6f 6e 6c e thread may onl
37d30 79 20 68 61 76 65 20 6f 6e 65 20 73 63 72 61 74 y have one scrat
37d40 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a ch allocation.**
37d50 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 61 74 20 outstanding at
37d60 74 69 6d 65 2c 20 74 68 69 73 20 70 61 72 61 6d time, this param
37d70 65 74 65 72 20 61 6c 73 6f 20 72 65 70 6f 72 74 eter also report
37d80 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
37d90 74 68 72 65 61 64 73 0a 2a 2a 20 75 73 69 6e 67 threads.** using
37da0 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 scratch memory
37db0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 at the same time
37dc0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
37dd0 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 >SQLITE_STATUS_S
37de0 43 52 41 54 43 48 5f 4f 56 45 52 46 4c 4f 57 3c CRATCH_OVERFLOW<
37df0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 /dt>.** <dd>This
37e00 20 70 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 parameter retur
37e10 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
37e20 20 62 79 74 65 73 20 6f 66 20 73 63 72 61 74 63 bytes of scratc
37e30 68 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f h memory.** allo
37e40 63 61 74 69 6f 6e 20 77 68 69 63 68 20 63 6f 75 cation which cou
37e50 6c 64 20 6e 6f 74 20 62 65 20 73 74 61 74 69 73 ld not be statis
37e60 66 69 65 64 20 62 79 20 74 68 65 20 5b 53 51 4c fied by the [SQL
37e70 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 ITE_CONFIG_SCRAT
37e80 43 48 5d 0a 2a 2a 20 62 75 66 66 65 72 20 61 6e CH].** buffer an
37e90 64 20 77 68 65 72 65 20 66 6f 72 63 65 64 20 74 d where forced t
37ea0 6f 20 6f 76 65 72 66 6c 6f 77 20 74 6f 20 5b 73 o overflow to [s
37eb0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
37ec0 2e 20 20 54 68 65 20 76 61 6c 75 65 73 0a 2a 2a . The values.**
37ed0 20 72 65 74 75 72 6e 65 64 20 69 6e 63 6c 75 64 returned includ
37ee0 65 20 6f 76 65 72 66 6c 6f 77 73 20 62 65 63 61 e overflows beca
37ef0 75 73 65 20 74 68 65 20 72 65 71 75 65 73 74 65 use the requeste
37f00 64 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 77 61 73 d allocation was
37f10 20 74 6f 6f 0a 2a 2a 20 6c 61 72 67 65 72 20 28 too.** larger (
37f20 74 68 61 74 20 69 73 2c 20 62 65 63 61 75 73 65 that is, because
37f30 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 61 the requested a
37f40 6c 6c 6f 63 61 74 69 6f 6e 20 77 61 73 20 6c 61 llocation was la
37f50 72 67 65 72 20 74 68 61 6e 20 74 68 65 0a 2a 2a rger than the.**
37f60 20 22 73 7a 22 20 70 61 72 61 6d 65 74 65 72 20 "sz" parameter
37f70 74 6f 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 to [SQLITE_CONFI
37f80 47 5f 53 43 52 41 54 43 48 5d 29 20 61 6e 64 20 G_SCRATCH]) and
37f90 62 65 63 61 75 73 65 20 6e 6f 20 73 63 72 61 74 because no scrat
37fa0 63 68 20 62 75 66 66 65 72 0a 2a 2a 20 73 6c 6f ch buffer.** slo
37fb0 74 73 20 77 65 72 65 20 61 76 61 69 6c 61 62 6c ts were availabl
37fc0 65 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a e..** </dd>.**.*
37fd0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 * <dt>SQLITE_STA
37fe0 54 55 53 5f 53 43 52 41 54 43 48 5f 53 49 5a 45 TUS_SCRATCH_SIZE
37ff0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 </dt>.** <dd>Thi
38000 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 63 6f s parameter reco
38010 72 64 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 rds the largest
38020 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
38030 6e 20 72 65 71 75 65 73 74 0a 2a 2a 20 68 61 6e n request.** han
38040 64 65 64 20 74 6f 20 5b 73 63 72 61 74 63 68 20 ded to [scratch
38050 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
38060 5d 2e 20 20 4f 6e 6c 79 20 74 68 65 20 76 61 6c ]. Only the val
38070 75 65 20 72 65 74 75 72 6e 65 64 20 69 6e 20 74 ue returned in t
38080 68 65 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74 65 he.** *pHighwate
38090 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b r parameter to [
380a0 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 sqlite3_status()
380b0 5d 20 69 73 20 6f 66 20 69 6e 74 65 72 65 73 74 ] is of interest
380c0 2e 20 20 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 . .** The value
380d0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 written into th
380e0 65 20 2a 70 43 75 72 72 65 6e 74 20 70 61 72 61 e *pCurrent para
380f0 6d 65 74 65 72 20 69 73 20 75 6e 64 65 66 69 6e meter is undefin
38100 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c ed.</dd>.**.** <
38110 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 dt>SQLITE_STATUS
38120 5f 50 41 52 53 45 52 5f 53 54 41 43 4b 3c 2f 64 _PARSER_STACK</d
38130 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 t>.** <dd>This p
38140 61 72 61 6d 65 74 65 72 20 72 65 63 6f 72 64 73 arameter records
38150 20 74 68 65 20 64 65 65 70 65 73 74 20 70 61 72 the deepest par
38160 73 65 72 20 73 74 61 63 6b 2e 20 20 49 74 20 69 ser stack. It i
38170 73 20 6f 6e 6c 79 0a 2a 2a 20 6d 65 61 6e 69 6e s only.** meanin
38180 67 66 75 6c 20 69 66 20 53 51 4c 69 74 65 20 69 gful if SQLite i
38190 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 s compiled with
381a0 5b 59 59 54 52 41 43 4b 4d 41 58 53 54 41 43 4b [YYTRACKMAXSTACK
381b0 44 45 50 54 48 5d 2e 3c 2f 64 64 3e 0a 2a 2a 20 DEPTH].</dd>.**
381c0 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 </dl>.**.** New
381d0 73 74 61 74 75 73 20 70 61 72 61 6d 65 74 65 72 status parameter
381e0 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 66 s may be added f
381f0 72 6f 6d 20 74 69 6d 65 20 74 6f 20 74 69 6d 65 rom time to time
38200 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
38210 49 54 45 5f 53 54 41 54 55 53 5f 4d 45 4d 4f 52 ITE_STATUS_MEMOR
38220 59 5f 55 53 45 44 20 20 20 20 20 20 20 20 20 20 Y_USED
38230 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
38240 5f 53 54 41 54 55 53 5f 50 41 47 45 43 41 43 48 _STATUS_PAGECACH
38250 45 5f 55 53 45 44 20 20 20 20 20 20 20 31 0a 23 E_USED 1.#
38260 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 define SQLITE_ST
38270 41 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f 4f ATUS_PAGECACHE_O
38280 56 45 52 46 4c 4f 57 20 20 20 32 0a 23 64 65 66 VERFLOW 2.#def
38290 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 ine SQLITE_STATU
382a0 53 5f 53 43 52 41 54 43 48 5f 55 53 45 44 20 20 S_SCRATCH_USED
382b0 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 3.#define
382c0 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 SQLITE_STATUS_S
382d0 43 52 41 54 43 48 5f 4f 56 45 52 46 4c 4f 57 20 CRATCH_OVERFLOW
382e0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4.#define SQ
382f0 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 41 4c 4c LITE_STATUS_MALL
38300 4f 43 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 OC_SIZE
38310 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 5.#define SQLIT
38320 45 5f 53 54 41 54 55 53 5f 50 41 52 53 45 52 5f E_STATUS_PARSER_
38330 53 54 41 43 4b 20 20 20 20 20 20 20 20 20 36 0a STACK 6.
38340 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
38350 54 41 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f TATUS_PAGECACHE_
38360 53 49 5a 45 20 20 20 20 20 20 20 37 0a 23 64 65 SIZE 7.#de
38370 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 fine SQLITE_STAT
38380 55 53 5f 53 43 52 41 54 43 48 5f 53 49 5a 45 20 US_SCRATCH_SIZE
38390 20 20 20 20 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 8../*.**
383a0 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 CAPI3REF: Datab
383b0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 53 ase Connection S
383c0 74 61 74 75 73 20 7b 48 31 37 35 30 30 7d 20 3c tatus {H17500} <
383d0 53 36 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 S60200>.** EXPER
383e0 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 IMENTAL.**.** Th
383f0 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 is interface is
38400 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 used to retrieve
38410 20 72 75 6e 74 69 6d 65 20 73 74 61 74 75 73 20 runtime status
38420 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 0a 2a 2a 20 information .**
38430 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 5b about a single [
38440 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
38450 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 ion]. The first
38460 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
38470 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
38480 6e 65 63 74 69 6f 6e 20 6f 62 6a 65 63 74 20 74 nection object t
38490 6f 20 62 65 20 69 6e 74 65 72 72 6f 67 61 74 65 o be interrogate
384a0 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 d. The second a
384b0 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 74 68 rgument.** is th
384c0 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 69 e parameter to i
384d0 6e 74 65 72 72 6f 67 61 74 65 2e 20 20 43 75 72 nterrogate. Cur
384e0 72 65 6e 74 6c 79 2c 20 74 68 65 20 6f 6e 6c 79 rently, the only
384f0 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 0a 2a allowed value.*
38500 2a 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 * for the second
38510 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 5b 53 parameter is [S
38520 51 4c 49 54 45 5f 44 42 53 54 41 54 55 53 5f 4c QLITE_DBSTATUS_L
38530 4f 4f 4b 41 53 49 44 45 5f 55 53 45 44 5d 2e 0a OOKASIDE_USED]..
38540 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6f 70 ** Additional op
38550 74 69 6f 6e 73 20 77 69 6c 6c 20 6c 69 6b 65 6c tions will likel
38560 79 20 61 70 70 65 61 72 20 69 6e 20 66 75 74 75 y appear in futu
38570 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 re releases of S
38580 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 QLite..**.** The
38590 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f current value o
385a0 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 f the requested
385b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 77 72 69 parameter is wri
385c0 74 74 65 6e 20 69 6e 74 6f 20 2a 70 43 75 72 0a tten into *pCur.
385d0 2a 2a 20 61 6e 64 20 74 68 65 20 68 69 67 68 65 ** and the highe
385e0 73 74 20 69 6e 73 74 61 6e 74 61 6e 65 6f 75 73 st instantaneous
385f0 20 76 61 6c 75 65 20 69 73 20 77 72 69 74 74 65 value is writte
38600 6e 20 69 6e 74 6f 20 2a 70 48 69 77 74 72 2e 20 n into *pHiwtr.
38610 20 49 66 0a 2a 2a 20 74 68 65 20 72 65 73 65 74 If.** the reset
38620 46 6c 67 20 69 73 20 74 72 75 65 2c 20 74 68 65 Flg is true, the
38630 6e 20 74 68 65 20 68 69 67 68 65 73 74 20 69 6e n the highest in
38640 73 74 61 6e 74 61 6e 65 6f 75 73 20 76 61 6c 75 stantaneous valu
38650 65 20 69 73 0a 2a 2a 20 72 65 73 65 74 20 62 61 e is.** reset ba
38660 63 6b 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 63 ck down to the c
38670 75 72 72 65 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a urrent value..**
38680 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
38690 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d qlite3_status()]
386a0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 and [sqlite3_st
386b0 6d 74 5f 73 74 61 74 75 73 28 29 5d 2e 0a 2a 2f mt_status()]..*/
386c0 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 .SQLITE_EXPERIME
386d0 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 NTAL int sqlite3
386e0 5f 64 62 5f 73 74 61 74 75 73 28 73 71 6c 69 74 _db_status(sqlit
386f0 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 69 6e 74 e3*, int op, int
38700 20 2a 70 43 75 72 2c 20 69 6e 74 20 2a 70 48 69 *pCur, int *pHi
38710 77 74 72 2c 20 69 6e 74 20 72 65 73 65 74 46 6c wtr, int resetFl
38720 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 g);../*.** CAPI3
38730 52 45 46 3a 20 53 74 61 74 75 73 20 50 61 72 61 REF: Status Para
38740 6d 65 74 65 72 73 20 66 6f 72 20 64 61 74 61 62 meters for datab
38750 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 ase connections
38760 7b 48 31 37 35 32 30 7d 20 3c 48 31 37 35 30 30 {H17520} <H17500
38770 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 >.** EXPERIMENTA
38780 4c 0a 2a 2a 0a 2a 2a 20 53 74 61 74 75 73 20 76 L.**.** Status v
38790 65 72 62 73 20 66 6f 72 20 5b 73 71 6c 69 74 65 erbs for [sqlite
387a0 33 5f 64 62 5f 73 74 61 74 75 73 28 29 5d 2e 0a 3_db_status()]..
387b0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 **.** <dl>.** <d
387c0 74 3e 53 51 4c 49 54 45 5f 44 42 53 54 41 54 55 t>SQLITE_DBSTATU
387d0 53 5f 4c 4f 4f 4b 41 53 49 44 45 5f 55 53 45 44 S_LOOKASIDE_USED
387e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 </dt>.** <dd>Thi
387f0 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 74 75 s parameter retu
38800 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
38810 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f f lookaside memo
38820 72 79 20 73 6c 6f 74 73 20 63 75 72 72 65 6e 74 ry slots current
38830 6c 79 0a 2a 2a 20 63 68 65 63 6b 65 64 20 6f 75 ly.** checked ou
38840 74 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e t.</dd>.** </dl>
38850 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
38860 54 45 5f 44 42 53 54 41 54 55 53 5f 4c 4f 4f 4b TE_DBSTATUS_LOOK
38870 41 53 49 44 45 5f 55 53 45 44 20 20 20 20 20 30 ASIDE_USED 0
38880 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 .../*.** CAPI3RE
38890 46 3a 20 50 72 65 70 61 72 65 64 20 53 74 61 74 F: Prepared Stat
388a0 65 6d 65 6e 74 20 53 74 61 74 75 73 20 7b 48 31 ement Status {H1
388b0 37 35 35 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 7550} <S60200>.*
388c0 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
388d0 2a 0a 2a 2a 20 45 61 63 68 20 70 72 65 70 61 72 *.** Each prepar
388e0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6d 61 69 ed statement mai
388f0 6e 74 61 69 6e 73 20 76 61 72 69 6f 75 73 0a 2a ntains various.*
38900 2a 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 53 54 * [SQLITE_STMTST
38910 41 54 55 53 5f 53 4f 52 54 20 7c 20 63 6f 75 6e ATUS_SORT | coun
38920 74 65 72 73 5d 20 74 68 61 74 20 6d 65 61 73 75 ters] that measu
38930 72 65 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a re the number.**
38940 20 6f 66 20 74 69 6d 65 73 20 69 74 20 68 61 73 of times it has
38950 20 70 65 72 66 6f 72 6d 65 64 20 73 70 65 63 69 performed speci
38960 66 69 63 20 6f 70 65 72 61 74 69 6f 6e 73 2e 20 fic operations.
38970 20 54 68 65 73 65 20 63 6f 75 6e 74 65 72 73 20 These counters
38980 63 61 6e 0a 2a 2a 20 62 65 20 75 73 65 64 20 74 can.** be used t
38990 6f 20 6d 6f 6e 69 74 6f 72 20 74 68 65 20 70 65 o monitor the pe
389a0 72 66 6f 72 6d 61 6e 63 65 20 63 68 61 72 61 63 rformance charac
389b0 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 teristics of the
389c0 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 prepared.** sta
389d0 74 65 6d 65 6e 74 73 2e 20 20 46 6f 72 20 65 78 tements. For ex
389e0 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 6e 75 ample, if the nu
389f0 6d 62 65 72 20 6f 66 20 74 61 62 6c 65 20 73 74 mber of table st
38a00 65 70 73 20 67 72 65 61 74 6c 79 20 65 78 63 65 eps greatly exce
38a10 65 64 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 eds.** the numbe
38a20 72 20 6f 66 20 74 61 62 6c 65 20 73 65 61 72 63 r of table searc
38a30 68 65 73 20 6f 72 20 72 65 73 75 6c 74 20 72 6f hes or result ro
38a40 77 73 2c 20 74 68 61 74 20 77 6f 75 6c 64 20 74 ws, that would t
38a50 65 6e 64 20 74 6f 20 69 6e 64 69 63 61 74 65 0a end to indicate.
38a60 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 65 70 ** that the prep
38a70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 ared statement i
38a80 73 20 75 73 69 6e 67 20 61 20 66 75 6c 6c 20 74 s using a full t
38a90 61 62 6c 65 20 73 63 61 6e 20 72 61 74 68 65 72 able scan rather
38aa0 20 74 68 61 6e 0a 2a 2a 20 61 6e 20 69 6e 64 65 than.** an inde
38ab0 78 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 x. .**.** This
38ac0 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 interface is use
38ad0 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 6e d to retrieve an
38ae0 64 20 72 65 73 65 74 20 63 6f 75 6e 74 65 72 20 d reset counter
38af0 76 61 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 61 values from.** a
38b00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
38b10 6d 65 6e 74 5d 2e 20 20 54 68 65 20 66 69 72 73 ment]. The firs
38b20 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 t argument is th
38b30 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 e prepared state
38b40 6d 65 6e 74 0a 2a 2a 20 6f 62 6a 65 63 74 20 74 ment.** object t
38b50 6f 20 62 65 20 69 6e 74 65 72 72 6f 67 61 74 65 o be interrogate
38b60 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 d. The second a
38b70 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 61 6e rgument.** is an
38b80 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 66 6f integer code fo
38b90 72 20 61 20 73 70 65 63 69 66 69 63 20 5b 53 51 r a specific [SQ
38ba0 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f LITE_STMTSTATUS_
38bb0 53 4f 52 54 20 7c 20 63 6f 75 6e 74 65 72 5d 0a SORT | counter].
38bc0 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 6f ** to be interro
38bd0 67 61 74 65 64 2e 20 0a 2a 2a 20 54 68 65 20 63 gated. .** The c
38be0 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 urrent value of
38bf0 74 68 65 20 72 65 71 75 65 73 74 65 64 20 63 6f the requested co
38c00 75 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 unter is returne
38c10 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 d..** If the res
38c20 65 74 46 6c 67 20 69 73 20 74 72 75 65 2c 20 74 etFlg is true, t
38c30 68 65 6e 20 74 68 65 20 63 6f 75 6e 74 65 72 20 hen the counter
38c40 69 73 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f is reset to zero
38c50 20 61 66 74 65 72 20 74 68 69 73 0a 2a 2a 20 69 after this.** i
38c60 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 72 65 nterface call re
38c70 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 turns..**.** See
38c80 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
38c90 73 74 61 74 75 73 28 29 5d 20 61 6e 64 20 5b 73 status()] and [s
38ca0 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 qlite3_db_status
38cb0 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 ()]..*/.SQLITE_E
38cc0 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 XPERIMENTAL int
38cd0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 73 74 61 sqlite3_stmt_sta
38ce0 74 75 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 tus(sqlite3_stmt
38cf0 2a 2c 20 69 6e 74 20 6f 70 2c 69 6e 74 20 72 65 *, int op,int re
38d00 73 65 74 46 6c 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 setFlg);../*.**
38d10 43 41 50 49 33 52 45 46 3a 20 53 74 61 74 75 73 CAPI3REF: Status
38d20 20 50 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 Parameters for
38d30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
38d40 6e 74 73 20 7b 48 31 37 35 37 30 7d 20 3c 48 31 nts {H17570} <H1
38d50 37 35 35 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 7550>.** EXPERIM
38d60 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ENTAL.**.** Thes
38d70 65 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d e preprocessor m
38d80 61 63 72 6f 73 20 64 65 66 69 6e 65 20 69 6e 74 acros define int
38d90 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 eger codes that
38da0 6e 61 6d 65 20 63 6f 75 6e 74 65 72 0a 2a 2a 20 name counter.**
38db0 76 61 6c 75 65 73 20 61 73 73 6f 63 69 61 74 65 values associate
38dc0 64 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 d with the [sqli
38dd0 74 65 33 5f 73 74 6d 74 5f 73 74 61 74 75 73 28 te3_stmt_status(
38de0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a )] interface..**
38df0 20 54 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 The meanings of
38e00 20 74 68 65 20 76 61 72 69 6f 75 73 20 63 6f 75 the various cou
38e10 6e 74 65 72 73 20 61 72 65 20 61 73 20 66 6f 6c nters are as fol
38e20 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e lows:.**.** <dl>
38e30 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 .** <dt>SQLITE_S
38e40 54 4d 54 53 54 41 54 55 53 5f 46 55 4c 4c 53 43 TMTSTATUS_FULLSC
38e50 41 4e 5f 53 54 45 50 3c 2f 64 74 3e 0a 2a 2a 20 AN_STEP</dt>.**
38e60 3c 64 64 3e 54 68 69 73 20 69 73 20 74 68 65 20 <dd>This is the
38e70 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 number of times
38e80 74 68 61 74 20 53 51 4c 69 74 65 20 68 61 73 20 that SQLite has
38e90 73 74 65 70 70 65 64 20 66 6f 72 77 61 72 64 20 stepped forward
38ea0 69 6e 0a 2a 2a 20 61 20 74 61 62 6c 65 20 61 73 in.** a table as
38eb0 20 70 61 72 74 20 6f 66 20 61 20 66 75 6c 6c 20 part of a full
38ec0 74 61 62 6c 65 20 73 63 61 6e 2e 20 20 4c 61 72 table scan. Lar
38ed0 67 65 20 6e 75 6d 62 65 72 73 20 66 6f 72 20 74 ge numbers for t
38ee0 68 69 73 20 63 6f 75 6e 74 65 72 0a 2a 2a 20 6d his counter.** m
38ef0 61 79 20 69 6e 64 69 63 61 74 65 20 6f 70 70 6f ay indicate oppo
38f00 72 74 75 6e 69 74 69 65 73 20 66 6f 72 20 70 65 rtunities for pe
38f10 72 66 6f 72 6d 61 6e 63 65 20 69 6d 70 72 6f 76 rformance improv
38f20 65 6d 65 6e 74 20 74 68 72 6f 75 67 68 20 0a 2a ement through .*
38f30 2a 20 63 61 72 65 66 75 6c 20 75 73 65 20 6f 66 * careful use of
38f40 20 69 6e 64 69 63 65 73 2e 3c 2f 64 64 3e 0a 2a indices.</dd>.*
38f50 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
38f60 53 54 4d 54 53 54 41 54 55 53 5f 53 4f 52 54 3c STMTSTATUS_SORT<
38f70 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 /dt>.** <dd>This
38f80 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
38f90 66 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e f sort operation
38fa0 73 20 74 68 61 74 20 68 61 76 65 20 6f 63 63 75 s that have occu
38fb0 72 72 65 64 2e 0a 2a 2a 20 41 20 6e 6f 6e 2d 7a rred..** A non-z
38fc0 65 72 6f 20 76 61 6c 75 65 20 69 6e 20 74 68 69 ero value in thi
38fd0 73 20 63 6f 75 6e 74 65 72 20 6d 61 79 20 69 6e s counter may in
38fe0 64 69 63 61 74 65 20 61 6e 20 6f 70 70 6f 72 74 dicate an opport
38ff0 75 6e 69 74 79 20 74 6f 0a 2a 2a 20 69 6d 70 72 unity to.** impr
39000 6f 76 65 6d 65 6e 74 20 70 65 72 66 6f 72 6d 61 ovement performa
39010 6e 63 65 20 74 68 72 6f 75 67 68 20 63 61 72 65 nce through care
39020 66 75 6c 20 75 73 65 20 6f 66 20 69 6e 64 69 63 ful use of indic
39030 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c es.</dd>.**.** <
39040 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 /dl>.*/.#define
39050 53 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 55 SQLITE_STMTSTATU
39060 53 5f 46 55 4c 4c 53 43 41 4e 5f 53 54 45 50 20 S_FULLSCAN_STEP
39070 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 1.#define SQ
39080 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f LITE_STMTSTATUS_
39090 53 4f 52 54 20 20 20 20 20 20 20 20 20 20 20 20 SORT
390a0 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 2../*.** CAPI3
390b0 52 45 46 3a 20 43 75 73 74 6f 6d 20 50 61 67 65 REF: Custom Page
390c0 20 43 61 63 68 65 20 4f 62 6a 65 63 74 0a 2a 2a Cache Object.**
390d0 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a EXPERIMENTAL.**
390e0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
390f0 70 63 61 63 68 65 20 74 79 70 65 20 69 73 20 6f pcache type is o
39100 70 61 71 75 65 2e 20 20 49 74 20 69 73 20 69 6d paque. It is im
39110 70 6c 65 6d 65 6e 74 65 64 20 62 79 0a 2a 2a 20 plemented by.**
39120 74 68 65 20 70 6c 75 67 67 61 62 6c 65 20 6d 6f the pluggable mo
39130 64 75 6c 65 2e 20 20 54 68 65 20 53 51 4c 69 74 dule. The SQLit
39140 65 20 63 6f 72 65 20 68 61 73 20 6e 6f 20 6b 6e e core has no kn
39150 6f 77 6c 65 64 67 65 20 6f 66 0a 2a 2a 20 69 74 owledge of.** it
39160 73 20 73 69 7a 65 20 6f 72 20 69 6e 74 65 72 6e s size or intern
39170 61 6c 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 al structure and
39180 20 6e 65 76 65 72 20 64 65 61 6c 73 20 77 69 74 never deals wit
39190 68 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 h the.** sqlite3
391a0 5f 70 63 61 63 68 65 20 6f 62 6a 65 63 74 20 65 _pcache object e
391b0 78 63 65 70 74 20 62 79 20 68 6f 6c 64 69 6e 67 xcept by holding
391c0 20 61 6e 64 20 70 61 73 73 69 6e 67 20 70 6f 69 and passing poi
391d0 6e 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 nters.** to the
391e0 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 object..**.** Se
391f0 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 e [sqlite3_pcach
39200 65 5f 6d 65 74 68 6f 64 73 5d 20 66 6f 72 20 61 e_methods] for a
39210 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d dditional inform
39220 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 ation..*/.typede
39230 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
39240 5f 70 63 61 63 68 65 20 73 71 6c 69 74 65 33 5f _pcache sqlite3_
39250 70 63 61 63 68 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 pcache;../*.** C
39260 41 50 49 33 52 45 46 3a 20 41 70 70 6c 69 63 61 API3REF: Applica
39270 74 69 6f 6e 20 44 65 66 69 6e 65 64 20 50 61 67 tion Defined Pag
39280 65 20 43 61 63 68 65 2e 0a 2a 2a 20 45 58 50 45 e Cache..** EXPE
39290 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 RIMENTAL.**.** T
392a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 he [sqlite3_conf
392b0 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ig]([SQLITE_CONF
392c0 49 47 5f 50 43 41 43 48 45 5d 2c 20 2e 2e 2e 29 IG_PCACHE], ...)
392d0 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 0a 2a interface can.*
392e0 2a 20 72 65 67 69 73 74 65 72 20 61 6e 20 61 6c * register an al
392f0 74 65 72 6e 61 74 69 76 65 20 70 61 67 65 20 63 ternative page c
39300 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ache implementat
39310 69 6f 6e 20 62 79 20 70 61 73 73 69 6e 67 20 69 ion by passing i
39320 6e 20 61 6e 20 0a 2a 2a 20 69 6e 73 74 61 6e 63 n an .** instanc
39330 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 e of the sqlite3
39340 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 20 _pcache_methods
39350 73 74 72 75 63 74 75 72 65 2e 20 54 68 65 20 6d structure. The m
39360 61 6a 6f 72 69 74 79 20 6f 66 20 74 68 65 20 0a ajority of the .
39370 2a 2a 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 ** heap memory u
39380 73 65 64 20 62 79 20 73 71 6c 69 74 65 20 69 73 sed by sqlite is
39390 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 67 used by the pag
393a0 65 20 63 61 63 68 65 20 74 6f 20 63 61 63 68 65 e cache to cache
393b0 20 64 61 74 61 20 72 65 61 64 20 0a 2a 2a 20 66 data read .** f
393c0 72 6f 6d 2c 20 6f 72 20 72 65 61 64 79 20 74 6f rom, or ready to
393d0 20 62 65 20 77 72 69 74 74 65 6e 20 74 6f 2c 20 be written to,
393e0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
393f0 65 2e 20 42 79 20 69 6d 70 6c 65 6d 65 6e 74 69 e. By implementi
39400 6e 67 20 61 20 0a 2a 2a 20 63 75 73 74 6f 6d 20 ng a .** custom
39410 70 61 67 65 20 63 61 63 68 65 20 75 73 69 6e 67 page cache using
39420 20 74 68 69 73 20 41 50 49 2c 20 61 6e 20 61 70 this API, an ap
39430 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 63 6f plication can co
39440 6e 74 72 6f 6c 20 6d 6f 72 65 20 0a 2a 2a 20 70 ntrol more .** p
39450 72 65 63 69 73 65 6c 79 20 74 68 65 20 61 6d 6f recisely the amo
39460 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 20 63 6f unt of memory co
39470 6e 73 75 6d 65 64 20 62 79 20 73 71 6c 69 74 65 nsumed by sqlite
39480 2c 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 , the way in whi
39490 63 68 20 0a 2a 2a 20 73 61 69 64 20 6d 65 6d 6f ch .** said memo
394a0 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 ry is allocated
394b0 61 6e 64 20 72 65 6c 65 61 73 65 64 2c 20 61 6e and released, an
394c0 64 20 74 68 65 20 70 6f 6c 69 63 69 65 73 20 75 d the policies u
394d0 73 65 64 20 74 6f 20 0a 2a 2a 20 64 65 74 65 72 sed to .** deter
394e0 6d 69 6e 65 20 65 78 61 63 74 6c 79 20 77 68 69 mine exactly whi
394f0 63 68 20 70 61 72 74 73 20 6f 66 20 61 20 64 61 ch parts of a da
39500 74 61 62 61 73 65 20 66 69 6c 65 20 61 72 65 20 tabase file are
39510 63 61 63 68 65 64 20 61 6e 64 20 66 6f 72 20 0a cached and for .
39520 2a 2a 20 68 6f 77 20 6c 6f 6e 67 2e 0a 2a 2a 0a ** how long..**.
39530 2a 2a 20 54 68 65 20 63 6f 6e 74 65 6e 74 73 20 ** The contents
39540 6f 66 20 74 68 65 20 73 74 72 75 63 74 75 72 65 of the structure
39550 20 61 72 65 20 63 6f 70 69 65 64 20 74 6f 20 61 are copied to a
39560 6e 20 69 6e 74 65 72 6e 61 6c 20 62 75 66 66 65 n internal buffe
39570 72 20 62 79 20 73 71 6c 69 74 65 0a 2a 2a 20 77 r by sqlite.** w
39580 69 74 68 69 6e 20 74 68 65 20 63 61 6c 6c 20 74 ithin the call t
39590 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 o [sqlite3_confi
395a0 67 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 g]..**.** The xI
395b0 6e 69 74 28 29 20 6d 65 74 68 6f 64 20 69 73 20 nit() method is
395c0 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 called once for
395d0 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 each call to [sq
395e0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
395f0 28 29 5d 0a 2a 2a 20 28 75 73 75 61 6c 6c 79 20 ()].** (usually
39600 6f 6e 6c 79 20 6f 6e 63 65 20 64 75 72 69 6e 67 only once during
39610 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 the lifetime of
39620 20 74 68 65 20 70 72 6f 63 65 73 73 29 2e 20 49 the process). I
39630 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 61 t is passed.** a
39640 20 63 6f 70 79 20 6f 66 20 74 68 65 20 73 71 6c copy of the sql
39650 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 ite3_pcache_meth
39660 6f 64 73 2e 70 41 72 67 20 76 61 6c 75 65 2e 20 ods.pArg value.
39670 49 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 It can be used t
39680 6f 20 73 65 74 0a 2a 2a 20 75 70 20 67 6c 6f 62 o set.** up glob
39690 61 6c 20 73 74 72 75 63 74 75 72 65 73 20 61 6e al structures an
396a0 64 20 6d 75 74 65 78 65 73 20 72 65 71 75 69 72 d mutexes requir
396b0 65 64 20 62 79 20 74 68 65 20 63 75 73 74 6f 6d ed by the custom
396c0 20 70 61 67 65 20 63 61 63 68 65 20 0a 2a 2a 20 page cache .**
396d0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 implementation.
396e0 54 68 65 20 78 53 68 75 74 64 6f 77 6e 28 29 20 The xShutdown()
396f0 6d 65 74 68 6f 64 20 69 73 20 63 61 6c 6c 65 64 method is called
39700 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 0a 2a 2a from within .**
39710 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f [sqlite3_shutdo
39720 77 6e 28 29 5d 2c 20 69 66 20 74 68 65 20 61 70 wn()], if the ap
39730 70 6c 69 63 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 plication invoke
39740 73 20 74 68 69 73 20 41 50 49 2e 20 49 74 20 63 s this API. It c
39750 61 6e 20 62 65 20 75 73 65 64 0a 2a 2a 20 74 6f an be used.** to
39760 20 63 6c 65 61 6e 20 75 70 20 61 6e 79 20 6f 75 clean up any ou
39770 74 73 74 61 6e 64 69 6e 67 20 72 65 73 6f 75 72 tstanding resour
39780 63 65 73 20 62 65 66 6f 72 65 20 70 72 6f 63 65 ces before proce
39790 73 73 20 73 68 75 74 64 6f 77 6e 2c 20 69 66 20 ss shutdown, if
397a0 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 required..**.**
397b0 54 68 65 20 78 43 72 65 61 74 65 28 29 20 6d 65 The xCreate() me
397c0 74 68 6f 64 20 69 73 20 75 73 65 64 20 74 6f 20 thod is used to
397d0 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 construct a new
397e0 63 61 63 68 65 20 69 6e 73 74 61 6e 63 65 2e 20 cache instance.
397f0 54 68 65 0a 2a 2a 20 66 69 72 73 74 20 70 61 72 The.** first par
39800 61 6d 65 74 65 72 2c 20 73 7a 50 61 67 65 2c 20 ameter, szPage,
39810 69 73 20 74 68 65 20 73 69 7a 65 20 69 6e 20 62 is the size in b
39820 79 74 65 73 20 6f 66 20 74 68 65 20 70 61 67 65 ytes of the page
39830 73 20 74 68 61 74 20 6d 75 73 74 0a 2a 2a 20 62 s that must.** b
39840 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 74 e allocated by t
39850 68 65 20 63 61 63 68 65 2e 20 73 7a 50 61 67 65 he cache. szPage
39860 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 61 20 70 will not be a p
39870 6f 77 65 72 20 6f 66 20 74 77 6f 2e 20 54 68 65 ower of two. The
39880 0a 2a 2a 20 73 65 63 6f 6e 64 20 61 72 67 75 6d .** second argum
39890 65 6e 74 2c 20 62 50 75 72 67 65 61 62 6c 65 2c ent, bPurgeable,
398a0 20 69 73 20 74 72 75 65 20 69 66 20 74 68 65 20 is true if the
398b0 63 61 63 68 65 20 62 65 69 6e 67 20 63 72 65 61 cache being crea
398c0 74 65 64 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 75 ted will.** be u
398d0 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74 sed to cache dat
398e0 61 62 61 73 65 20 70 61 67 65 73 20 72 65 61 64 abase pages read
398f0 20 66 72 6f 6d 20 61 20 66 69 6c 65 20 73 74 6f from a file sto
39900 72 65 64 20 6f 6e 20 64 69 73 6b 2c 20 6f 72 0a red on disk, or.
39910 2a 2a 20 66 61 6c 73 65 20 69 66 20 69 74 20 69 ** false if it i
39920 73 20 75 73 65 64 20 66 6f 72 20 61 6e 20 69 6e s used for an in
39930 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 -memory database
39940 2e 20 54 68 65 20 63 61 63 68 65 20 69 6d 70 6c . The cache impl
39950 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 64 6f ementation.** do
39960 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 20 64 es not have to d
39970 6f 20 61 6e 79 74 68 69 6e 67 20 73 70 65 63 69 o anything speci
39980 61 6c 20 62 61 73 65 64 20 6f 6e 20 74 68 65 20 al based on the
39990 76 61 6c 75 65 20 6f 66 20 62 50 75 72 67 65 61 value of bPurgea
399a0 62 6c 65 2c 0a 2a 2a 20 69 74 20 69 73 20 70 75 ble,.** it is pu
399b0 72 65 6c 79 20 61 64 76 69 73 6f 72 79 2e 20 0a rely advisory. .
399c0 2a 2a 0a 2a 2a 20 54 68 65 20 78 43 61 63 68 65 **.** The xCache
399d0 73 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 6d 61 size() method ma
399e0 79 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 y be called at a
399f0 6e 79 20 74 69 6d 65 20 62 79 20 53 51 4c 69 74 ny time by SQLit
39a00 65 20 74 6f 20 73 65 74 20 74 68 65 0a 2a 2a 20 e to set the.**
39a10 73 75 67 67 65 73 74 65 64 20 6d 61 78 69 6d 75 suggested maximu
39a20 6d 20 63 61 63 68 65 2d 73 69 7a 65 20 28 6e 75 m cache-size (nu
39a30 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 73 74 mber of pages st
39a40 6f 72 65 64 20 62 79 29 20 74 68 65 20 63 61 63 ored by) the cac
39a50 68 65 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 70 he.** instance p
39a60 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 assed as the fir
39a70 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 69 st argument. Thi
39a80 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 63 s is the value c
39a90 6f 6e 66 69 67 75 72 65 64 20 75 73 69 6e 67 0a onfigured using.
39aa0 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 22 5b ** the SQLite "[
39ab0 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a PRAGMA cache_siz
39ac0 65 5d 22 20 63 6f 6d 6d 61 6e 64 2e 20 41 73 20 e]" command. As
39ad0 77 69 74 68 20 74 68 65 20 62 50 75 72 67 65 61 with the bPurgea
39ae0 62 6c 65 20 70 61 72 61 6d 65 74 65 72 2c 0a 2a ble parameter,.*
39af0 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 * the implementa
39b00 74 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65 71 75 tion is not requ
39b10 69 72 65 64 20 74 6f 20 64 6f 20 61 6e 79 74 68 ired to do anyth
39b20 69 6e 67 20 73 70 65 63 69 61 6c 20 77 69 74 68 ing special with
39b30 20 74 68 69 73 0a 2a 2a 20 76 61 6c 75 65 2c 20 this.** value,
39b40 69 74 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f it is advisory o
39b50 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 nly..**.** The x
39b60 50 61 67 65 63 6f 75 6e 74 28 29 20 6d 65 74 68 Pagecount() meth
39b70 6f 64 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e od should return
39b80 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 the number of p
39b90 61 67 65 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a ages currently.*
39ba0 2a 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 * stored in the
39bb0 63 61 63 68 65 20 73 75 70 70 6c 69 65 64 20 61 cache supplied a
39bc0 73 20 61 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a s an argument..*
39bd0 2a 20 0a 2a 2a 20 54 68 65 20 78 46 65 74 63 68 * .** The xFetch
39be0 28 29 20 6d 65 74 68 6f 64 20 69 73 20 75 73 65 () method is use
39bf0 64 20 74 6f 20 66 65 74 63 68 20 61 20 70 61 67 d to fetch a pag
39c00 65 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 e and return a p
39c10 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e 20 0a 2a ointer to it. .*
39c20 2a 20 41 20 27 70 61 67 65 27 2c 20 69 6e 20 74 * A 'page', in t
39c30 68 69 73 20 63 6f 6e 74 65 78 74 2c 20 69 73 20 his context, is
39c40 61 20 62 75 66 66 65 72 20 6f 66 20 73 7a 50 61 a buffer of szPa
39c50 67 65 20 62 79 74 65 73 20 61 6c 69 67 6e 65 64 ge bytes aligned
39c60 20 61 74 20 61 6e 0a 2a 2a 20 38 2d 62 79 74 65 at an.** 8-byte
39c70 20 62 6f 75 6e 64 61 72 79 2e 20 54 68 65 20 70 boundary. The p
39c80 61 67 65 20 74 6f 20 62 65 20 66 65 74 63 68 65 age to be fetche
39c90 64 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 20 d is determined
39ca0 62 79 20 74 68 65 20 6b 65 79 2e 20 54 68 65 0a by the key. The.
39cb0 2a 2a 20 6d 69 6d 69 6d 75 6d 20 6b 65 79 20 76 ** mimimum key v
39cc0 61 6c 75 65 20 69 73 20 31 2e 20 41 66 74 65 72 alue is 1. After
39cd0 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 74 it has been ret
39ce0 72 69 65 76 65 64 20 75 73 69 6e 67 20 78 46 65 rieved using xFe
39cf0 74 63 68 2c 20 74 68 65 20 70 61 67 65 20 0a 2a tch, the page .*
39d00 2a 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 * is considered
39d10 74 6f 20 62 65 20 70 69 6e 6e 65 64 2e 0a 2a 2a to be pinned..**
39d20 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 71 75 65 .** If the reque
39d30 73 74 65 64 20 70 61 67 65 20 69 73 20 61 6c 72 sted page is alr
39d40 65 61 64 79 20 69 6e 20 74 68 65 20 70 61 67 65 eady in the page
39d50 20 63 61 63 68 65 2c 20 74 68 65 6e 20 61 20 70 cache, then a p
39d60 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 ointer to.** the
39d70 20 63 61 63 68 65 64 20 62 75 66 66 65 72 20 73 cached buffer s
39d80 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 hould be returne
39d90 64 20 77 69 74 68 20 69 74 73 20 63 6f 6e 74 65 d with its conte
39da0 6e 74 73 20 69 6e 74 61 63 74 2e 20 49 66 20 74 nts intact. If t
39db0 68 65 0a 2a 2a 20 70 61 67 65 20 69 73 20 6e 6f he.** page is no
39dc0 74 20 61 6c 72 65 61 64 79 20 69 6e 20 74 68 65 t already in the
39dd0 20 63 61 63 68 65 2c 20 74 68 65 6e 20 74 68 65 cache, then the
39de0 20 65 78 70 65 63 74 65 64 20 62 65 68 61 76 69 expected behavi
39df0 6f 75 72 20 6f 66 20 74 68 65 0a 2a 2a 20 63 61 our of the.** ca
39e00 63 68 65 20 69 73 20 64 65 74 65 72 6d 69 6e 65 che is determine
39e10 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 6f d by the value o
39e20 66 20 74 68 65 20 63 72 65 61 74 65 46 6c 61 67 f the createFlag
39e30 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 parameter passe
39e40 64 0a 2a 2a 20 74 6f 20 78 46 65 74 63 68 2c 20 d.** to xFetch,
39e50 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 according to the
39e60 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 following table
39e70 3a 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 :.**.** <table b
39e80 6f 72 64 65 72 3d 31 20 77 69 64 74 68 3d 38 35 order=1 width=85
39e90 25 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 3e 0a % align=center>.
39ea0 2a 2a 20 20 20 3c 74 72 3e 3c 74 68 3e 63 72 65 ** <tr><th>cre
39eb0 61 74 65 46 6c 61 67 3c 74 68 3e 45 78 70 65 63 ateFlag<th>Expec
39ec0 74 65 64 20 42 65 68 61 76 69 6f 75 72 0a 2a 2a ted Behaviour.**
39ed0 20 20 20 3c 74 72 3e 3c 74 64 3e 30 3c 74 64 3e <tr><td>0<td>
39ee0 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 72 NULL should be r
39ef0 65 74 75 72 6e 65 64 2e 20 4e 6f 20 6e 65 77 20 eturned. No new
39f00 63 61 63 68 65 20 65 6e 74 72 79 20 69 73 20 63 cache entry is c
39f10 72 65 61 74 65 64 2e 0a 2a 2a 20 20 20 3c 74 72 reated..** <tr
39f20 3e 3c 74 64 3e 31 3c 74 64 3e 49 66 20 63 72 65 ><td>1<td>If cre
39f30 61 74 65 46 6c 61 67 20 69 73 20 73 65 74 20 74 ateFlag is set t
39f40 6f 20 31 2c 20 74 68 69 73 20 69 6e 64 69 63 61 o 1, this indica
39f50 74 65 73 20 74 68 61 74 20 0a 2a 2a 20 20 20 20 tes that .**
39f60 20 20 20 20 20 20 20 20 20 20 20 20 53 51 4c 69 SQLi
39f70 74 65 20 69 73 20 68 6f 6c 64 69 6e 67 20 70 69 te is holding pi
39f80 6e 6e 65 64 20 70 61 67 65 73 20 74 68 61 74 20 nned pages that
39f90 63 61 6e 20 62 65 20 75 6e 70 69 6e 6e 65 64 0a can be unpinned.
39fa0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 **
39fb0 20 20 62 79 20 77 72 69 74 69 6e 67 20 74 68 65 by writing the
39fc0 69 72 20 63 6f 6e 74 65 6e 74 73 20 74 6f 20 74 ir contents to t
39fd0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
39fe0 20 28 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 (a.**
39ff0 20 20 20 20 20 20 72 65 6c 61 74 69 76 65 6c 79 relatively
3a000 20 65 78 70 65 6e 73 69 76 65 20 6f 70 65 72 61 expensive opera
3a010 74 69 6f 6e 29 2e 20 49 6e 20 74 68 69 73 20 73 tion). In this s
3a020 69 74 75 61 74 69 6f 6e 20 74 68 65 0a 2a 2a 20 ituation the.**
3a030 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 63 c
3a040 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ache implementat
3a050 69 6f 6e 20 68 61 73 20 74 77 6f 20 63 68 6f 69 ion has two choi
3a060 63 65 73 3a 20 69 74 20 63 61 6e 20 72 65 74 75 ces: it can retu
3a070 72 6e 20 4e 55 4c 4c 2c 0a 2a 2a 20 20 20 20 20 rn NULL,.**
3a080 20 20 20 20 20 20 20 20 20 20 20 69 6e 20 77 68 in wh
3a090 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 ich case SQLite
3a0a0 77 69 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f 20 will attempt to
3a0b0 75 6e 70 69 6e 20 6f 6e 65 20 6f 72 20 6d 6f 72 unpin one or mor
3a0c0 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 e .**
3a0d0 20 20 20 20 20 70 61 67 65 73 20 62 65 66 6f 72 pages befor
3a0e0 65 20 72 65 2d 72 65 71 75 65 73 74 69 6e 67 20 e re-requesting
3a0f0 74 68 65 20 73 61 6d 65 20 70 61 67 65 2c 20 6f the same page, o
3a100 72 20 69 74 20 63 61 6e 0a 2a 2a 20 20 20 20 20 r it can.**
3a110 20 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 alloc
3a120 61 74 65 20 61 20 6e 65 77 20 70 61 67 65 20 61 ate a new page a
3a130 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e nd return a poin
3a140 74 65 72 20 74 6f 20 69 74 2e 20 49 66 20 61 20 ter to it. If a
3a150 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 new.**
3a160 20 20 20 20 20 20 70 61 67 65 20 69 73 20 61 6c page is al
3a170 6c 6f 63 61 74 65 64 2c 20 74 68 65 6e 20 74 68 located, then th
3a180 65 20 66 69 72 73 74 20 73 69 7a 65 6f 66 28 76 e first sizeof(v
3a190 6f 69 64 2a 29 20 62 79 74 65 73 20 6f 66 0a 2a oid*) bytes of.*
3a1a0 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 *
3a1b0 20 69 74 20 28 61 74 20 6c 65 61 73 74 29 20 6d it (at least) m
3a1c0 75 73 74 20 62 65 20 7a 65 72 6f 65 64 20 62 65 ust be zeroed be
3a1d0 66 6f 72 65 20 69 74 20 69 73 20 72 65 74 75 72 fore it is retur
3a1e0 6e 65 64 2e 0a 2a 2a 20 20 20 3c 74 72 3e 3c 74 ned..** <tr><t
3a1f0 64 3e 32 3c 74 64 3e 49 66 20 63 72 65 61 74 65 d>2<td>If create
3a200 46 6c 61 67 20 69 73 20 73 65 74 20 74 6f 20 32 Flag is set to 2
3a210 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 69 73 , then SQLite is
3a220 20 6e 6f 74 20 68 6f 6c 64 69 6e 67 20 61 6e 79 not holding any
3a230 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 .**
3a240 20 20 20 70 69 6e 6e 65 64 20 70 61 67 65 73 20 pinned pages
3a250 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
3a260 74 68 65 20 73 70 65 63 69 66 69 63 20 63 61 63 the specific cac
3a270 68 65 20 70 61 73 73 65 64 0a 2a 2a 20 20 20 20 he passed.**
3a280 20 20 20 20 20 20 20 20 20 20 20 20 61 73 20 74 as t
3a290 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
3a2a0 74 20 74 6f 20 78 46 65 74 63 68 28 29 20 74 68 t to xFetch() th
3a2b0 61 74 20 63 61 6e 20 62 65 20 75 6e 70 69 6e 6e at can be unpinn
3a2c0 65 64 2e 20 54 68 65 0a 2a 2a 20 20 20 20 20 20 ed. The.**
3a2d0 20 20 20 20 20 20 20 20 20 20 63 61 63 68 65 20 cache
3a2e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 implementation s
3a2f0 68 6f 75 6c 64 20 61 74 74 65 6d 70 74 20 74 6f hould attempt to
3a300 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 77 0a allocate a new.
3a310 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 **
3a320 20 20 63 61 63 68 65 20 65 6e 74 72 79 20 61 6e cache entry an
3a330 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 d return a point
3a340 65 72 20 74 6f 20 69 74 2e 20 41 67 61 69 6e 2c er to it. Again,
3a350 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 20 20 the first.**
3a360 20 20 20 20 20 20 20 20 20 20 20 20 20 73 69 7a siz
3a370 65 6f 66 28 76 6f 69 64 2a 29 20 62 79 74 65 73 eof(void*) bytes
3a380 20 6f 66 20 74 68 65 20 70 61 67 65 20 73 68 6f of the page sho
3a390 75 6c 64 20 62 65 20 7a 65 72 6f 65 64 20 62 65 uld be zeroed be
3a3a0 66 6f 72 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 fore .**
3a3b0 20 20 20 20 20 20 20 20 69 74 20 69 73 20 72 65 it is re
3a3c0 74 75 72 6e 65 64 2e 20 49 66 20 74 68 65 20 78 turned. If the x
3a3d0 46 65 74 63 68 28 29 20 6d 65 74 68 6f 64 20 72 Fetch() method r
3a3e0 65 74 75 72 6e 73 20 4e 55 4c 4c 20 77 68 65 6e eturns NULL when
3a3f0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 .**
3a400 20 20 20 20 63 72 65 61 74 65 46 6c 61 67 3d 3d createFlag==
3a410 32 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 2, SQLite assume
3a420 73 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 s that a memory
3a430 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 20 allocation .**
3a440 20 20 20 20 20 20 20 20 20 20 20 20 20 20 66 61 fa
3a450 69 6c 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 iled and returns
3a460 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 74 6f SQLITE_NOMEM to
3a470 20 74 68 65 20 75 73 65 72 2e 0a 2a 2a 20 3c 2f the user..** </
3a480 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 78 55 6e table>.**.** xUn
3a490 70 69 6e 28 29 20 69 73 20 63 61 6c 6c 65 64 20 pin() is called
3a4a0 62 79 20 53 51 4c 69 74 65 20 77 69 74 68 20 61 by SQLite with a
3a4b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 75 pointer to a cu
3a4c0 72 72 65 6e 74 6c 79 20 70 69 6e 6e 65 64 20 70 rrently pinned p
3a4d0 61 67 65 0a 2a 2a 20 61 73 20 69 74 73 20 73 65 age.** as its se
3a4e0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 20 49 cond argument. I
3a4f0 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 f the third para
3a500 6d 65 74 65 72 2c 20 64 69 73 63 61 72 64 2c 20 meter, discard,
3a510 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 is non-zero,.**
3a520 74 68 65 6e 20 74 68 65 20 70 61 67 65 20 73 68 then the page sh
3a530 6f 75 6c 64 20 62 65 20 65 76 69 63 74 65 64 20 ould be evicted
3a540 66 72 6f 6d 20 74 68 65 20 63 61 63 68 65 2e 20 from the cache.
3a550 49 6e 20 74 68 69 73 20 63 61 73 65 20 53 51 4c In this case SQL
3a560 69 74 65 20 0a 2a 2a 20 61 73 73 75 6d 65 73 20 ite .** assumes
3a570 74 68 61 74 20 74 68 65 20 6e 65 78 74 20 74 69 that the next ti
3a580 6d 65 20 74 68 65 20 70 61 67 65 20 69 73 20 72 me the page is r
3a590 65 74 72 69 65 76 65 64 20 66 72 6f 6d 20 74 68 etrieved from th
3a5a0 65 20 63 61 63 68 65 20 75 73 69 6e 67 0a 2a 2a e cache using.**
3a5b0 20 74 68 65 20 78 46 65 74 63 68 28 29 20 6d 65 the xFetch() me
3a5c0 74 68 6f 64 2c 20 69 74 20 77 69 6c 6c 20 62 65 thod, it will be
3a5d0 20 7a 65 72 6f 65 64 2e 20 49 66 20 74 68 65 20 zeroed. If the
3a5e0 64 69 73 63 61 72 64 20 70 61 72 61 6d 65 74 65 discard paramete
3a5f0 72 20 69 73 0a 2a 2a 20 7a 65 72 6f 2c 20 74 68 r is.** zero, th
3a600 65 6e 20 74 68 65 20 70 61 67 65 20 69 73 20 63 en the page is c
3a610 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20 onsidered to be
3a620 75 6e 70 69 6e 6e 65 64 2e 20 54 68 65 20 63 61 unpinned. The ca
3a630 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 che implementati
3a640 6f 6e 0a 2a 2a 20 6d 61 79 20 63 68 6f 6f 73 65 on.** may choose
3a650 20 74 6f 20 72 65 63 6c 61 69 6d 20 28 66 72 65 to reclaim (fre
3a660 65 20 6f 72 20 72 65 63 79 63 6c 65 29 20 75 6e e or recycle) un
3a670 70 69 6e 6e 65 64 20 70 61 67 65 73 20 61 74 20 pinned pages at
3a680 61 6e 79 20 74 69 6d 65 2e 0a 2a 2a 20 53 51 4c any time..** SQL
3a690 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 ite assumes that
3a6a0 20 6e 65 78 74 20 74 69 6d 65 20 74 68 65 20 70 next time the p
3a6b0 61 67 65 20 69 73 20 72 65 74 72 69 65 76 65 64 age is retrieved
3a6c0 20 66 72 6f 6d 20 74 68 65 20 63 61 63 68 65 0a from the cache.
3a6d0 2a 2a 20 69 74 20 77 69 6c 6c 20 65 69 74 68 65 ** it will eithe
3a6e0 72 20 62 65 20 7a 65 72 6f 65 64 2c 20 6f 72 20 r be zeroed, or
3a6f0 63 6f 6e 74 61 69 6e 20 74 68 65 20 73 61 6d 65 contain the same
3a700 20 64 61 74 61 20 74 68 61 74 20 69 74 20 64 69 data that it di
3a710 64 20 77 68 65 6e 20 69 74 0a 2a 2a 20 77 61 73 d when it.** was
3a720 20 75 6e 70 69 6e 6e 65 64 2e 0a 2a 2a 0a 2a 2a unpinned..**.**
3a730 20 54 68 65 20 63 61 63 68 65 20 69 73 20 6e 6f The cache is no
3a740 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 70 65 t required to pe
3a750 72 66 6f 72 6d 20 61 6e 79 20 72 65 66 65 72 65 rform any refere
3a760 6e 63 65 20 63 6f 75 6e 74 69 6e 67 2e 20 41 20 nce counting. A
3a770 73 69 6e 67 6c 65 20 0a 2a 2a 20 63 61 6c 6c 20 single .** call
3a780 74 6f 20 78 55 6e 70 69 6e 28 29 20 75 6e 70 69 to xUnpin() unpi
3a790 6e 73 20 74 68 65 20 70 61 67 65 20 72 65 67 61 ns the page rega
3a7a0 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75 rdless of the nu
3a7b0 6d 62 65 72 20 6f 66 20 70 72 69 6f 72 20 63 61 mber of prior ca
3a7c0 6c 6c 73 20 0a 2a 2a 20 74 6f 20 78 46 65 74 63 lls .** to xFetc
3a7d0 68 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 h()..**.** The x
3a7e0 52 65 6b 65 79 28 29 20 6d 65 74 68 6f 64 20 69 Rekey() method i
3a7f0 73 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 s used to change
3a800 20 74 68 65 20 6b 65 79 20 76 61 6c 75 65 20 61 the key value a
3a810 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
3a820 68 65 0a 2a 2a 20 70 61 67 65 20 70 61 73 73 65 he.** page passe
3a830 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 d as the second
3a840 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 6f 6c argument from ol
3a850 64 4b 65 79 20 74 6f 20 6e 65 77 4b 65 79 2e 20 dKey to newKey.
3a860 49 66 20 74 68 65 20 63 61 63 68 65 0a 2a 2a 20 If the cache.**
3a870 70 72 65 76 69 6f 75 73 6c 79 20 63 6f 6e 74 61 previously conta
3a880 69 6e 73 20 61 6e 20 65 6e 74 72 79 20 61 73 73 ins an entry ass
3a890 6f 63 69 61 74 65 64 20 77 69 74 68 20 6e 65 77 ociated with new
3a8a0 4b 65 79 2c 20 69 74 20 73 68 6f 75 6c 64 20 62 Key, it should b
3a8b0 65 0a 2a 2a 20 64 69 73 63 61 72 64 65 64 2e 20 e.** discarded.
3a8c0 41 6e 79 20 70 72 69 6f 72 20 63 61 63 68 65 20 Any prior cache
3a8d0 65 6e 74 72 79 20 61 73 73 6f 63 69 61 74 65 64 entry associated
3a8e0 20 77 69 74 68 20 6e 65 77 4b 65 79 20 69 73 20 with newKey is
3a8f0 67 75 61 72 61 6e 74 65 65 64 20 6e 6f 74 0a 2a guaranteed not.*
3a900 2a 20 74 6f 20 62 65 20 70 69 6e 6e 65 64 2e 0a * to be pinned..
3a910 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 **.** When SQLit
3a920 65 20 63 61 6c 6c 73 20 74 68 65 20 78 54 72 75 e calls the xTru
3a930 6e 63 61 74 65 28 29 20 6d 65 74 68 6f 64 2c 20 ncate() method,
3a940 74 68 65 20 63 61 63 68 65 20 6d 75 73 74 20 64 the cache must d
3a950 69 73 63 61 72 64 20 61 6c 6c 0a 2a 2a 20 65 78 iscard all.** ex
3a960 69 73 74 69 6e 67 20 63 61 63 68 65 20 65 6e 74 isting cache ent
3a970 72 69 65 73 20 77 69 74 68 20 70 61 67 65 20 6e ries with page n
3a980 75 6d 62 65 72 73 20 28 6b 65 79 73 29 20 67 72 umbers (keys) gr
3a990 65 61 74 65 72 20 74 68 61 6e 20 6f 72 20 65 71 eater than or eq
3a9a0 75 61 6c 0a 2a 2a 20 74 6f 20 74 68 65 20 76 61 ual.** to the va
3a9b0 6c 75 65 20 6f 66 20 74 68 65 20 69 4c 69 6d 69 lue of the iLimi
3a9c0 74 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 t parameter pass
3a9d0 65 64 20 74 6f 20 78 54 72 75 6e 63 61 74 65 28 ed to xTruncate(
3a9e0 29 2e 20 49 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 ). If any.** of
3a9f0 74 68 65 73 65 20 70 61 67 65 73 20 61 72 65 20 these pages are
3aa00 70 69 6e 6e 65 64 2c 20 74 68 65 79 20 61 72 65 pinned, they are
3aa10 20 69 6d 70 6c 69 63 69 74 6c 79 20 75 6e 70 69 implicitly unpi
3aa20 6e 6e 65 64 2c 20 6d 65 61 6e 69 6e 67 20 74 68 nned, meaning th
3aa30 61 74 0a 2a 2a 20 74 68 65 79 20 63 61 6e 20 62 at.** they can b
3aa40 65 20 73 61 66 65 6c 79 20 64 69 73 63 61 72 64 e safely discard
3aa50 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 ed..**.** The xD
3aa60 65 73 74 72 6f 79 28 29 20 6d 65 74 68 6f 64 20 estroy() method
3aa70 69 73 20 75 73 65 64 20 74 6f 20 64 65 6c 65 74 is used to delet
3aa80 65 20 61 20 63 61 63 68 65 20 61 6c 6c 6f 63 61 e a cache alloca
3aa90 74 65 64 20 62 79 20 78 43 72 65 61 74 65 28 29 ted by xCreate()
3aaa0 2e 0a 2a 2a 20 41 6c 6c 20 72 65 73 6f 75 72 63 ..** All resourc
3aab0 65 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 es associated wi
3aac0 74 68 20 74 68 65 20 73 70 65 63 69 66 69 65 64 th the specified
3aad0 20 63 61 63 68 65 20 73 68 6f 75 6c 64 20 62 65 cache should be
3aae0 20 66 72 65 65 64 2e 20 41 66 74 65 72 0a 2a 2a freed. After.**
3aaf0 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 44 65 calling the xDe
3ab00 73 74 72 6f 79 28 29 20 6d 65 74 68 6f 64 2c 20 stroy() method,
3ab10 53 51 4c 69 74 65 20 63 6f 6e 73 69 64 65 72 73 SQLite considers
3ab20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 the [sqlite3_pc
3ab30 61 63 68 65 2a 5d 0a 2a 2a 20 68 61 6e 64 6c 65 ache*].** handle
3ab40 20 69 6e 76 61 6c 69 64 2c 20 61 6e 64 20 77 69 invalid, and wi
3ab50 6c 6c 20 6e 6f 74 20 75 73 65 20 69 74 20 77 69 ll not use it wi
3ab60 74 68 20 61 6e 79 20 6f 74 68 65 72 20 73 71 6c th any other sql
3ab70 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 ite3_pcache_meth
3ab80 6f 64 73 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 ods.** functions
3ab90 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
3aba0 75 63 74 20 73 71 6c 69 74 65 33 5f 70 63 61 63 uct sqlite3_pcac
3abb0 68 65 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 he_methods sqlit
3abc0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 e3_pcache_method
3abd0 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 s;.struct sqlite
3abe0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3_pcache_methods
3abf0 20 7b 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 3b {. void *pArg;
3ac00 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 . int (*xInit)(
3ac10 76 6f 69 64 2a 29 3b 0a 20 20 76 6f 69 64 20 28 void*);. void (
3ac20 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 *xShutdown)(void
3ac30 2a 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 70 63 *);. sqlite3_pc
3ac40 61 63 68 65 20 2a 28 2a 78 43 72 65 61 74 65 29 ache *(*xCreate)
3ac50 28 69 6e 74 20 73 7a 50 61 67 65 2c 20 69 6e 74 (int szPage, int
3ac60 20 62 50 75 72 67 65 61 62 6c 65 29 3b 0a 20 20 bPurgeable);.
3ac70 76 6f 69 64 20 28 2a 78 43 61 63 68 65 73 69 7a void (*xCachesiz
3ac80 65 29 28 73 71 6c 69 74 65 33 5f 70 63 61 63 68 e)(sqlite3_pcach
3ac90 65 2a 2c 20 69 6e 74 20 6e 43 61 63 68 65 73 69 e*, int nCachesi
3aca0 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 50 61 ze);. int (*xPa
3acb0 67 65 63 6f 75 6e 74 29 28 73 71 6c 69 74 65 33 gecount)(sqlite3
3acc0 5f 70 63 61 63 68 65 2a 29 3b 0a 20 20 76 6f 69 _pcache*);. voi
3acd0 64 20 2a 28 2a 78 46 65 74 63 68 29 28 73 71 6c d *(*xFetch)(sql
3ace0 69 74 65 33 5f 70 63 61 63 68 65 2a 2c 20 75 6e ite3_pcache*, un
3acf0 73 69 67 6e 65 64 20 6b 65 79 2c 20 69 6e 74 20 signed key, int
3ad00 63 72 65 61 74 65 46 6c 61 67 29 3b 0a 20 20 76 createFlag);. v
3ad10 6f 69 64 20 28 2a 78 55 6e 70 69 6e 29 28 73 71 oid (*xUnpin)(sq
3ad20 6c 69 74 65 33 5f 70 63 61 63 68 65 2a 2c 20 76 lite3_pcache*, v
3ad30 6f 69 64 2a 2c 20 69 6e 74 20 64 69 73 63 61 72 oid*, int discar
3ad40 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 52 65 d);. void (*xRe
3ad50 6b 65 79 29 28 73 71 6c 69 74 65 33 5f 70 63 61 key)(sqlite3_pca
3ad60 63 68 65 2a 2c 20 76 6f 69 64 2a 2c 20 75 6e 73 che*, void*, uns
3ad70 69 67 6e 65 64 20 6f 6c 64 4b 65 79 2c 20 75 6e igned oldKey, un
3ad80 73 69 67 6e 65 64 20 6e 65 77 4b 65 79 29 3b 0a signed newKey);.
3ad90 20 20 76 6f 69 64 20 28 2a 78 54 72 75 6e 63 61 void (*xTrunca
3ada0 74 65 29 28 73 71 6c 69 74 65 33 5f 70 63 61 63 te)(sqlite3_pcac
3adb0 68 65 2a 2c 20 75 6e 73 69 67 6e 65 64 20 69 4c he*, unsigned iL
3adc0 69 6d 69 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a imit);. void (*
3add0 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65 xDestroy)(sqlite
3ade0 33 5f 70 63 61 63 68 65 2a 29 3b 0a 7d 3b 0a 0a 3_pcache*);.};..
3adf0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
3ae00 4f 6e 6c 69 6e 65 20 42 61 63 6b 75 70 20 4f 62 Online Backup Ob
3ae10 6a 65 63 74 0a 2a 2a 20 45 58 50 45 52 49 4d 45 ject.** EXPERIME
3ae20 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 NTAL.**.** The s
3ae30 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 qlite3_backup ob
3ae40 6a 65 63 74 20 72 65 63 6f 72 64 73 20 73 74 61 ject records sta
3ae50 74 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 te information a
3ae60 62 6f 75 74 20 61 6e 20 6f 6e 67 6f 69 6e 67 0a bout an ongoing.
3ae70 2a 2a 20 6f 6e 6c 69 6e 65 20 62 61 63 6b 75 70 ** online backup
3ae80 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 54 68 65 operation. The
3ae90 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 sqlite3_backup
3aea0 6f 62 6a 65 63 74 20 69 73 20 63 72 65 61 74 65 object is create
3aeb0 64 20 62 79 0a 2a 2a 20 61 20 63 61 6c 6c 20 74 d by.** a call t
3aec0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 o [sqlite3_backu
3aed0 70 5f 69 6e 69 74 28 29 5d 20 61 6e 64 20 69 73 p_init()] and is
3aee0 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 61 20 destroyed by a
3aef0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 call to.** [sqli
3af00 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 te3_backup_finis
3af10 68 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 h()]..**.** See
3af20 41 6c 73 6f 3a 20 5b 55 73 69 6e 67 20 74 68 65 Also: [Using the
3af30 20 53 51 4c 69 74 65 20 4f 6e 6c 69 6e 65 20 42 SQLite Online B
3af40 61 63 6b 75 70 20 41 50 49 5d 0a 2a 2f 0a 74 79 ackup API].*/.ty
3af50 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
3af60 69 74 65 33 5f 62 61 63 6b 75 70 20 73 71 6c 69 ite3_backup sqli
3af70 74 65 33 5f 62 61 63 6b 75 70 3b 0a 0a 2f 2a 0a te3_backup;../*.
3af80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 6c ** CAPI3REF: Onl
3af90 69 6e 65 20 42 61 63 6b 75 70 20 41 50 49 2e 0a ine Backup API..
3afa0 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a ** EXPERIMENTAL.
3afb0 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 69 **.** This API i
3afc0 73 20 75 73 65 64 20 74 6f 20 6f 76 65 72 77 72 s used to overwr
3afd0 69 74 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 ite the contents
3afe0 20 6f 66 20 6f 6e 65 20 64 61 74 61 62 61 73 65 of one database
3aff0 20 77 69 74 68 20 74 68 61 74 0a 2a 2a 20 6f 66 with that.** of
3b000 20 61 6e 6f 74 68 65 72 2e 20 49 74 20 69 73 20 another. It is
3b010 75 73 65 66 75 6c 20 65 69 74 68 65 72 20 66 6f useful either fo
3b020 72 20 63 72 65 61 74 69 6e 67 20 62 61 63 6b 75 r creating backu
3b030 70 73 20 6f 66 20 64 61 74 61 62 61 73 65 73 20 ps of databases
3b040 6f 72 0a 2a 2a 20 66 6f 72 20 63 6f 70 79 69 6e or.** for copyin
3b050 67 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 g in-memory data
3b060 62 61 73 65 73 20 74 6f 20 6f 72 20 66 72 6f 6d bases to or from
3b070 20 70 65 72 73 69 73 74 65 6e 74 20 66 69 6c 65 persistent file
3b080 73 2e 20 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c s. .**.** See Al
3b090 73 6f 3a 20 5b 55 73 69 6e 67 20 74 68 65 20 53 so: [Using the S
3b0a0 51 4c 69 74 65 20 4f 6e 6c 69 6e 65 20 42 61 63 QLite Online Bac
3b0b0 6b 75 70 20 41 50 49 5d 0a 2a 2a 0a 2a 2a 20 45 kup API].**.** E
3b0c0 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 20 xclusive access
3b0d0 69 73 20 72 65 71 75 69 72 65 64 20 74 6f 20 74 is required to t
3b0e0 68 65 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 he destination d
3b0f0 61 74 61 62 61 73 65 20 66 6f 72 20 74 68 65 20 atabase for the
3b100 0a 2a 2a 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 .** duration of
3b110 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 48 the operation. H
3b120 6f 77 65 76 65 72 20 74 68 65 20 73 6f 75 72 63 owever the sourc
3b130 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 6e e database is on
3b140 6c 79 0a 2a 2a 20 72 65 61 64 2d 6c 6f 63 6b 65 ly.** read-locke
3b150 64 20 77 68 69 6c 65 20 69 74 20 69 73 20 61 63 d while it is ac
3b160 74 75 61 6c 6c 79 20 62 65 69 6e 67 20 72 65 61 tually being rea
3b170 64 2c 20 69 74 20 69 73 20 6e 6f 74 20 6c 6f 63 d, it is not loc
3b180 6b 65 64 0a 2a 2a 20 63 6f 6e 74 69 6e 75 6f 75 ked.** continuou
3b190 73 6c 79 20 66 6f 72 20 74 68 65 20 65 6e 74 69 sly for the enti
3b1a0 72 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 54 68 re operation. Th
3b1b0 75 73 2c 20 74 68 65 20 62 61 63 6b 75 70 20 6d us, the backup m
3b1c0 61 79 20 62 65 0a 2a 2a 20 70 65 72 66 6f 72 6d ay be.** perform
3b1d0 65 64 20 6f 6e 20 61 20 6c 69 76 65 20 64 61 74 ed on a live dat
3b1e0 61 62 61 73 65 20 77 69 74 68 6f 75 74 20 70 72 abase without pr
3b1f0 65 76 65 6e 74 69 6e 67 20 6f 74 68 65 72 20 75 eventing other u
3b200 73 65 72 73 20 66 72 6f 6d 0a 2a 2a 20 77 72 69 sers from.** wri
3b210 74 69 6e 67 20 74 6f 20 74 68 65 20 64 61 74 61 ting to the data
3b220 62 61 73 65 20 66 6f 72 20 61 6e 20 65 78 74 65 base for an exte
3b230 6e 64 65 64 20 70 65 72 69 6f 64 20 6f 66 20 74 nded period of t
3b240 69 6d 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 6f 20 70 ime..** .** To p
3b250 65 72 66 6f 72 6d 20 61 20 62 61 63 6b 75 70 20 erform a backup
3b260 6f 70 65 72 61 74 69 6f 6e 3a 20 0a 2a 2a 20 20 operation: .**
3b270 20 3c 6f 6c 3e 0a 2a 2a 20 20 20 20 20 3c 6c 69 <ol>.** <li
3b280 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 62 61 63 6b ><b>sqlite3_back
3b290 75 70 5f 69 6e 69 74 28 29 3c 2f 62 3e 20 69 73 up_init()</b> is
3b2a0 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 74 6f 20 called once to
3b2b0 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 0a 2a initialize the.*
3b2c0 2a 20 20 20 20 20 20 20 20 20 62 61 63 6b 75 70 * backup
3b2d0 2c 20 0a 2a 2a 20 20 20 20 20 3c 6c 69 3e 3c 62 , .** <li><b
3b2e0 3e 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f >sqlite3_backup_
3b2f0 73 74 65 70 28 29 3c 2f 62 3e 20 69 73 20 63 61 step()</b> is ca
3b300 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 lled one or more
3b310 20 74 69 6d 65 73 20 74 6f 20 74 72 61 6e 73 66 times to transf
3b320 65 72 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 74 er .** t
3b330 68 65 20 64 61 74 61 20 62 65 74 77 65 65 6e 20 he data between
3b340 74 68 65 20 74 77 6f 20 64 61 74 61 62 61 73 65 the two database
3b350 73 2c 20 61 6e 64 20 66 69 6e 61 6c 6c 79 0a 2a s, and finally.*
3b360 2a 20 20 20 20 20 3c 6c 69 3e 3c 62 3e 73 71 6c * <li><b>sql
3b370 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 ite3_backup_fini
3b380 73 68 28 29 3c 2f 62 3e 20 69 73 20 63 61 6c 6c sh()</b> is call
3b390 65 64 20 74 6f 20 72 65 6c 65 61 73 65 20 61 6c ed to release al
3b3a0 6c 20 72 65 73 6f 75 72 63 65 73 20 0a 2a 2a 20 l resources .**
3b3b0 20 20 20 20 20 20 20 20 61 73 73 6f 63 69 61 74 associat
3b3c0 65 64 20 77 69 74 68 20 74 68 65 20 62 61 63 6b ed with the back
3b3d0 75 70 20 6f 70 65 72 61 74 69 6f 6e 2e 20 0a 2a up operation. .*
3b3e0 2a 20 20 20 3c 2f 6f 6c 3e 0a 2a 2a 20 54 68 65 * </ol>.** The
3b3f0 72 65 20 73 68 6f 75 6c 64 20 62 65 20 65 78 61 re should be exa
3b400 63 74 6c 79 20 6f 6e 65 20 63 61 6c 6c 20 74 6f ctly one call to
3b410 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f sqlite3_backup_
3b420 66 69 6e 69 73 68 28 29 20 66 6f 72 20 65 61 63 finish() for eac
3b430 68 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 h.** successful
3b440 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
3b450 62 61 63 6b 75 70 5f 69 6e 69 74 28 29 2e 0a 2a backup_init()..*
3b460 2a 0a 2a 2a 20 3c 62 3e 73 71 6c 69 74 65 33 5f *.** <b>sqlite3_
3b470 62 61 63 6b 75 70 5f 69 6e 69 74 28 29 3c 2f 62 backup_init()</b
3b480 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 >.**.** The firs
3b490 74 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 t two arguments
3b4a0 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 passed to [sqlit
3b4b0 65 33 5f 62 61 63 6b 75 70 5f 69 6e 69 74 28 29 e3_backup_init()
3b4c0 5d 20 61 72 65 20 74 68 65 20 64 61 74 61 62 61 ] are the databa
3b4d0 73 65 0a 2a 2a 20 68 61 6e 64 6c 65 20 61 73 73 se.** handle ass
3b4e0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 ociated with the
3b4f0 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 destination dat
3b500 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 64 61 abase and the da
3b510 74 61 62 61 73 65 20 6e 61 6d 65 20 0a 2a 2a 20 tabase name .**
3b520 75 73 65 64 20 74 6f 20 61 74 74 61 63 68 20 74 used to attach t
3b530 68 65 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 he destination d
3b540 61 74 61 62 61 73 65 20 74 6f 20 74 68 65 20 68 atabase to the h
3b550 61 6e 64 6c 65 2e 20 54 68 65 20 64 61 74 61 62 andle. The datab
3b560 61 73 65 20 6e 61 6d 65 0a 2a 2a 20 69 73 20 22 ase name.** is "
3b570 6d 61 69 6e 22 20 66 6f 72 20 74 68 65 20 6d 61 main" for the ma
3b580 69 6e 20 64 61 74 61 62 61 73 65 2c 20 22 74 65 in database, "te
3b590 6d 70 22 20 66 6f 72 20 74 68 65 20 74 65 6d 70 mp" for the temp
3b5a0 6f 72 61 72 79 20 64 61 74 61 62 61 73 65 2c 20 orary database,
3b5b0 6f 72 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 73 or.** the name s
3b5c0 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74 pecified as part
3b5d0 20 6f 66 20 74 68 65 20 5b 41 54 54 41 43 48 5d of the [ATTACH]
3b5e0 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20 74 68 statement if th
3b5f0 65 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 69 73 e destination is
3b600 0a 2a 2a 20 61 6e 20 61 74 74 61 63 68 65 64 20 .** an attached
3b610 64 61 74 61 62 61 73 65 2e 20 54 68 65 20 74 68 database. The th
3b620 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61 ird and fourth a
3b630 72 67 75 6d 65 6e 74 73 20 70 61 73 73 65 64 20 rguments passed
3b640 74 6f 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 to .** sqlite3_b
3b650 61 63 6b 75 70 5f 69 6e 69 74 28 29 20 69 64 65 ackup_init() ide
3b660 6e 74 69 66 79 20 74 68 65 20 5b 64 61 74 61 62 ntify the [datab
3b670 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a ase connection].
3b680 2a 2a 20 61 6e 64 20 64 61 74 61 62 61 73 65 20 ** and database
3b690 6e 61 6d 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 name used.** to
3b6a0 61 63 63 65 73 73 20 74 68 65 20 73 6f 75 72 63 access the sourc
3b6b0 65 20 64 61 74 61 62 61 73 65 2e 20 54 68 65 20 e database. The
3b6c0 76 61 6c 75 65 73 20 70 61 73 73 65 64 20 66 6f values passed fo
3b6d0 72 20 74 68 65 20 73 6f 75 72 63 65 20 61 6e 64 r the source and
3b6e0 20 0a 2a 2a 20 64 65 73 74 69 6e 61 74 69 6f 6e .** destination
3b6f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
3b700 63 74 69 6f 6e 5d 20 70 61 72 61 6d 65 74 65 72 ction] parameter
3b710 73 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 74 68 s must not be th
3b720 65 20 73 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 e same..**.** If
3b730 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 an error occurs
3b740 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f within sqlite3_
3b750 62 61 63 6b 75 70 5f 69 6e 69 74 28 29 2c 20 74 backup_init(), t
3b760 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 hen NULL is retu
3b770 72 6e 65 64 0a 2a 2a 20 61 6e 64 20 61 6e 20 65 rned.** and an e
3b780 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 65 72 rror code and er
3b790 72 6f 72 20 6d 65 73 73 61 67 65 20 77 72 69 74 ror message writ
3b7a0 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 5b 64 61 ten into the [da
3b7b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
3b7c0 6e 5d 20 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 n] .** passed as
3b7d0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
3b7e0 65 6e 74 2e 20 54 68 65 79 20 6d 61 79 20 62 65 ent. They may be
3b7f0 20 72 65 74 72 69 65 76 65 64 20 75 73 69 6e 67 retrieved using
3b800 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
3b810 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71 _errcode()], [sq
3b820 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c lite3_errmsg()],
3b830 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 and [sqlite3_er
3b840 72 6d 73 67 31 36 28 29 5d 20 66 75 6e 63 74 69 rmsg16()] functi
3b850 6f 6e 73 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 ons..** Otherwis
3b860 65 2c 20 69 66 20 73 75 63 63 65 73 73 66 75 6c e, if successful
3b870 2c 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 , a pointer to a
3b880 6e 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 n [sqlite3_backu
3b890 70 5d 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 p] object is.**
3b8a0 72 65 74 75 72 6e 65 64 2e 20 54 68 69 73 20 70 returned. This p
3b8b0 6f 69 6e 74 65 72 20 6d 61 79 20 62 65 20 75 73 ointer may be us
3b8c0 65 64 20 77 69 74 68 20 74 68 65 20 73 71 6c 69 ed with the sqli
3b8d0 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 te3_backup_step(
3b8e0 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ) and.** sqlite3
3b8f0 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 29 _backup_finish()
3b900 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 70 65 functions to pe
3b910 72 66 6f 72 6d 20 74 68 65 20 73 70 65 63 69 66 rform the specif
3b920 69 65 64 20 62 61 63 6b 75 70 20 0a 2a 2a 20 6f ied backup .** o
3b930 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 peration..**.**
3b940 3c 62 3e 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 <b>sqlite3_backu
3b950 70 5f 73 74 65 70 28 29 3c 2f 62 3e 0a 2a 2a 0a p_step()</b>.**.
3b960 2a 2a 20 46 75 6e 63 74 69 6f 6e 20 5b 73 71 6c ** Function [sql
3b970 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 ite3_backup_step
3b980 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 63 ()] is used to c
3b990 6f 70 79 20 75 70 20 74 6f 20 6e 50 61 67 65 20 opy up to nPage
3b9a0 70 61 67 65 73 20 62 65 74 77 65 65 6e 20 0a 2a pages between .*
3b9b0 2a 20 74 68 65 20 73 6f 75 72 63 65 20 61 6e 64 * the source and
3b9c0 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 destination dat
3b9d0 61 62 61 73 65 73 2c 20 77 68 65 72 65 20 6e 50 abases, where nP
3b9e0 61 67 65 20 69 73 20 74 68 65 20 76 61 6c 75 65 age is the value
3b9f0 20 6f 66 20 74 68 65 20 0a 2a 2a 20 73 65 63 6f of the .** seco
3ba00 6e 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 nd parameter pas
3ba10 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 sed to sqlite3_b
3ba20 61 63 6b 75 70 5f 73 74 65 70 28 29 2e 20 49 66 ackup_step(). If
3ba30 20 6e 50 61 67 65 20 69 73 20 61 20 6e 65 67 61 nPage is a nega
3ba40 74 69 76 65 0a 2a 2a 20 76 61 6c 75 65 2c 20 61 tive.** value, a
3ba50 6c 6c 20 72 65 6d 61 69 6e 69 6e 67 20 73 6f 75 ll remaining sou
3ba60 72 63 65 20 70 61 67 65 73 20 61 72 65 20 63 6f rce pages are co
3ba70 70 69 65 64 2e 20 49 66 20 74 68 65 20 72 65 71 pied. If the req
3ba80 75 69 72 65 64 20 70 61 67 65 73 20 61 72 65 20 uired pages are
3ba90 0a 2a 2a 20 73 75 63 63 65 73 66 75 6c 6c 79 20 .** succesfully
3baa0 63 6f 70 69 65 64 2c 20 62 75 74 20 74 68 65 72 copied, but ther
3bab0 65 20 61 72 65 20 73 74 69 6c 6c 20 6d 6f 72 65 e are still more
3bac0 20 70 61 67 65 73 20 74 6f 20 63 6f 70 79 20 62 pages to copy b
3bad0 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 62 61 efore the .** ba
3bae0 63 6b 75 70 20 69 73 20 63 6f 6d 70 6c 65 74 65 ckup is complete
3baf0 2c 20 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 , it returns [SQ
3bb00 4c 49 54 45 5f 4f 4b 5d 2e 20 49 66 20 6e 6f 20 LITE_OK]. If no
3bb10 65 72 72 6f 72 20 6f 63 63 75 72 65 64 20 61 6e error occured an
3bb20 64 20 74 68 65 72 65 20 0a 2a 2a 20 61 72 65 20 d there .** are
3bb30 6e 6f 20 6d 6f 72 65 20 70 61 67 65 73 20 74 6f no more pages to
3bb40 20 63 6f 70 79 2c 20 74 68 65 6e 20 5b 53 51 4c copy, then [SQL
3bb50 49 54 45 5f 44 4f 4e 45 5d 20 69 73 20 72 65 74 ITE_DONE] is ret
3bb60 75 72 6e 65 64 2e 20 49 66 20 61 6e 20 65 72 72 urned. If an err
3bb70 6f 72 20 0a 2a 2a 20 6f 63 63 75 72 73 2c 20 74 or .** occurs, t
3bb80 68 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 65 72 hen an SQLite er
3bb90 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 ror code is retu
3bba0 72 6e 65 64 2e 20 41 73 20 77 65 6c 6c 20 61 73 rned. As well as
3bbb0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e 64 [SQLITE_OK] and
3bbc0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 .** [SQLITE_DONE
3bbd0 5d 2c 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c ], a call to sql
3bbe0 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 ite3_backup_step
3bbf0 28 29 20 6d 61 79 20 72 65 74 75 72 6e 20 5b 53 () may return [S
3bc00 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2c QLITE_READONLY],
3bc10 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 .** [SQLITE_NOME
3bc20 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 M], [SQLITE_BUSY
3bc30 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 ], [SQLITE_LOCKE
3bc40 44 5d 2c 20 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 D], or an.** [SQ
3bc50 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 LITE_IOERR_ACCES
3bc60 53 20 7c 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 S | SQLITE_IOERR
3bc70 5f 58 58 58 5d 20 65 78 74 65 6e 64 65 64 20 65 _XXX] extended e
3bc80 72 72 6f 72 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a rror code..**.**
3bc90 20 41 73 20 77 65 6c 6c 20 61 73 20 74 68 65 20 As well as the
3bca0 63 61 73 65 20 77 68 65 72 65 20 74 68 65 20 64 case where the d
3bcb0 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 estination datab
3bcc0 61 73 65 20 66 69 6c 65 20 77 61 73 20 6f 70 65 ase file was ope
3bcd0 6e 65 64 20 66 6f 72 0a 2a 2a 20 72 65 61 64 2d ned for.** read-
3bce0 6f 6e 6c 79 20 61 63 63 65 73 73 2c 20 73 71 6c only access, sql
3bcf0 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 ite3_backup_step
3bd00 28 29 20 6d 61 79 20 72 65 74 75 72 6e 20 5b 53 () may return [S
3bd10 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 20 QLITE_READONLY]
3bd20 69 66 0a 2a 2a 20 74 68 65 20 64 65 73 74 69 6e if.** the destin
3bd30 61 74 69 6f 6e 20 69 73 20 61 6e 20 69 6e 2d 6d ation is an in-m
3bd40 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 emory database w
3bd50 69 74 68 20 61 20 64 69 66 66 65 72 65 6e 74 20 ith a different
3bd60 70 61 67 65 20 73 69 7a 65 0a 2a 2a 20 66 72 6f page size.** fro
3bd70 6d 20 74 68 65 20 73 6f 75 72 63 65 20 64 61 74 m the source dat
3bd80 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 abase..**.** If
3bd90 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 sqlite3_backup_s
3bda0 74 65 70 28 29 20 63 61 6e 6e 6f 74 20 6f 62 74 tep() cannot obt
3bdb0 61 69 6e 20 61 20 72 65 71 75 69 72 65 64 20 66 ain a required f
3bdc0 69 6c 65 2d 73 79 73 74 65 6d 20 6c 6f 63 6b 2c ile-system lock,
3bdd0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 73 71 then.** the [sq
3bde0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c lite3_busy_handl
3bdf0 65 72 20 7c 20 62 75 73 79 2d 68 61 6e 64 6c 65 er | busy-handle
3be00 72 20 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 69 r function].** i
3be10 73 20 69 6e 76 6f 6b 65 64 20 28 69 66 20 6f 6e s invoked (if on
3be20 65 20 69 73 20 73 70 65 63 69 66 69 65 64 29 2e e is specified).
3be30 20 49 66 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 If the .** busy
3be40 2d 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 -handler returns
3be50 20 6e 6f 6e 2d 7a 65 72 6f 20 62 65 66 6f 72 65 non-zero before
3be60 20 74 68 65 20 6c 6f 63 6b 20 69 73 20 61 76 61 the lock is ava
3be70 69 6c 61 62 6c 65 2c 20 74 68 65 6e 20 0a 2a 2a ilable, then .**
3be80 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 [SQLITE_BUSY] i
3be90 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 s returned to th
3bea0 65 20 63 61 6c 6c 65 72 2e 20 49 6e 20 74 68 69 e caller. In thi
3beb0 73 20 63 61 73 65 20 74 68 65 20 63 61 6c 6c 20 s case the call
3bec0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 to.** sqlite3_ba
3bed0 63 6b 75 70 5f 73 74 65 70 28 29 20 63 61 6e 20 ckup_step() can
3bee0 62 65 20 72 65 74 72 69 65 64 20 6c 61 74 65 72 be retried later
3bef0 2e 20 49 66 20 74 68 65 20 73 6f 75 72 63 65 0a . If the source.
3bf00 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
3bf10 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 73 20 62 nection].** is b
3bf20 65 69 6e 67 20 75 73 65 64 20 74 6f 20 77 72 69 eing used to wri
3bf30 74 65 20 74 6f 20 74 68 65 20 73 6f 75 72 63 65 te to the source
3bf40 20 64 61 74 61 62 61 73 65 20 77 68 65 6e 20 73 database when s
3bf50 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 qlite3_backup_st
3bf60 65 70 28 29 0a 2a 2a 20 69 73 20 63 61 6c 6c 65 ep().** is calle
3bf70 64 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f d, then [SQLITE_
3bf80 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 LOCKED] is retur
3bf90 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e ned immediately.
3bfa0 20 41 67 61 69 6e 2c 20 69 6e 20 74 68 69 73 0a Again, in this.
3bfb0 2a 2a 20 63 61 73 65 20 74 68 65 20 63 61 6c 6c ** case the call
3bfc0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b to sqlite3_back
3bfd0 75 70 5f 73 74 65 70 28 29 20 63 61 6e 20 62 65 up_step() can be
3bfe0 20 72 65 74 72 69 65 64 20 6c 61 74 65 72 20 6f retried later o
3bff0 6e 2e 20 49 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 n. If.** [SQLITE
3c000 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 7c 20 _IOERR_ACCESS |
3c010 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 58 58 58 SQLITE_IOERR_XXX
3c020 5d 2c 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d ], [SQLITE_NOMEM
3c030 5d 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 ], or.** [SQLITE
3c040 5f 52 45 41 44 4f 4e 4c 59 5d 20 69 73 20 72 65 _READONLY] is re
3c050 74 75 72 6e 65 64 2c 20 74 68 65 6e 20 0a 2a 2a turned, then .**
3c060 20 74 68 65 72 65 20 69 73 20 6e 6f 20 70 6f 69 there is no poi
3c070 6e 74 20 69 6e 20 72 65 74 72 79 69 6e 67 20 74 nt in retrying t
3c080 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 he call to sqlit
3c090 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 e3_backup_step()
3c0a0 2e 20 54 68 65 73 65 20 0a 2a 2a 20 65 72 72 6f . These .** erro
3c0b0 72 73 20 61 72 65 20 63 6f 6e 73 69 64 65 72 65 rs are considere
3c0c0 64 20 66 61 74 61 6c 2e 20 41 74 20 74 68 69 73 d fatal. At this
3c0d0 20 70 6f 69 6e 74 20 74 68 65 20 61 70 70 6c 69 point the appli
3c0e0 63 61 74 69 6f 6e 20 6d 75 73 74 20 61 63 63 65 cation must acce
3c0f0 70 74 20 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 pt .** that the
3c100 62 61 63 6b 75 70 20 6f 70 65 72 61 74 69 6f 6e backup operation
3c110 20 68 61 73 20 66 61 69 6c 65 64 20 61 6e 64 20 has failed and
3c120 70 61 73 73 20 74 68 65 20 62 61 63 6b 75 70 20 pass the backup
3c130 6f 70 65 72 61 74 69 6f 6e 20 68 61 6e 64 6c 65 operation handle
3c140 20 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 .** to the sqli
3c150 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 te3_backup_finis
3c160 68 28 29 20 74 6f 20 72 65 6c 65 61 73 65 20 61 h() to release a
3c170 73 73 6f 63 69 61 74 65 64 20 72 65 73 6f 75 72 ssociated resour
3c180 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 46 6f 6c 6c 6f ces..**.** Follo
3c190 77 69 6e 67 20 74 68 65 20 66 69 72 73 74 20 63 wing the first c
3c1a0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 all to sqlite3_b
3c1b0 61 63 6b 75 70 5f 73 74 65 70 28 29 2c 20 61 6e ackup_step(), an
3c1c0 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 20 exclusive lock
3c1d0 69 73 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 6f is.** obtained o
3c1e0 6e 20 74 68 65 20 64 65 73 74 69 6e 61 74 69 6f n the destinatio
3c1f0 6e 20 66 69 6c 65 2e 20 49 74 20 69 73 20 6e 6f n file. It is no
3c200 74 20 72 65 6c 65 61 73 65 64 20 75 6e 74 69 6c t released until
3c210 20 65 69 74 68 65 72 20 0a 2a 2a 20 73 71 6c 69 either .** sqli
3c220 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 te3_backup_finis
3c230 68 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 72 h() is called or
3c240 20 74 68 65 20 62 61 63 6b 75 70 20 6f 70 65 72 the backup oper
3c250 61 74 69 6f 6e 20 69 73 20 63 6f 6d 70 6c 65 74 ation is complet
3c260 65 20 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 e .** and sqlite
3c270 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 3_backup_step()
3c280 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
3c290 44 4f 4e 45 5d 2e 20 41 64 64 69 74 69 6f 6e 61 DONE]. Additiona
3c2a0 6c 6c 79 2c 20 65 61 63 68 20 74 69 6d 65 20 0a lly, each time .
3c2b0 2a 2a 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c ** a call to sql
3c2c0 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 ite3_backup_step
3c2d0 28 29 20 69 73 20 6d 61 64 65 20 61 20 5b 73 68 () is made a [sh
3c2e0 61 72 65 64 20 6c 6f 63 6b 5d 20 69 73 20 6f 62 ared lock] is ob
3c2f0 74 61 69 6e 65 64 20 6f 6e 0a 2a 2a 20 74 68 65 tained on.** the
3c300 20 73 6f 75 72 63 65 20 64 61 74 61 62 61 73 65 source database
3c310 20 66 69 6c 65 2e 20 54 68 69 73 20 6c 6f 63 6b file. This lock
3c320 20 69 73 20 72 65 6c 65 61 73 65 64 20 62 65 66 is released bef
3c330 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 ore the.** sqlit
3c340 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 e3_backup_step()
3c350 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 20 42 call returns. B
3c360 65 63 61 75 73 65 20 74 68 65 20 73 6f 75 72 63 ecause the sourc
3c370 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f e database is no
3c380 74 0a 2a 2a 20 6c 6f 63 6b 65 64 20 62 65 74 77 t.** locked betw
3c390 65 65 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c een calls to sql
3c3a0 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 ite3_backup_step
3c3b0 28 29 2c 20 69 74 20 6d 61 79 20 62 65 20 6d 6f (), it may be mo
3c3c0 64 69 66 69 65 64 20 6d 69 64 2d 77 61 79 0a 2a dified mid-way.*
3c3d0 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 62 61 * through the ba
3c3e0 63 6b 75 70 20 70 72 6f 63 65 64 75 72 65 2e 20 ckup procedure.
3c3f0 49 66 20 74 68 65 20 73 6f 75 72 63 65 20 64 61 If the source da
3c400 74 61 62 61 73 65 20 69 73 20 6d 6f 64 69 66 69 tabase is modifi
3c410 65 64 20 62 79 20 61 6e 0a 2a 2a 20 65 78 74 65 ed by an.** exte
3c420 72 6e 61 6c 20 70 72 6f 63 65 73 73 20 6f 72 20 rnal process or
3c430 76 69 61 20 61 20 64 61 74 61 62 61 73 65 20 63 via a database c
3c440 6f 6e 6e 65 63 74 69 6f 6e 20 6f 74 68 65 72 20 onnection other
3c450 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 62 65 69 than the one bei
3c460 6e 67 0a 2a 2a 20 75 73 65 64 20 62 79 20 74 68 ng.** used by th
3c470 65 20 62 61 63 6b 75 70 20 6f 70 65 72 61 74 69 e backup operati
3c480 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 62 61 63 on, then the bac
3c490 6b 75 70 20 77 69 6c 6c 20 62 65 20 74 72 61 6e kup will be tran
3c4a0 73 70 61 72 65 6e 74 6c 79 0a 2a 2a 20 72 65 73 sparently.** res
3c4b0 74 61 72 74 65 64 20 62 79 20 74 68 65 20 6e 65 tarted by the ne
3c4c0 78 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 xt call to sqlit
3c4d0 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 e3_backup_step()
3c4e0 2e 20 49 66 20 74 68 65 20 73 6f 75 72 63 65 20 . If the source
3c4f0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 .** database is
3c500 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 20 modified by the
3c510 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 64 using the same d
3c520 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
3c530 6f 6e 20 61 73 20 69 73 20 75 73 65 64 0a 2a 2a on as is used.**
3c540 20 62 79 20 74 68 65 20 62 61 63 6b 75 70 20 6f by the backup o
3c550 70 65 72 61 74 69 6f 6e 2c 20 74 68 65 6e 20 74 peration, then t
3c560 68 65 20 62 61 63 6b 75 70 20 64 61 74 61 62 61 he backup databa
3c570 73 65 20 69 73 20 74 72 61 6e 73 70 61 72 65 6e se is transparen
3c580 74 6c 79 20 0a 2a 2a 20 75 70 64 61 74 65 64 20 tly .** updated
3c590 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 at the same time
3c5a0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 73 71 6c 69 74 ..**.** <b>sqlit
3c5b0 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 e3_backup_finish
3c5c0 28 29 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 63 ()</b>.**.** Onc
3c5d0 65 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 e sqlite3_backup
3c5e0 5f 73 74 65 70 28 29 20 68 61 73 20 72 65 74 75 _step() has retu
3c5f0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e rned [SQLITE_DON
3c600 45 5d 2c 20 6f 72 20 77 68 65 6e 20 74 68 65 20 E], or when the
3c610 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 .** application
3c620 77 69 73 68 65 73 20 74 6f 20 61 62 61 6e 64 6f wishes to abando
3c630 6e 20 74 68 65 20 62 61 63 6b 75 70 20 6f 70 65 n the backup ope
3c640 72 61 74 69 6f 6e 2c 20 74 68 65 20 5b 73 71 6c ration, the [sql
3c650 69 74 65 33 5f 62 61 63 6b 75 70 5d 0a 2a 2a 20 ite3_backup].**
3c660 6f 62 6a 65 63 74 20 73 68 6f 75 6c 64 20 62 65 object should be
3c670 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 passed to sqlit
3c680 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 e3_backup_finish
3c690 28 29 2e 20 54 68 69 73 20 72 65 6c 65 61 73 65 (). This release
3c6a0 73 20 61 6c 6c 0a 2a 2a 20 72 65 73 6f 75 72 63 s all.** resourc
3c6b0 65 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 es associated wi
3c6c0 74 68 20 74 68 65 20 62 61 63 6b 75 70 20 6f 70 th the backup op
3c6d0 65 72 61 74 69 6f 6e 2e 20 49 66 20 73 71 6c 69 eration. If sqli
3c6e0 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 te3_backup_step(
3c6f0 29 0a 2a 2a 20 68 61 73 20 6e 6f 74 20 79 65 74 ).** has not yet
3c700 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 returned [SQLIT
3c710 45 5f 44 4f 4e 45 5d 2c 20 74 68 65 6e 20 61 6e E_DONE], then an
3c720 79 20 61 63 74 69 76 65 20 77 72 69 74 65 2d 74 y active write-t
3c730 72 61 6e 73 61 63 74 69 6f 6e 20 6f 6e 20 74 68 ransaction on th
3c740 65 0a 2a 2a 20 64 65 73 74 69 6e 61 74 69 6f 6e e.** destination
3c750 20 64 61 74 61 62 61 73 65 20 69 73 20 72 6f 6c database is rol
3c760 6c 65 64 20 62 61 63 6b 2e 20 54 68 65 20 5b 73 led back. The [s
3c770 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f qlite3_backup] o
3c780 62 6a 65 63 74 20 69 73 20 69 6e 76 61 6c 69 64 bject is invalid
3c790 0a 2a 2a 20 61 6e 64 20 6d 61 79 20 6e 6f 74 20 .** and may not
3c7a0 62 65 20 75 73 65 64 20 66 6f 6c 6c 6f 77 69 6e be used followin
3c7b0 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 g a call to sqli
3c7c0 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 te3_backup_finis
3c7d0 68 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 h()..**.** The v
3c7e0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 alue returned by
3c7f0 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f sqlite3_backup_
3c800 66 69 6e 69 73 68 20 69 73 20 5b 53 51 4c 49 54 finish is [SQLIT
3c810 45 5f 4f 4b 5d 20 69 66 20 6e 6f 20 65 72 72 6f E_OK] if no erro
3c820 72 0a 2a 2a 20 6f 63 63 75 72 72 65 64 2c 20 72 r.** occurred, r
3c830 65 67 61 72 64 6c 65 73 73 20 6f 72 20 77 68 65 egardless or whe
3c840 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 71 6c 69 ther or not sqli
3c850 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 te3_backup_step(
3c860 29 20 77 61 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 ) was called.**
3c870 61 20 73 75 66 66 69 63 69 65 6e 74 20 6e 75 6d a sufficient num
3c880 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 6f 20 ber of times to
3c890 63 6f 6d 70 6c 65 74 65 20 74 68 65 20 62 61 63 complete the bac
3c8a0 6b 75 70 20 6f 70 65 72 61 74 69 6f 6e 2e 20 4f kup operation. O
3c8b0 72 2c 20 69 66 0a 2a 2a 20 61 6e 20 6f 75 74 2d r, if.** an out-
3c8c0 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 of-memory condit
3c8d0 69 6f 6e 20 6f 72 20 49 4f 20 65 72 72 6f 72 20 ion or IO error
3c8e0 6f 63 63 75 72 65 64 20 64 75 72 69 6e 67 20 61 occured during a
3c8f0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 call to.** sqli
3c900 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 te3_backup_step(
3c910 29 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 4e ) then [SQLITE_N
3c920 4f 4d 45 4d 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b OMEM] or an.** [
3c930 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 SQLITE_IOERR_ACC
3c940 45 53 53 20 7c 20 53 51 4c 49 54 45 5f 49 4f 45 ESS | SQLITE_IOE
3c950 52 52 5f 58 58 58 5d 20 65 72 72 6f 72 20 63 6f RR_XXX] error co
3c960 64 65 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 de.** is returne
3c970 64 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 20 d. In this case
3c980 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 61 the error code a
3c990 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 nd an error mess
3c9a0 61 67 65 20 61 72 65 0a 2a 2a 20 77 72 69 74 74 age are.** writt
3c9b0 65 6e 20 74 6f 20 74 68 65 20 64 65 73 74 69 6e en to the destin
3c9c0 61 74 69 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 ation [database
3c9d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a connection]..**.
3c9e0 2a 2a 20 41 20 72 65 74 75 72 6e 20 6f 66 20 5b ** A return of [
3c9f0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 SQLITE_BUSY] or
3ca00 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5d 20 [SQLITE_LOCKED]
3ca10 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 62 61 63 from sqlite3_bac
3ca20 6b 75 70 5f 73 74 65 70 28 29 20 69 73 0a 2a 2a kup_step() is.**
3ca30 20 6e 6f 74 20 61 20 70 65 72 6d 61 6e 65 6e 74 not a permanent
3ca40 20 65 72 72 6f 72 20 61 6e 64 20 64 6f 65 73 20 error and does
3ca50 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 20 72 not affect the r
3ca60 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 0a 2a eturn value of.*
3ca70 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 * sqlite3_backup
3ca80 5f 66 69 6e 69 73 68 28 29 2e 0a 2a 2a 0a 2a 2a _finish()..**.**
3ca90 20 3c 62 3e 73 71 6c 69 74 65 33 5f 62 61 63 6b <b>sqlite3_back
3caa0 75 70 5f 72 65 6d 61 69 6e 69 6e 67 28 29 2c 20 up_remaining(),
3cab0 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 70 sqlite3_backup_p
3cac0 61 67 65 63 6f 75 6e 74 28 29 3c 2f 62 3e 0a 2a agecount()</b>.*
3cad0 2a 0a 2a 2a 20 45 61 63 68 20 63 61 6c 6c 20 74 *.** Each call t
3cae0 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 o sqlite3_backup
3caf0 5f 73 74 65 70 28 29 20 73 65 74 73 20 74 77 6f _step() sets two
3cb00 20 76 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 values stored i
3cb10 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 62 79 20 nternally.** by
3cb20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b an [sqlite3_back
3cb30 75 70 5d 20 6f 62 6a 65 63 74 2e 20 54 68 65 20 up] object. The
3cb40 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 number of pages
3cb50 73 74 69 6c 6c 20 74 6f 20 62 65 20 62 61 63 6b still to be back
3cb60 65 64 0a 2a 2a 20 75 70 2c 20 77 68 69 63 68 20 ed.** up, which
3cb70 6d 61 79 20 62 65 20 71 75 65 72 69 65 64 20 62 may be queried b
3cb80 79 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 y sqlite3_backup
3cb90 5f 72 65 6d 61 69 6e 69 6e 67 28 29 2c 20 61 6e _remaining(), an
3cba0 64 20 74 68 65 20 74 6f 74 61 6c 0a 2a 2a 20 6e d the total.** n
3cbb0 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 69 umber of pages i
3cbc0 6e 20 74 68 65 20 73 6f 75 72 63 65 20 64 61 74 n the source dat
3cbd0 61 62 61 73 65 20 66 69 6c 65 2c 20 77 68 69 63 abase file, whic
3cbe0 68 20 6d 61 79 20 62 65 20 71 75 65 72 69 65 64 h may be queried
3cbf0 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 by.** sqlite3_b
3cc00 61 63 6b 75 70 5f 70 61 67 65 63 6f 75 6e 74 28 ackup_pagecount(
3cc10 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c )..**.** The val
3cc20 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 ues returned by
3cc30 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 these functions
3cc40 61 72 65 20 6f 6e 6c 79 20 75 70 64 61 74 65 64 are only updated
3cc50 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 by.** sqlite3_b
3cc60 61 63 6b 75 70 5f 73 74 65 70 28 29 2e 20 49 66 ackup_step(). If
3cc70 20 74 68 65 20 73 6f 75 72 63 65 20 64 61 74 61 the source data
3cc80 62 61 73 65 20 69 73 20 6d 6f 64 69 66 69 65 64 base is modified
3cc90 20 64 75 72 69 6e 67 20 61 20 62 61 63 6b 75 70 during a backup
3cca0 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 2c 20 74 .** operation, t
3ccb0 68 65 6e 20 74 68 65 20 76 61 6c 75 65 73 20 61 hen the values a
3ccc0 72 65 20 6e 6f 74 20 75 70 64 61 74 65 64 20 74 re not updated t
3ccd0 6f 20 61 63 63 6f 75 6e 74 20 66 6f 72 20 61 6e o account for an
3cce0 79 20 65 78 74 72 61 0a 2a 2a 20 70 61 67 65 73 y extra.** pages
3ccf0 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 62 65 that need to be
3cd00 20 75 70 64 61 74 65 64 20 6f 72 20 74 68 65 20 updated or the
3cd10 73 69 7a 65 20 6f 66 20 74 68 65 20 73 6f 75 72 size of the sour
3cd20 63 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 ce database file
3cd30 0a 2a 2a 20 63 68 61 6e 67 69 6e 67 2e 0a 2a 2a .** changing..**
3cd40 0a 2a 2a 20 3c 62 3e 43 6f 6e 63 75 72 72 65 6e .** <b>Concurren
3cd50 74 20 55 73 61 67 65 20 6f 66 20 44 61 74 61 62 t Usage of Datab
3cd60 61 73 65 20 48 61 6e 64 6c 65 73 3c 2f 62 3e 0a ase Handles</b>.
3cd70 2a 2a 0a 2a 2a 20 54 68 65 20 73 6f 75 72 63 65 **.** The source
3cd80 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
3cd90 63 74 69 6f 6e 5d 20 6d 61 79 20 62 65 20 75 73 ction] may be us
3cda0 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 ed by the applic
3cdb0 61 74 69 6f 6e 20 66 6f 72 20 6f 74 68 65 72 0a ation for other.
3cdc0 2a 2a 20 70 75 72 70 6f 73 65 73 20 77 68 69 6c ** purposes whil
3cdd0 65 20 61 20 62 61 63 6b 75 70 20 6f 70 65 72 61 e a backup opera
3cde0 74 69 6f 6e 20 69 73 20 75 6e 64 65 72 77 61 79 tion is underway
3cdf0 20 6f 72 20 62 65 69 6e 67 20 69 6e 69 74 69 61 or being initia
3ce00 6c 69 7a 65 64 2e 0a 2a 2a 20 49 66 20 53 51 4c lized..** If SQL
3ce10 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
3ce20 61 6e 64 20 63 6f 6e 66 69 67 75 72 65 64 20 74 and configured t
3ce30 6f 20 73 75 70 70 6f 72 74 20 74 68 72 65 61 64 o support thread
3ce40 73 61 66 65 20 64 61 74 61 62 61 73 65 0a 2a 2a safe database.**
3ce50 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2c 20 74 68 connections, th
3ce60 65 6e 20 74 68 65 20 73 6f 75 72 63 65 20 64 61 en the source da
3ce70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
3ce80 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20 63 6f n may be used co
3ce90 6e 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 66 72 ncurrently.** fr
3cea0 6f 6d 20 77 69 74 68 69 6e 20 6f 74 68 65 72 20 om within other
3ceb0 74 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 48 threads..**.** H
3cec0 6f 77 65 76 65 72 2c 20 74 68 65 20 61 70 70 6c owever, the appl
3ced0 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 67 75 61 ication must gua
3cee0 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 65 20 rantee that the
3cef0 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 destination data
3cf00 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 base.** connecti
3cf10 6f 6e 20 68 61 6e 64 6c 65 20 69 73 20 6e 6f 74 on handle is not
3cf20 20 70 61 73 73 65 64 20 74 6f 20 61 6e 79 20 6f passed to any o
3cf30 74 68 65 72 20 41 50 49 20 28 62 79 20 61 6e 79 ther API (by any
3cf40 20 74 68 72 65 61 64 29 20 61 66 74 65 72 20 0a thread) after .
3cf50 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 ** sqlite3_backu
3cf60 70 5f 69 6e 69 74 28 29 20 69 73 20 63 61 6c 6c p_init() is call
3cf70 65 64 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 ed and before th
3cf80 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 e corresponding
3cf90 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 call to.** sqlit
3cfa0 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 e3_backup_finish
3cfb0 28 29 2e 20 55 6e 66 6f 72 74 75 6e 61 74 65 6c (). Unfortunatel
3cfc0 79 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f y SQLite does no
3cfd0 74 20 63 75 72 72 65 6e 74 6c 79 20 63 68 65 63 t currently chec
3cfe0 6b 0a 2a 2a 20 66 6f 72 20 74 68 69 73 2c 20 69 k.** for this, i
3cff0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
3d000 6e 20 64 6f 65 73 20 75 73 65 20 74 68 65 20 64 n does use the d
3d010 65 73 74 69 6e 61 74 69 6f 6e 20 5b 64 61 74 61 estination [data
3d020 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
3d030 0a 2a 2a 20 66 6f 72 20 73 6f 6d 65 20 6f 74 68 .** for some oth
3d040 65 72 20 70 75 72 70 6f 73 65 20 64 75 72 69 6e er purpose durin
3d050 67 20 61 20 62 61 63 6b 75 70 20 6f 70 65 72 61 g a backup opera
3d060 74 69 6f 6e 2c 20 74 68 69 6e 67 73 20 6d 61 79 tion, things may
3d070 20 61 70 70 65 61 72 20 74 6f 0a 2a 2a 20 77 6f appear to.** wo
3d080 72 6b 20 63 6f 72 72 65 63 74 6c 79 20 62 75 74 rk correctly but
3d090 20 69 6e 20 66 61 63 74 20 62 65 20 73 75 62 74 in fact be subt
3d0a0 6c 79 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 69 6e ly malfunctionin
3d0b0 67 2e 20 20 55 73 65 20 6f 66 20 74 68 65 0a 2a g. Use of the.*
3d0c0 2a 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 * destination da
3d0d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
3d0e0 6e 20 77 68 69 6c 65 20 61 20 62 61 63 6b 75 70 n while a backup
3d0f0 20 69 73 20 69 6e 20 70 72 6f 67 72 65 73 73 20 is in progress
3d100 6d 69 67 68 74 0a 2a 2a 20 61 6c 73 6f 20 63 61 might.** also ca
3d110 75 73 65 20 61 20 6d 75 74 65 78 20 64 65 61 64 use a mutex dead
3d120 6c 6f 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 75 72 74 lock..**.** Furt
3d130 68 65 72 6d 6f 72 65 2c 20 69 66 20 72 75 6e 6e hermore, if runn
3d140 69 6e 67 20 69 6e 20 5b 73 68 61 72 65 64 20 63 ing in [shared c
3d150 61 63 68 65 20 6d 6f 64 65 5d 2c 20 74 68 65 20 ache mode], the
3d160 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
3d170 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 20 74 68 .** guarantee th
3d180 61 74 20 74 68 65 20 73 68 61 72 65 64 20 63 61 at the shared ca
3d190 63 68 65 20 75 73 65 64 20 62 79 20 74 68 65 20 che used by the
3d1a0 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 destination data
3d1b0 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 base.** is not a
3d1c0 63 63 65 73 73 65 64 20 77 68 69 6c 65 20 74 68 ccessed while th
3d1d0 65 20 62 61 63 6b 75 70 20 69 73 20 72 75 6e 6e e backup is runn
3d1e0 69 6e 67 2e 20 49 6e 20 70 72 61 63 74 69 63 65 ing. In practice
3d1f0 20 74 68 69 73 20 6d 65 61 6e 73 0a 2a 2a 20 74 this means.** t
3d200 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 hat the applicat
3d210 69 6f 6e 20 6d 75 73 74 20 67 75 61 72 61 6e 74 ion must guarant
3d220 65 65 20 74 68 61 74 20 74 68 65 20 66 69 6c 65 ee that the file
3d230 2d 73 79 73 74 65 6d 20 66 69 6c 65 20 62 65 69 -system file bei
3d240 6e 67 20 0a 2a 2a 20 62 61 63 6b 65 64 20 75 70 ng .** backed up
3d250 20 74 6f 20 69 73 20 6e 6f 74 20 61 63 63 65 73 to is not acces
3d260 73 65 64 20 62 79 20 61 6e 79 20 63 6f 6e 6e 65 sed by any conne
3d270 63 74 69 6f 6e 20 77 69 74 68 69 6e 20 74 68 65 ction within the
3d280 20 70 72 6f 63 65 73 73 2c 0a 2a 2a 20 6e 6f 74 process,.** not
3d290 20 6a 75 73 74 20 74 68 65 20 73 70 65 63 69 66 just the specif
3d2a0 69 63 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 ic connection th
3d2b0 61 74 20 77 61 73 20 70 61 73 73 65 64 20 74 6f at was passed to
3d2c0 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f sqlite3_backup_
3d2d0 69 6e 69 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 init()..**.** Th
3d2e0 65 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 e [sqlite3_backu
3d2f0 70 5d 20 6f 62 6a 65 63 74 20 69 74 73 65 6c 66 p] object itself
3d300 20 69 73 20 70 61 72 74 69 61 6c 6c 79 20 74 68 is partially th
3d310 72 65 61 64 73 61 66 65 2e 20 4d 75 6c 74 69 70 readsafe. Multip
3d320 6c 65 20 0a 2a 2a 20 74 68 72 65 61 64 73 20 6d le .** threads m
3d330 61 79 20 73 61 66 65 6c 79 20 6d 61 6b 65 20 6d ay safely make m
3d340 75 6c 74 69 70 6c 65 20 63 6f 6e 63 75 72 72 65 ultiple concurre
3d350 6e 74 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 nt calls to sqli
3d360 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 te3_backup_step(
3d370 29 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 )..** However, t
3d380 68 65 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 he sqlite3_backu
3d390 70 5f 72 65 6d 61 69 6e 69 6e 67 28 29 20 61 6e p_remaining() an
3d3a0 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 d sqlite3_backup
3d3b0 5f 70 61 67 65 63 6f 75 6e 74 28 29 0a 2a 2a 20 _pagecount().**
3d3c0 41 50 49 73 20 61 72 65 20 6e 6f 74 20 73 74 72 APIs are not str
3d3d0 69 63 74 6c 79 20 73 70 65 61 6b 69 6e 67 20 74 ictly speaking t
3d3e0 68 72 65 61 64 73 61 66 65 2e 20 49 66 20 74 68 hreadsafe. If th
3d3f0 65 79 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 61 ey are invoked a
3d400 74 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 74 69 t the.** same ti
3d410 6d 65 20 61 73 20 61 6e 6f 74 68 65 72 20 74 68 me as another th
3d420 72 65 61 64 20 69 73 20 69 6e 76 6f 6b 69 6e 67 read is invoking
3d430 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f sqlite3_backup_
3d440 73 74 65 70 28 29 20 69 74 20 69 73 0a 2a 2a 20 step() it is.**
3d450 70 6f 73 73 69 62 6c 65 20 74 68 61 74 20 74 68 possible that th
3d460 65 79 20 72 65 74 75 72 6e 20 69 6e 76 61 6c 69 ey return invali
3d470 64 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 73 71 6c d values..*/.sql
3d480 69 74 65 33 5f 62 61 63 6b 75 70 20 2a 73 71 6c ite3_backup *sql
3d490 69 74 65 33 5f 62 61 63 6b 75 70 5f 69 6e 69 74 ite3_backup_init
3d4a0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 70 44 65 (. sqlite3 *pDe
3d4b0 73 74 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 st,
3d4c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 65 /* De
3d4d0 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 stination databa
3d4e0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 se handle */. c
3d4f0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 65 73 74 onst char *zDest
3d500 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 20 20 Name,
3d510 20 20 20 20 20 20 2f 2a 20 44 65 73 74 69 6e 61 /* Destina
3d520 74 69 6f 6e 20 64 61 74 61 62 61 73 65 20 6e 61 tion database na
3d530 6d 65 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 me */. sqlite3
3d540 2a 70 53 6f 75 72 63 65 2c 20 20 20 20 20 20 20 *pSource,
3d550 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
3d560 2a 20 53 6f 75 72 63 65 20 64 61 74 61 62 61 73 * Source databas
3d570 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f e handle */. co
3d580 6e 73 74 20 63 68 61 72 20 2a 7a 53 6f 75 72 63 nst char *zSourc
3d590 65 4e 61 6d 65 20 20 20 20 20 20 20 20 20 20 20 eName
3d5a0 20 20 20 20 20 2f 2a 20 53 6f 75 72 63 65 20 64 /* Source d
3d5b0 61 74 61 62 61 73 65 20 6e 61 6d 65 20 2a 2f 0a atabase name */.
3d5c0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 );.int sqlite3_b
3d5d0 61 63 6b 75 70 5f 73 74 65 70 28 73 71 6c 69 74 ackup_step(sqlit
3d5e0 65 33 5f 62 61 63 6b 75 70 20 2a 70 2c 20 69 6e e3_backup *p, in
3d5f0 74 20 6e 50 61 67 65 29 3b 0a 69 6e 74 20 73 71 t nPage);.int sq
3d600 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e lite3_backup_fin
3d610 69 73 68 28 73 71 6c 69 74 65 33 5f 62 61 63 6b ish(sqlite3_back
3d620 75 70 20 2a 70 29 3b 0a 69 6e 74 20 73 71 6c 69 up *p);.int sqli
3d630 74 65 33 5f 62 61 63 6b 75 70 5f 72 65 6d 61 69 te3_backup_remai
3d640 6e 69 6e 67 28 73 71 6c 69 74 65 33 5f 62 61 63 ning(sqlite3_bac
3d650 6b 75 70 20 2a 70 29 3b 0a 69 6e 74 20 73 71 6c kup *p);.int sql
3d660 69 74 65 33 5f 62 61 63 6b 75 70 5f 70 61 67 65 ite3_backup_page
3d670 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 62 61 count(sqlite3_ba
3d680 63 6b 75 70 20 2a 70 29 3b 0a 0a 2f 2a 0a 2a 2a ckup *p);../*.**
3d690 20 43 41 50 49 33 52 45 46 3a 20 55 6e 6c 6f 63 CAPI3REF: Unloc
3d6a0 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 0a 2a k Notification.*
3d6b0 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
3d6c0 2a 0a 2a 2a 20 57 68 65 6e 20 72 75 6e 6e 69 6e *.** When runnin
3d6d0 67 20 69 6e 20 73 68 61 72 65 64 2d 63 61 63 68 g in shared-cach
3d6e0 65 20 6d 6f 64 65 2c 20 61 20 64 61 74 61 62 61 e mode, a databa
3d6f0 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 6d 61 79 se operation may
3d700 20 66 61 69 6c 20 77 69 74 68 0a 2a 2a 20 61 6e fail with.** an
3d710 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5d [SQLITE_LOCKED]
3d720 20 65 72 72 6f 72 20 69 66 20 74 68 65 20 72 65 error if the re
3d730 71 75 69 72 65 64 20 6c 6f 63 6b 73 20 6f 6e 20 quired locks on
3d740 74 68 65 20 73 68 61 72 65 64 2d 63 61 63 68 65 the shared-cache
3d750 20 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 64 75 61 or.** individua
3d760 6c 20 74 61 62 6c 65 73 20 77 69 74 68 69 6e 20 l tables within
3d770 74 68 65 20 73 68 61 72 65 64 2d 63 61 63 68 65 the shared-cache
3d780 20 63 61 6e 6e 6f 74 20 62 65 20 6f 62 74 61 69 cannot be obtai
3d790 6e 65 64 2e 20 53 65 65 0a 2a 2a 20 5b 53 51 4c ned. See.** [SQL
3d7a0 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 ite Shared-Cache
3d7b0 20 4d 6f 64 65 5d 20 66 6f 72 20 61 20 64 65 73 Mode] for a des
3d7c0 63 72 69 70 74 69 6f 6e 20 6f 66 20 73 68 61 72 cription of shar
3d7d0 65 64 2d 63 61 63 68 65 20 6c 6f 63 6b 69 6e 67 ed-cache locking
3d7e0 2e 20 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 6d . .** This API m
3d7f0 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 ay be used to re
3d800 67 69 73 74 65 72 20 61 20 63 61 6c 6c 62 61 63 gister a callbac
3d810 6b 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 k that SQLite wi
3d820 6c 6c 20 69 6e 76 6f 6b 65 20 0a 2a 2a 20 77 68 ll invoke .** wh
3d830 65 6e 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f en the connectio
3d840 6e 20 63 75 72 72 65 6e 74 6c 79 20 68 6f 6c 64 n currently hold
3d850 69 6e 67 20 74 68 65 20 72 65 71 75 69 72 65 64 ing the required
3d860 20 6c 6f 63 6b 20 72 65 6c 69 6e 71 75 69 73 68 lock relinquish
3d870 65 73 20 69 74 2e 0a 2a 2a 20 54 68 69 73 20 41 es it..** This A
3d880 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c PI is only avail
3d890 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 able if the libr
3d8a0 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 ary was compiled
3d8b0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 with the.** [SQ
3d8c0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 55 4e 4c 4f LITE_ENABLE_UNLO
3d8d0 43 4b 5f 4e 4f 54 49 46 59 5d 20 43 2d 70 72 65 CK_NOTIFY] C-pre
3d8e0 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c processor symbol
3d8f0 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 defined..**.**
3d900 53 65 65 20 41 6c 73 6f 3a 20 5b 55 73 69 6e 67 See Also: [Using
3d910 20 74 68 65 20 53 51 4c 69 74 65 20 55 6e 6c 6f the SQLite Unlo
3d920 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 ck Notification
3d930 46 65 61 74 75 72 65 5d 2e 0a 2a 2a 0a 2a 2a 20 Feature]..**.**
3d940 53 68 61 72 65 64 2d 63 61 63 68 65 20 6c 6f 63 Shared-cache loc
3d950 6b 73 20 61 72 65 20 72 65 6c 65 61 73 65 64 20 ks are released
3d960 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 when a database
3d970 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6f 6e 63 6c connection concl
3d980 75 64 65 73 0a 2a 2a 20 69 74 73 20 63 75 72 72 udes.** its curr
3d990 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c ent transaction,
3d9a0 20 65 69 74 68 65 72 20 62 79 20 63 6f 6d 6d 69 either by commi
3d9b0 74 74 69 6e 67 20 69 74 20 6f 72 20 72 6f 6c 6c tting it or roll
3d9c0 69 6e 67 20 69 74 20 62 61 63 6b 2e 20 0a 2a 2a ing it back. .**
3d9d0 0a 2a 2a 20 57 68 65 6e 20 61 20 63 6f 6e 6e 65 .** When a conne
3d9e0 63 74 69 6f 6e 20 28 6b 6e 6f 77 6e 20 61 73 20 ction (known as
3d9f0 74 68 65 20 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e the blocked conn
3da00 65 63 74 69 6f 6e 29 20 66 61 69 6c 73 20 74 6f ection) fails to
3da10 20 6f 62 74 61 69 6e 20 61 0a 2a 2a 20 73 68 61 obtain a.** sha
3da20 72 65 64 2d 63 61 63 68 65 20 6c 6f 63 6b 20 61 red-cache lock a
3da30 6e 64 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 nd SQLITE_LOCKED
3da40 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 is returned to
3da50 74 68 65 20 63 61 6c 6c 65 72 2c 20 74 68 65 0a the caller, the.
3da60 2a 2a 20 69 64 65 6e 74 69 74 79 20 6f 66 20 74 ** identity of t
3da70 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
3da80 65 63 74 69 6f 6e 20 28 74 68 65 20 62 6c 6f 63 ection (the bloc
3da90 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 69 6f 6e 29 king connection)
3daa0 20 74 68 61 74 0a 2a 2a 20 68 61 73 20 6c 6f 63 that.** has loc
3dab0 6b 65 64 20 74 68 65 20 72 65 71 75 69 72 65 64 ked the required
3dac0 20 72 65 73 6f 75 72 63 65 20 69 73 20 73 74 6f resource is sto
3dad0 72 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 20 red internally.
3dae0 41 66 74 65 72 20 61 6e 20 0a 2a 2a 20 61 70 70 After an .** app
3daf0 6c 69 63 61 74 69 6f 6e 20 72 65 63 65 69 76 65 lication receive
3db00 73 20 61 6e 20 53 51 4c 49 54 45 5f 4c 4f 43 4b s an SQLITE_LOCK
3db10 45 44 20 65 72 72 6f 72 2c 20 69 74 20 6d 61 79 ED error, it may
3db20 20 63 61 6c 6c 20 74 68 65 0a 2a 2a 20 73 71 6c call the.** sql
3db30 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 ite3_unlock_noti
3db40 66 79 28 29 20 6d 65 74 68 6f 64 20 77 69 74 68 fy() method with
3db50 20 74 68 65 20 62 6c 6f 63 6b 65 64 20 63 6f 6e the blocked con
3db60 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 61 nection handle a
3db70 73 20 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 s .** the first
3db80 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 65 67 69 argument to regi
3db90 73 74 65 72 20 66 6f 72 20 61 20 63 61 6c 6c 62 ster for a callb
3dba0 61 63 6b 20 74 68 61 74 20 77 69 6c 6c 20 62 65 ack that will be
3dbb0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e invoked.** when
3dbc0 20 74 68 65 20 62 6c 6f 63 6b 69 6e 67 20 63 6f the blocking co
3dbd0 6e 6e 65 63 74 69 6f 6e 73 20 63 75 72 72 65 6e nnections curren
3dbe0 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 t transaction is
3dbf0 20 63 6f 6e 63 6c 75 64 65 64 2e 20 54 68 65 0a concluded. The.
3dc00 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 ** callback is i
3dc10 6e 76 6f 6b 65 64 20 66 72 6f 6d 20 77 69 74 68 nvoked from with
3dc20 69 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f in the [sqlite3_
3dc30 73 74 65 70 5d 20 6f 72 20 5b 73 71 6c 69 74 65 step] or [sqlite
3dc40 33 5f 63 6c 6f 73 65 5d 0a 2a 2a 20 63 61 6c 6c 3_close].** call
3dc50 20 74 68 61 74 20 63 6f 6e 63 6c 75 64 65 73 20 that concludes
3dc60 74 68 65 20 62 6c 6f 63 6b 69 6e 67 20 63 6f 6e the blocking con
3dc70 6e 65 63 74 69 6f 6e 73 20 74 72 61 6e 73 61 63 nections transac
3dc80 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 tion..**.** If s
3dc90 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f qlite3_unlock_no
3dca0 74 69 66 79 28 29 20 69 73 20 63 61 6c 6c 65 64 tify() is called
3dcb0 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 in a multi-thre
3dcc0 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e aded application
3dcd0 2c 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 61 20 ,.** there is a
3dce0 63 68 61 6e 63 65 20 74 68 61 74 20 74 68 65 20 chance that the
3dcf0 62 6c 6f 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 blocking connect
3dd00 69 6f 6e 20 77 69 6c 6c 20 68 61 76 65 20 61 6c ion will have al
3dd10 72 65 61 64 79 0a 2a 2a 20 63 6f 6e 63 6c 75 64 ready.** conclud
3dd20 65 64 20 69 74 73 20 74 72 61 6e 73 61 63 74 69 ed its transacti
3dd30 6f 6e 20 62 79 20 74 68 65 20 74 69 6d 65 20 73 on by the time s
3dd40 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f qlite3_unlock_no
3dd50 74 69 66 79 28 29 20 69 73 20 69 6e 76 6f 6b 65 tify() is invoke
3dd60 64 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 68 61 d..** If this ha
3dd70 70 70 65 6e 73 2c 20 74 68 65 6e 20 74 68 65 20 ppens, then the
3dd80 73 70 65 63 69 66 69 65 64 20 63 61 6c 6c 62 61 specified callba
3dd90 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6d ck is invoked im
3dda0 6d 65 64 69 61 74 65 6c 79 2c 0a 2a 2a 20 66 72 mediately,.** fr
3ddb0 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 63 61 om within the ca
3ddc0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 6e ll to sqlite3_un
3ddd0 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 2e 0a 2a lock_notify()..*
3dde0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 62 6c 6f 63 *.** If the bloc
3ddf0 6b 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ked connection i
3de00 73 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 s attempting to
3de10 6f 62 74 61 69 6e 20 61 20 77 72 69 74 65 2d 6c obtain a write-l
3de20 6f 63 6b 20 6f 6e 20 61 0a 2a 2a 20 73 68 61 72 ock on a.** shar
3de30 65 64 2d 63 61 63 68 65 20 74 61 62 6c 65 2c 20 ed-cache table,
3de40 61 6e 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e and more than on
3de50 65 20 6f 74 68 65 72 20 63 6f 6e 6e 65 63 74 69 e other connecti
3de60 6f 6e 20 63 75 72 72 65 6e 74 6c 79 20 68 6f 6c on currently hol
3de70 64 73 0a 2a 2a 20 61 20 72 65 61 64 2d 6c 6f 63 ds.** a read-loc
3de80 6b 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 74 61 k on the same ta
3de90 62 6c 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 ble, then SQLite
3dea0 20 61 72 62 69 74 72 61 72 69 6c 79 20 73 65 6c arbitrarily sel
3deb0 65 63 74 73 20 6f 6e 65 20 6f 66 20 0a 2a 2a 20 ects one of .**
3dec0 74 68 65 20 6f 74 68 65 72 20 63 6f 6e 6e 65 63 the other connec
3ded0 74 69 6f 6e 73 20 74 6f 20 75 73 65 20 61 73 20 tions to use as
3dee0 74 68 65 20 62 6c 6f 63 6b 69 6e 67 20 63 6f 6e the blocking con
3def0 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 nection..**.** T
3df00 68 65 72 65 20 6d 61 79 20 62 65 20 61 74 20 6d here may be at m
3df10 6f 73 74 20 6f 6e 65 20 75 6e 6c 6f 63 6b 2d 6e ost one unlock-n
3df20 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 72 otify callback r
3df30 65 67 69 73 74 65 72 65 64 20 62 79 20 61 20 0a egistered by a .
3df40 2a 2a 20 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e 65 ** blocked conne
3df50 63 74 69 6f 6e 2e 20 49 66 20 73 71 6c 69 74 65 ction. If sqlite
3df60 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 3_unlock_notify(
3df70 29 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e ) is called when
3df80 20 74 68 65 0a 2a 2a 20 62 6c 6f 63 6b 65 64 20 the.** blocked
3df90 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6c 72 65 61 connection alrea
3dfa0 64 79 20 68 61 73 20 61 20 72 65 67 69 73 74 65 dy has a registe
3dfb0 72 65 64 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 red unlock-notif
3dfc0 79 20 63 61 6c 6c 62 61 63 6b 2c 0a 2a 2a 20 74 y callback,.** t
3dfd0 68 65 6e 20 74 68 65 20 6e 65 77 20 63 61 6c 6c hen the new call
3dfe0 62 61 63 6b 20 72 65 70 6c 61 63 65 73 20 74 68 back replaces th
3dff0 65 20 6f 6c 64 2e 20 49 66 20 73 71 6c 69 74 65 e old. If sqlite
3e000 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 3_unlock_notify(
3e010 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 77 ) is.** called w
3e020 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 ith a NULL point
3e030 65 72 20 61 73 20 69 74 73 20 73 65 63 6f 6e 64 er as its second
3e040 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 65 6e 20 argument, then
3e050 61 6e 79 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 any existing.**
3e060 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 unlock-notify ca
3e070 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e 63 65 6c llback is cancel
3e080 6c 65 64 2e 20 54 68 65 20 62 6c 6f 63 6b 65 64 led. The blocked
3e090 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 0a 2a 2a connections .**
3e0a0 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 unlock-notify c
3e0b0 61 6c 6c 62 61 63 6b 20 6d 61 79 20 61 6c 73 6f allback may also
3e0c0 20 62 65 20 63 61 6e 63 65 6c 65 64 20 62 79 20 be canceled by
3e0d0 63 6c 6f 73 69 6e 67 20 74 68 65 20 62 6c 6f 63 closing the bloc
3e0e0 6b 65 64 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f ked.** connectio
3e0f0 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 n using [sqlite3
3e100 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a _close()]..**.**
3e110 20 54 68 65 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 The unlock-noti
3e120 66 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e fy callback is n
3e130 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 49 66 ot reentrant. If
3e140 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 an application
3e150 69 6e 76 6f 6b 65 73 0a 2a 2a 20 61 6e 79 20 73 invokes.** any s
3e160 71 6c 69 74 65 33 5f 78 78 78 20 41 50 49 20 66 qlite3_xxx API f
3e170 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 77 69 unctions from wi
3e180 74 68 69 6e 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e thin an unlock-n
3e190 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b 2c 20 otify callback,
3e1a0 61 0a 2a 2a 20 63 72 61 73 68 20 6f 72 20 64 65 a.** crash or de
3e1b0 61 64 6c 6f 63 6b 20 6d 61 79 20 62 65 20 74 68 adlock may be th
3e1c0 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 e result..**.**
3e1d0 55 6e 6c 65 73 73 20 64 65 61 64 6c 6f 63 6b 20 Unless deadlock
3e1e0 69 73 20 64 65 74 65 63 74 65 64 20 28 73 65 65 is detected (see
3e1f0 20 62 65 6c 6f 77 29 2c 20 73 71 6c 69 74 65 33 below), sqlite3
3e200 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 _unlock_notify()
3e210 20 61 6c 77 61 79 73 0a 2a 2a 20 72 65 74 75 72 always.** retur
3e220 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a ns SQLITE_OK..**
3e230 0a 2a 2a 20 3c 62 3e 43 61 6c 6c 62 61 63 6b 20 .** <b>Callback
3e240 49 6e 76 6f 63 61 74 69 6f 6e 20 44 65 74 61 69 Invocation Detai
3e250 6c 73 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 ls</b>.**.** Whe
3e260 6e 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 n an unlock-noti
3e270 66 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 72 fy callback is r
3e280 65 67 69 73 74 65 72 65 64 2c 20 74 68 65 20 61 egistered, the a
3e290 70 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 pplication provi
3e2a0 64 65 73 20 61 20 0a 2a 2a 20 73 69 6e 67 6c 65 des a .** single
3e2b0 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 74 void* pointer t
3e2c0 68 61 74 20 69 73 20 70 61 73 73 65 64 20 74 6f hat is passed to
3e2d0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 68 the callback wh
3e2e0 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 en it is invoked
3e2f0 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 ..** However, th
3e300 65 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 74 e signature of t
3e310 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 he callback func
3e320 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 53 51 4c 69 tion allows SQLi
3e330 74 65 20 74 6f 20 70 61 73 73 0a 2a 2a 20 69 74 te to pass.** it
3e340 20 61 6e 20 61 72 72 61 79 20 6f 66 20 76 6f 69 an array of voi
3e350 64 2a 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 d* context point
3e360 65 72 73 2e 20 54 68 65 20 66 69 72 73 74 20 61 ers. The first a
3e370 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 rgument passed t
3e380 6f 0a 2a 2a 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e o.** an unlock-n
3e390 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 69 otify callback i
3e3a0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
3e3b0 6e 20 61 72 72 61 79 20 6f 66 20 76 6f 69 64 2a n array of void*
3e3c0 20 70 6f 69 6e 74 65 72 73 2c 0a 2a 2a 20 61 6e pointers,.** an
3e3d0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 d the second is
3e3e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6e the number of en
3e3f0 74 72 69 65 73 20 69 6e 20 74 68 65 20 61 72 72 tries in the arr
3e400 61 79 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 ay..**.** When a
3e410 20 62 6c 6f 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 blocking connec
3e420 74 69 6f 6e 73 20 74 72 61 6e 73 61 63 74 69 6f tions transactio
3e430 6e 20 69 73 20 63 6f 6e 63 6c 75 64 65 64 2c 20 n is concluded,
3e440 74 68 65 72 65 20 6d 61 79 20 62 65 0a 2a 2a 20 there may be.**
3e450 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 62 6c more than one bl
3e460 6f 63 6b 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e ocked connection
3e470 20 74 68 61 74 20 68 61 73 20 72 65 67 69 73 74 that has regist
3e480 65 72 65 64 20 66 6f 72 20 61 6e 20 75 6e 6c 6f ered for an unlo
3e490 63 6b 2d 6e 6f 74 69 66 79 0a 2a 2a 20 63 61 6c ck-notify.** cal
3e4a0 6c 62 61 63 6b 2e 20 49 66 20 74 77 6f 20 6f 72 lback. If two or
3e4b0 20 6d 6f 72 65 20 73 75 63 68 20 62 6c 6f 63 6b more such block
3e4c0 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 68 ed connections h
3e4d0 61 76 65 20 73 70 65 63 69 66 69 65 64 20 74 68 ave specified th
3e4e0 65 0a 2a 2a 20 73 61 6d 65 20 63 61 6c 6c 62 61 e.** same callba
3e4f0 63 6b 20 66 75 6e 63 74 69 6f 6e 2c 20 74 68 65 ck function, the
3e500 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 n instead of inv
3e510 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 oking the callba
3e520 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d ck function.** m
3e530 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 2c 20 69 ultiple times, i
3e540 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 t is invoked onc
3e550 65 20 77 69 74 68 20 74 68 65 20 73 65 74 20 6f e with the set o
3e560 66 20 76 6f 69 64 2a 20 63 6f 6e 74 65 78 74 20 f void* context
3e570 70 6f 69 6e 74 65 72 73 0a 2a 2a 20 73 70 65 63 pointers.** spec
3e580 69 66 69 65 64 20 62 79 20 74 68 65 20 62 6c 6f ified by the blo
3e590 63 6b 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 cked connections
3e5a0 20 62 75 6e 64 6c 65 64 20 74 6f 67 65 74 68 65 bundled togethe
3e5b0 72 20 69 6e 74 6f 20 61 6e 20 61 72 72 61 79 2e r into an array.
3e5c0 0a 2a 2a 20 54 68 69 73 20 67 69 76 65 73 20 74 .** This gives t
3e5d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 61 he application a
3e5e0 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 20 74 6f n opportunity to
3e5f0 20 70 72 69 6f 72 69 74 69 7a 65 20 61 6e 79 20 prioritize any
3e600 61 63 74 69 6f 6e 73 20 0a 2a 2a 20 72 65 6c 61 actions .** rela
3e610 74 65 64 20 74 6f 20 74 68 65 20 73 65 74 20 6f ted to the set o
3e620 66 20 75 6e 62 6c 6f 63 6b 65 64 20 64 61 74 61 f unblocked data
3e630 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
3e640 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 44 65 61 64 6c ..**.** <b>Deadl
3e650 6f 63 6b 20 44 65 74 65 63 74 69 6f 6e 3c 2f 62 ock Detection</b
3e660 3e 0a 2a 2a 0a 2a 2a 20 41 73 73 75 6d 69 6e 67 >.**.** Assuming
3e670 20 74 68 61 74 20 61 66 74 65 72 20 72 65 67 69 that after regi
3e680 73 74 65 72 69 6e 67 20 66 6f 72 20 61 6e 20 75 stering for an u
3e690 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c nlock-notify cal
3e6a0 6c 62 61 63 6b 20 61 20 0a 2a 2a 20 64 61 74 61 lback a .** data
3e6b0 62 61 73 65 20 77 61 69 74 73 20 66 6f 72 20 74 base waits for t
3e6c0 68 65 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 he callback to b
3e6d0 65 20 69 73 73 75 65 64 20 62 65 66 6f 72 65 20 e issued before
3e6e0 74 61 6b 69 6e 67 20 61 6e 79 20 66 75 72 74 68 taking any furth
3e6f0 65 72 0a 2a 2a 20 61 63 74 69 6f 6e 20 28 61 20 er.** action (a
3e700 72 65 61 73 6f 6e 61 62 6c 65 20 61 73 73 75 6d reasonable assum
3e710 70 74 69 6f 6e 29 2c 20 74 68 65 6e 20 75 73 69 ption), then usi
3e720 6e 67 20 74 68 69 73 20 41 50 49 20 6d 61 79 20 ng this API may
3e730 63 61 75 73 65 20 74 68 65 0a 2a 2a 20 61 70 70 cause the.** app
3e740 6c 69 63 61 74 69 6f 6e 20 74 6f 20 64 65 61 64 lication to dead
3e750 6c 6f 63 6b 2e 20 46 6f 72 20 65 78 61 6d 70 6c lock. For exampl
3e760 65 2c 20 69 66 20 63 6f 6e 6e 65 63 74 69 6f 6e e, if connection
3e770 20 58 20 69 73 20 77 61 69 74 69 6e 67 20 66 6f X is waiting fo
3e780 72 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 r.** connection
3e790 59 27 73 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 Y's transaction
3e7a0 74 6f 20 62 65 20 63 6f 6e 63 6c 75 64 65 64 2c to be concluded,
3e7b0 20 61 6e 64 20 73 69 6d 69 6c 61 72 6c 79 20 63 and similarly c
3e7c0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 59 20 69 onnection.** Y i
3e7d0 73 20 77 61 69 74 69 6e 67 20 6f 6e 20 63 6f 6e s waiting on con
3e7e0 6e 65 63 74 69 6f 6e 20 58 27 73 20 74 72 61 6e nection X's tran
3e7f0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 6e 65 saction, then ne
3e800 69 74 68 65 72 20 63 6f 6e 6e 65 63 74 69 6f 6e ither connection
3e810 0a 2a 2a 20 77 69 6c 6c 20 70 72 6f 63 65 65 64 .** will proceed
3e820 20 61 6e 64 20 74 68 65 20 73 79 73 74 65 6d 20 and the system
3e830 6d 61 79 20 72 65 6d 61 69 6e 20 64 65 61 64 6c may remain deadl
3e840 6f 63 6b 65 64 20 69 6e 64 65 66 69 6e 69 74 65 ocked indefinite
3e850 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f ly..**.** To avo
3e860 69 64 20 74 68 69 73 20 73 63 65 6e 61 72 69 6f id this scenario
3e870 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 75 6e , the sqlite3_un
3e880 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 20 70 65 lock_notify() pe
3e890 72 66 6f 72 6d 73 20 64 65 61 64 6c 6f 63 6b 0a rforms deadlock.
3e8a0 2a 2a 20 64 65 74 65 63 74 69 6f 6e 2e 20 49 66 ** detection. If
3e8b0 20 61 20 67 69 76 65 6e 20 63 61 6c 6c 20 74 6f a given call to
3e8c0 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f sqlite3_unlock_
3e8d0 6e 6f 74 69 66 79 28 29 20 77 6f 75 6c 64 20 70 notify() would p
3e8e0 75 74 20 74 68 65 0a 2a 2a 20 73 79 73 74 65 6d ut the.** system
3e8f0 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 65 64 in a deadlocked
3e900 20 73 74 61 74 65 2c 20 74 68 65 6e 20 53 51 4c state, then SQL
3e910 49 54 45 5f 4c 4f 43 4b 45 44 20 69 73 20 72 65 ITE_LOCKED is re
3e920 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 0a 2a 2a turned and no.**
3e930 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 unlock-notify c
3e940 61 6c 6c 62 61 63 6b 20 69 73 20 72 65 67 69 73 allback is regis
3e950 74 65 72 65 64 2e 20 54 68 65 20 73 79 73 74 65 tered. The syste
3e960 6d 20 69 73 20 73 61 69 64 20 74 6f 20 62 65 20 m is said to be
3e970 69 6e 0a 2a 2a 20 61 20 64 65 61 64 6c 6f 63 6b in.** a deadlock
3e980 65 64 20 73 74 61 74 65 20 69 66 20 63 6f 6e 6e ed state if conn
3e990 65 63 74 69 6f 6e 20 41 20 68 61 73 20 72 65 67 ection A has reg
3e9a0 69 73 74 65 72 65 64 20 66 6f 72 20 61 6e 20 75 istered for an u
3e9b0 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 0a 2a 2a 20 nlock-notify.**
3e9c0 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 74 68 65 20 callback on the
3e9d0 63 6f 6e 63 6c 75 73 69 6f 6e 20 6f 66 20 63 6f conclusion of co
3e9e0 6e 6e 65 63 74 69 6f 6e 20 42 27 73 20 74 72 61 nnection B's tra
3e9f0 6e 73 61 63 74 69 6f 6e 2c 20 61 6e 64 20 63 6f nsaction, and co
3ea00 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 42 20 68 61 nnection.** B ha
3ea10 73 20 69 74 73 65 6c 66 20 72 65 67 69 73 74 65 s itself registe
3ea20 72 65 64 20 66 6f 72 20 61 6e 20 75 6e 6c 6f 63 red for an unloc
3ea30 6b 2d 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 k-notify callbac
3ea40 6b 20 77 68 65 6e 20 63 6f 6e 6e 65 63 74 69 6f k when connectio
3ea50 6e 0a 2a 2a 20 41 27 73 20 74 72 61 6e 73 61 63 n.** A's transac
3ea60 74 69 6f 6e 20 69 73 20 63 6f 6e 63 6c 75 64 65 tion is conclude
3ea70 64 2e 20 49 6e 64 69 72 65 63 74 20 64 65 61 64 d. Indirect dead
3ea80 6c 6f 63 6b 20 69 73 20 61 6c 73 6f 20 64 65 74 lock is also det
3ea90 65 63 74 65 64 2c 20 73 6f 0a 2a 2a 20 74 68 65 ected, so.** the
3eaa0 20 73 79 73 74 65 6d 20 69 73 20 61 6c 73 6f 20 system is also
3eab0 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 considered to be
3eac0 20 64 65 61 64 6c 6f 63 6b 65 64 20 69 66 20 63 deadlocked if c
3ead0 6f 6e 6e 65 63 74 69 6f 6e 20 42 20 68 61 73 0a onnection B has.
3eae0 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 66 6f ** registered fo
3eaf0 72 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 r an unlock-noti
3eb00 66 79 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 74 fy callback on t
3eb10 68 65 20 63 6f 6e 63 6c 75 73 69 6f 6e 20 6f 66 he conclusion of
3eb20 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 connection.** C
3eb30 27 73 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 's transaction,
3eb40 77 68 65 72 65 20 63 6f 6e 6e 65 63 74 69 6f 6e where connection
3eb50 20 43 20 69 73 20 77 61 69 74 69 6e 67 20 6f 6e C is waiting on
3eb60 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 41 2e 20 41 connection A. A
3eb70 6e 79 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 ny.** number of
3eb80 6c 65 76 65 6c 73 20 6f 66 20 69 6e 64 69 72 65 levels of indire
3eb90 63 74 69 6f 6e 20 61 72 65 20 61 6c 6c 6f 77 65 ction are allowe
3eba0 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 d..**.** <b>The
3ebb0 22 44 52 4f 50 20 54 41 42 4c 45 22 20 45 78 63 "DROP TABLE" Exc
3ebc0 65 70 74 69 6f 6e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a eption</b>.**.**
3ebd0 20 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 When a call to
3ebe0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
3ebf0 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f returns SQLITE_
3ec00 4c 4f 43 4b 45 44 2c 20 69 74 20 69 73 20 61 6c LOCKED, it is al
3ec10 6d 6f 73 74 20 0a 2a 2a 20 61 6c 77 61 79 73 20 most .** always
3ec20 61 70 70 72 6f 70 72 69 61 74 65 20 74 6f 20 63 appropriate to c
3ec30 61 6c 6c 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f all sqlite3_unlo
3ec40 63 6b 5f 6e 6f 74 69 66 79 28 29 2e 20 54 68 65 ck_notify(). The
3ec50 72 65 20 69 73 20 68 6f 77 65 76 65 72 2c 0a 2a re is however,.*
3ec60 2a 20 6f 6e 65 20 65 78 63 65 70 74 69 6f 6e 2e * one exception.
3ec70 20 57 68 65 6e 20 65 78 65 63 75 74 69 6e 67 20 When executing
3ec80 61 20 22 44 52 4f 50 20 54 41 42 4c 45 22 20 6f a "DROP TABLE" o
3ec90 72 20 22 44 52 4f 50 20 49 4e 44 45 58 22 20 73 r "DROP INDEX" s
3eca0 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 53 51 4c tatement,.** SQL
3ecb0 69 74 65 20 63 68 65 63 6b 73 20 69 66 20 74 68 ite checks if th
3ecc0 65 72 65 20 61 72 65 20 61 6e 79 20 63 75 72 72 ere are any curr
3ecd0 65 6e 74 6c 79 20 65 78 65 63 75 74 69 6e 67 20 ently executing
3ece0 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 SELECT statement
3ecf0 73 0a 2a 2a 20 74 68 61 74 20 62 65 6c 6f 6e 67 s.** that belong
3ed00 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6e to the same con
3ed10 6e 65 63 74 69 6f 6e 2e 20 49 66 20 74 68 65 72 nection. If ther
3ed20 65 20 61 72 65 2c 20 53 51 4c 49 54 45 5f 4c 4f e are, SQLITE_LO
3ed30 43 4b 45 44 20 69 73 0a 2a 2a 20 72 65 74 75 72 CKED is.** retur
3ed40 6e 65 64 2e 20 49 6e 20 74 68 69 73 20 63 61 73 ned. In this cas
3ed50 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 22 62 e there is no "b
3ed60 6c 6f 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 69 locking connecti
3ed70 6f 6e 22 2c 20 73 6f 20 69 6e 76 6f 6b 69 6e 67 on", so invoking
3ed80 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f .** sqlite3_unlo
3ed90 63 6b 5f 6e 6f 74 69 66 79 28 29 20 72 65 73 75 ck_notify() resu
3eda0 6c 74 73 20 69 6e 20 74 68 65 20 75 6e 6c 6f 63 lts in the unloc
3edb0 6b 2d 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 k-notify callbac
3edc0 6b 20 62 65 69 6e 67 0a 2a 2a 20 69 6e 76 6f 6b k being.** invok
3edd0 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 20 ed immediately.
3ede0 49 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 If the applicati
3edf0 6f 6e 20 74 68 65 6e 20 72 65 2d 61 74 74 65 6d on then re-attem
3ee00 70 74 73 20 74 68 65 20 22 44 52 4f 50 20 54 41 pts the "DROP TA
3ee10 42 4c 45 22 0a 2a 2a 20 6f 72 20 22 44 52 4f 50 BLE".** or "DROP
3ee20 20 49 4e 44 45 58 22 20 71 75 65 72 79 2c 20 61 INDEX" query, a
3ee30 6e 20 69 6e 66 69 6e 69 74 65 20 6c 6f 6f 70 20 n infinite loop
3ee40 6d 69 67 68 74 20 62 65 20 74 68 65 20 72 65 73 might be the res
3ee50 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 77 ult..**.** One w
3ee60 61 79 20 61 72 6f 75 6e 64 20 74 68 69 73 20 70 ay around this p
3ee70 72 6f 62 6c 65 6d 20 69 73 20 74 6f 20 63 68 65 roblem is to che
3ee80 63 6b 20 74 68 65 20 65 78 74 65 6e 64 65 64 20 ck the extended
3ee90 65 72 72 6f 72 20 63 6f 64 65 20 72 65 74 75 72 error code retur
3eea0 6e 65 64 0a 2a 2a 20 62 79 20 61 6e 20 73 71 6c ned.** by an sql
3eeb0 69 74 65 33 5f 73 74 65 70 28 29 20 63 61 6c 6c ite3_step() call
3eec0 2e 20 49 66 20 74 68 65 72 65 20 69 73 20 61 20 . If there is a
3eed0 62 6c 6f 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 blocking connect
3eee0 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a ion, then the.**
3eef0 20 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 extended error
3ef00 63 6f 64 65 20 69 73 20 73 65 74 20 74 6f 20 53 code is set to S
3ef10 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 QLITE_LOCKED_SHA
3ef20 52 45 44 43 41 43 48 45 2e 20 4f 74 68 65 72 77 REDCACHE. Otherw
3ef30 69 73 65 2c 20 69 6e 0a 2a 2a 20 74 68 65 20 73 ise, in.** the s
3ef40 70 65 63 69 61 6c 20 22 44 52 4f 50 20 54 41 42 pecial "DROP TAB
3ef50 4c 45 2f 49 4e 44 45 58 22 20 63 61 73 65 2c 20 LE/INDEX" case,
3ef60 74 68 65 20 65 78 74 65 6e 64 65 64 20 65 72 72 the extended err
3ef70 6f 72 20 63 6f 64 65 20 69 73 20 6a 75 73 74 20 or code is just
3ef80 0a 2a 2a 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 .** SQLITE_LOCKE
3ef90 44 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 D..*/.int sqlite
3efa0 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 3_unlock_notify(
3efb0 0a 20 20 73 71 6c 69 74 65 33 20 2a 70 42 6c 6f . sqlite3 *pBlo
3efc0 63 6b 65 64 2c 20 20 20 20 20 20 20 20 20 20 20 cked,
3efd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
3efe0 2a 20 57 61 69 74 69 6e 67 20 63 6f 6e 6e 65 63 * Waiting connec
3eff0 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 tion */. void (
3f000 2a 78 4e 6f 74 69 66 79 29 28 76 6f 69 64 20 2a *xNotify)(void *
3f010 2a 61 70 41 72 67 2c 20 69 6e 74 20 6e 41 72 67 *apArg, int nArg
3f020 29 2c 20 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 ), /* Callbac
3f030 6b 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e k function to in
3f040 76 6f 6b 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a voke */. void *
3f050 70 4e 6f 74 69 66 79 41 72 67 20 20 20 20 20 20 pNotifyArg
3f060 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3f070 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e /* Argumen
3f080 74 20 74 6f 20 70 61 73 73 20 74 6f 20 78 4e 6f t to pass to xNo
3f090 74 69 66 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a tify */.);../*.*
3f0a0 2a 20 55 6e 64 6f 20 74 68 65 20 68 61 63 6b 20 * Undo the hack
3f0b0 74 68 61 74 20 63 6f 6e 76 65 72 74 73 20 66 6c that converts fl
3f0c0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 74 79 70 oating point typ
3f0d0 65 73 20 74 6f 20 69 6e 74 65 67 65 72 20 66 6f es to integer fo
3f0e0 72 0a 2a 2a 20 62 75 69 6c 64 73 20 6f 6e 20 70 r.** builds on p
3f0f0 72 6f 63 65 73 73 6f 72 73 20 77 69 74 68 6f 75 rocessors withou
3f100 74 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 t floating point
3f110 20 73 75 70 70 6f 72 74 2e 0a 2a 2f 0a 23 69 66 support..*/.#if
3f120 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f def SQLITE_OMIT_
3f130 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 FLOATING_POINT.#
3f140 20 75 6e 64 65 66 20 64 6f 75 62 6c 65 0a 23 65 undef double.#e
3f150 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 5f 5f 63 ndif..#ifdef __c
3f160 70 6c 75 73 70 6c 75 73 0a 7d 20 20 2f 2a 20 45 plusplus.} /* E
3f170 6e 64 20 6f 66 20 74 68 65 20 27 65 78 74 65 72 nd of the 'exter
3f180 6e 20 22 43 22 27 20 62 6c 6f 63 6b 20 2a 2f 0a n "C"' block */.
3f190 23 65 6e 64 69 66 0a 23 65 6e 64 69 66 0a #endif.#endif.