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 34 37 20 32 30 30 39 2f 30 n,v 1.447 2009/0
05f0: 34 2f 33 30 20 31 35 3a 35 39 3a 35 36 20 64 72 4/30 15:59:56 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 0a 23 64 65 66 69 6e 65 20 0000001.#define
4180: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
4190: 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 WRITE 0x0
41a0: 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 0000002.#define
41b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 SQLITE_OPEN_CREA
41c0: 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 TE 0x0
41d0: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 0000004.#define
41e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 SQLITE_OPEN_DELE
41f0: 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 TEONCLOSE 0x0
4200: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 0000008.#define
4210: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c SQLITE_OPEN_EXCL
4220: 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 USIVE 0x0
4230: 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 0000010.#define
4240: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e SQLITE_OPEN_MAIN
4250: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 _DB 0x0
4260: 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 0000100.#define
4270: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 SQLITE_OPEN_TEMP
4280: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 _DB 0x0
4290: 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 0000200.#define
42a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e SQLITE_OPEN_TRAN
42b0: 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 SIENT_DB 0x0
42c0: 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 0000400.#define
42d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e SQLITE_OPEN_MAIN
42e0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 _JOURNAL 0x0
42f0: 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 0000800.#define
4300: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 SQLITE_OPEN_TEMP
4310: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 _JOURNAL 0x0
4320: 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 0001000.#define
4330: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a SQLITE_OPEN_SUBJ
4340: 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 OURNAL 0x0
4350: 30 30 30 32 30 30 30 0a 23 64 65 66 69 6e 65 20 0002000.#define
4360: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 SQLITE_OPEN_MAST
4370: 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 ER_JOURNAL 0x0
4380: 30 30 30 34 30 30 30 0a 23 64 65 66 69 6e 65 20 0004000.#define
4390: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 SQLITE_OPEN_NOMU
43a0: 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 TEX 0x0
43b0: 30 30 30 38 30 30 30 0a 23 64 65 66 69 6e 65 20 0008000.#define
43c0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c SQLITE_OPEN_FULL
43d0: 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 MUTEX 0x0
43e0: 30 30 31 30 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 0010000../*.** C
43f0: 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 API3REF: Device
4400: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 Characteristics
4410: 7b 48 31 30 32 34 30 7d 20 3c 48 31 31 31 32 30 {H10240} <H11120
4420: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 >.**.** The xDev
4430: 69 63 65 43 61 70 61 62 69 6c 69 74 69 65 73 20 iceCapabilities
4440: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 method of the [s
4450: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
4460: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 s].** object ret
4470: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 urns an integer
4480: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f which is a vecto
4490: 72 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a r of the these.*
44a0: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 * bit values exp
44b0: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 ressing I/O char
44c0: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 acteristics of t
44d0: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a he mass storage.
44e0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 ** device that h
44f0: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 olds the file th
4500: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f at the [sqlite3_
4510: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 io_methods].** r
4520: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 efers to..**.**
4530: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
4540: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 _ATOMIC property
4550: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 means that all
4560: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 writes of.** any
4570: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 size are atomic
4580: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
4590: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 CAP_ATOMICnnn va
45a0: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 lues.** mean tha
45b0: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 t writes of bloc
45c0: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 ks that are nnn
45d0: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e bytes in size an
45e0: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 d.** are aligned
45f0: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 to an address w
4600: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 hich is an integ
4610: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a er multiple of.*
4620: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 * nnn are atomic
4630: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
4640: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 CAP_SAFE_APPEND
4650: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 value means.** t
4660: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 hat when data is
4670: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 appended to a f
4680: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 ile, the data is
4690: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 appended.** fir
46a0: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 st then the size
46b0: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 of the file is
46c0: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 extended, never
46d0: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 the other.** way
46e0: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 around. The SQ
46f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 LITE_IOCAP_SEQUE
4700: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d NTIAL property m
4710: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 eans that.** inf
4720: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 ormation is writ
4730: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 ten to disk in t
4740: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 he same order as
4750: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 calls.** to xWr
4760: 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e ite()..*/.#defin
4770: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
4780: 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 30 TOMIC 0
4790: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e x00000001.#defin
47a0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
47b0: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 30 TOMIC512 0
47c0: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e x00000002.#defin
47d0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
47e0: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 30 TOMIC1K 0
47f0: 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e x00000004.#defin
4800: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
4810: 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 30 TOMIC2K 0
4820: 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e x00000008.#defin
4830: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
4840: 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 30 TOMIC4K 0
4850: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e x00000010.#defin
4860: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
4870: 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 30 TOMIC8K 0
4880: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e x00000020.#defin
4890: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
48a0: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 30 TOMIC16K 0
48b0: 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e x00000040.#defin
48c0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
48d0: 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 30 TOMIC32K 0
48e0: 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e x00000080.#defin
48f0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
4900: 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 30 TOMIC64K 0
4910: 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e x00000100.#defin
4920: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 e SQLITE_IOCAP_S
4930: 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 30 AFE_APPEND 0
4940: 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e x00000200.#defin
4950: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 e SQLITE_IOCAP_S
4960: 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 30 EQUENTIAL 0
4970: 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a x00000400../*.**
4980: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 CAPI3REF: File
4990: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b Locking Levels {
49a0: 48 31 30 32 35 30 7d 20 3c 48 31 31 31 32 30 3e H10250} <H11120>
49b0: 20 3c 48 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a 20 <H11310>.**.**
49c0: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 SQLite uses one
49d0: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 of these integer
49e0: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 values as the s
49f0: 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e econd.** argumen
4a00: 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 t to calls it ma
4a10: 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b kes to the xLock
4a20: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 () and xUnlock()
4a30: 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 methods.** of a
4a40: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 n [sqlite3_io_me
4a50: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a thods] object..*
4a60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4a70: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 _LOCK_NONE
4a80: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 0.#define SQ
4a90: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 LITE_LOCK_SHARED
4aa0: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 1.#defin
4ab0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 e SQLITE_LOCK_RE
4ac0: 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 SERVED 2.#d
4ad0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 efine SQLITE_LOC
4ae0: 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 K_PENDING
4af0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 3.#define SQLITE
4b00: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 _LOCK_EXCLUSIVE
4b10: 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 4../*.** CAP
4b20: 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 I3REF: Synchroni
4b30: 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 zation Type Flag
4b40: 73 20 7b 48 31 30 32 36 30 7d 20 3c 48 31 31 31 s {H10260} <H111
4b50: 32 30 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 20>.**.** When S
4b60: 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 QLite invokes th
4b70: 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 e xSync() method
4b80: 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 of an.** [sqlit
4b90: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f e3_io_methods] o
4ba0: 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20 bject it uses a
4bb0: 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a combination of.*
4bc0: 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 * these integer
4bd0: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 values as the se
4be0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a cond argument..*
4bf0: 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 *.** When the SQ
4c00: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e LITE_SYNC_DATAON
4c10: 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c LY flag is used,
4c20: 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 it means that t
4c30: 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 he.** sync opera
4c40: 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 tion only needs
4c50: 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f to flush data to
4c60: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 mass storage.
4c70: 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 Inode.** informa
4c80: 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 tion need not be
4c90: 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 flushed. If the
4ca0: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 lower four bits
4cb0: 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 of the flag.**
4cc0: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e equal SQLITE_SYN
4cd0: 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d C_NORMAL, that m
4ce0: 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d eans to use norm
4cf0: 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e al fsync() seman
4d00: 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 tics..** If the
4d10: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 lower four bits
4d20: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e equal SQLITE_SYN
4d30: 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 C_FULL, that mea
4d40: 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 ns.** to use Mac
4d50: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c OS X style full
4d60: 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 sync instead of
4d70: 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 66 fsync()..*/.#def
4d80: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f ine SQLITE_SYNC_
4d90: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 NORMAL 0x
4da0: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 00002.#define SQ
4db0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 LITE_SYNC_FULL
4dc0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 0x00003.
4dd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
4de0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 YNC_DATAONLY
4df0: 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 0x00010../*.**
4e00: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e CAPI3REF: OS In
4e10: 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c terface Open Fil
4e20: 65 20 48 61 6e 64 6c 65 20 7b 48 31 31 31 31 30 e Handle {H11110
4e30: 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a } <S20110>.**.**
4e40: 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c An [sqlite3_fil
4e50: 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 e] object repres
4e60: 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c ents an open fil
4e70: 65 20 69 6e 20 74 68 65 20 4f 53 0a 2a 2a 20 69 e in the OS.** i
4e80: 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 2e 20 nterface layer.
4e90: 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 Individual OS i
4ea0: 6e 74 65 72 66 61 63 65 20 69 6d 70 6c 65 6d 65 nterface impleme
4eb0: 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a ntations will.**
4ec0: 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 want to subclas
4ed0: 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 s this object by
4ee0: 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 appending addit
4ef0: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 ional fields.**
4f00: 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 for their own us
4f10: 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 e. The pMethods
4f20: 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e entry is a poin
4f30: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 ter to an.** [sq
4f40: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
4f50: 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 ] object that de
4f60: 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f fines methods fo
4f70: 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 r performing.**
4f80: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f I/O operations o
4f90: 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e n the open file.
4fa0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
4fb0: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 ct sqlite3_file
4fc0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 sqlite3_file;.st
4fd0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c ruct sqlite3_fil
4fe0: 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 e {. const stru
4ff0: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 ct sqlite3_io_me
5000: 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b thods *pMethods;
5010: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 /* Methods for
5020: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f an open file */
5030: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .};../*.** CAPI3
5040: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 REF: OS Interfac
5050: 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d e File Virtual M
5060: 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 20 7b 48 ethods Object {H
5070: 31 31 31 32 30 7d 20 3c 53 32 30 31 31 30 3e 0a 11120} <S20110>.
5080: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 **.** Every file
5090: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b opened by the [
50a0: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 sqlite3_vfs] xOp
50b0: 65 6e 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 en method popula
50c0: 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 tes an.** [sqlit
50d0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 e3_file] object
50e0: 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e (or, more common
50f0: 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f ly, a subclass o
5100: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 f the.** [sqlite
5110: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 3_file] object)
5120: 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 with a pointer t
5130: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 o an instance of
5140: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a this object..**
5150: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 This object def
5160: 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 ines the methods
5170: 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d used to perform
5180: 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 various operati
5190: 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 ons.** against t
51a0: 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 he open file rep
51b0: 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 resented by the
51c0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f [sqlite3_file] o
51d0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 bject..**.** The
51e0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 flags argument
51f0: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 to xSync may be
5200: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 one of [SQLITE_S
5210: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a YNC_NORMAL] or.*
5220: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 * [SQLITE_SYNC_F
5230: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 ULL]. The first
5240: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e choice is the n
5250: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a ormal fsync()..*
5260: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f * The second cho
5270: 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 ice is a Mac OS
5280: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 X style fullsync
5290: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 . The [SQLITE_S
52a0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a YNC_DATAONLY].**
52b0: 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 flag may be ORe
52c0: 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 d in to indicate
52d0: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 that only the d
52e0: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a ata of the file.
52f0: 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 ** and not its i
5300: 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 node needs to be
5310: 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 synced..**.** T
5320: 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 he integer value
5330: 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 s to xLock() and
5340: 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f xUnlock() are o
5350: 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a ne of.** <ul>.**
5360: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f <li> [SQLITE_LO
5370: 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 CK_NONE],.** <li
5380: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 > [SQLITE_LOCK_S
5390: 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 HARED],.** <li>
53a0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 [SQLITE_LOCK_RES
53b0: 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 ERVED],.** <li>
53c0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e [SQLITE_LOCK_PEN
53d0: 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 DING], or.** <li
53e0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 > [SQLITE_LOCK_E
53f0: 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f XCLUSIVE]..** </
5400: 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 ul>.** xLock() i
5410: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 ncreases the loc
5420: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 k. xUnlock() dec
5430: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e reases the lock.
5440: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 .** The xCheckRe
5450: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 servedLock() met
5460: 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 hod checks wheth
5470: 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 er any database
5480: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 connection,.** e
5490: 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 ither in this pr
54a0: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 ocess or in some
54b0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 other process,
54c0: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 is holding a RES
54d0: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e ERVED,.** PENDIN
54e0: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 G, or EXCLUSIVE
54f0: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 lock on the file
5500: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 . It returns tr
5510: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 ue.** if such a
5520: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 lock exists and
5530: 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e false otherwise.
5540: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 .**.** The xFile
5550: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 Control() method
5560: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e is a generic in
5570: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c terface that all
5580: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 ows custom.** VF
5590: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e S implementation
55a0: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f s to directly co
55b0: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 ntrol an open fi
55c0: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 le using the.**
55d0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
55e0: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 ntrol()] interfa
55f0: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 ce. The second
5600: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 "op" argument is
5610: 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f an.** integer o
5620: 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 pcode. The thir
5630: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 d argument is a
5640: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 generic pointer
5650: 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 intended to.** p
5660: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 oint to a struct
5670: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e ure that may con
5680: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f tain arguments o
5690: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 r space in which
56a0: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 to.** write ret
56b0: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 urn values. Pot
56c0: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 ential uses for
56d0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d xFileControl() m
56e0: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 ight be.** funct
56f0: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 ions to enable b
5700: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 locking locks wi
5710: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 th timeouts, to
5720: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f change the.** lo
5730: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 cking strategy (
5740: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 for example to u
5750: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b se dot-file lock
5760: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a s), to inquire.*
5770: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 * about the stat
5780: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 us of a lock, or
5790: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 to break stale
57a0: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 locks. The SQLi
57b0: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 te.** core reser
57c0: 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 ves all opcodes
57d0: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f less than 100 fo
57e0: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a r its own use..*
57f0: 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 * A [SQLITE_FCNT
5800: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 L_LOCKSTATE | li
5810: 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c st of opcodes] l
5820: 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 ess than 100 is
5830: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 available..** Ap
5840: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 plications that
5850: 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 define a custom
5860: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 xFileControl met
5870: 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f hod should use o
5880: 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 pcodes.** greate
5890: 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 r than 100 to av
58a0: 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a oid conflicts..*
58b0: 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 *.** The xSector
58c0: 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 Size() method re
58d0: 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 turns the sector
58e0: 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 size of the.**
58f0: 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 device that unde
5900: 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 rlies the file.
5910: 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 The sector size
5920: 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d is the.** minim
5930: 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 um write that ca
5940: 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 n be performed w
5950: 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e ithout disturbin
5960: 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 g.** other bytes
5970: 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 in the file. T
5980: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 he xDeviceCharac
5990: 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d teristics().** m
59a0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 ethod returns a
59b0: 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 bit vector descr
59c0: 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 ibing behaviors
59d0: 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c of the.** underl
59e0: 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a ying device:.**.
59f0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
5a00: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
5a10: 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 OMIC].** <li> [S
5a20: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
5a30: 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b IC512].** <li> [
5a40: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
5a50: 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b MIC1K].** <li> [
5a60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
5a70: 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b MIC2K].** <li> [
5a80: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
5a90: 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b MIC4K].** <li> [
5aa0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
5ab0: 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b MIC8K].** <li> [
5ac0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
5ad0: 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 MIC16K].** <li>
5ae0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
5af0: 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e OMIC32K].** <li>
5b00: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
5b10: 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 TOMIC64K].** <li
5b20: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
5b30: 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 SAFE_APPEND].**
5b40: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
5b50: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a AP_SEQUENTIAL].*
5b60: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 * </ul>.**.** Th
5b70: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
5b80: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d TOMIC property m
5b90: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 eans that all wr
5ba0: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 ites of.** any s
5bb0: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 ize are atomic.
5bc0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
5bd0: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 P_ATOMICnnn valu
5be0: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 es.** mean that
5bf0: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 writes of blocks
5c00: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 that are nnn by
5c10: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a tes in size and.
5c20: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 ** are aligned t
5c30: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 o an address whi
5c40: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 ch is an integer
5c50: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 multiple of.**
5c60: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 nnn are atomic.
5c70: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
5c80: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 P_SAFE_APPEND va
5c90: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 lue means.** tha
5ca0: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 t when data is a
5cb0: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c ppended to a fil
5cc0: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 e, the data is a
5cd0: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 ppended.** first
5ce0: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f then the size o
5cf0: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 f the file is ex
5d00: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 tended, never th
5d10: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 e other.** way a
5d20: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 round. The SQLI
5d30: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 TE_IOCAP_SEQUENT
5d40: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 IAL property mea
5d50: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 ns that.** infor
5d60: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 mation is writte
5d70: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 n to disk in the
5d80: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 same order as c
5d90: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 alls.** to xWrit
5da0: 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 e()..**.** If xR
5db0: 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 ead() returns SQ
5dc0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 LITE_IOERR_SHORT
5dd0: 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c _READ it must al
5de0: 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 so fill.** in th
5df0: 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e e unread portion
5e00: 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 s of the buffer
5e10: 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 with zeros. A V
5e20: 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 FS that.** fails
5e30: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 to zero-fill sh
5e40: 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 ort reads might
5e50: 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 seem to work. H
5e60: 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 owever,.** failu
5e70: 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 re to zero-fill
5e80: 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c short reads will
5e90: 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 eventually lead
5ea0: 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 to.** database
5eb0: 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 corruption..*/.t
5ec0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
5ed0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
5ee0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 sqlite3_io_meth
5ef0: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 ods;.struct sqli
5f00: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b te3_io_methods {
5f10: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b . int iVersion;
5f20: 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 . int (*xClose)
5f30: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b (sqlite3_file*);
5f40: 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 . int (*xRead)(
5f50: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 sqlite3_file*, v
5f60: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 oid*, int iAmt,
5f70: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f sqlite3_int64 iO
5f80: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 fst);. int (*xW
5f90: 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 rite)(sqlite3_fi
5fa0: 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a le*, const void*
5fb0: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 , int iAmt, sqli
5fc0: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 te3_int64 iOfst)
5fd0: 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 ;. int (*xTrunc
5fe0: 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ate)(sqlite3_fil
5ff0: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 e*, sqlite3_int6
6000: 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 4 size);. int (
6010: 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f *xSync)(sqlite3_
6020: 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 file*, int flags
6030: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 );. int (*xFile
6040: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 Size)(sqlite3_fi
6050: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 le*, sqlite3_int
6060: 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 64 *pSize);. in
6070: 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 t (*xLock)(sqlit
6080: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a e3_file*, int);.
6090: 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 int (*xUnlock)
60a0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
60b0: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 int);. int (*xC
60c0: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b heckReservedLock
60d0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
60e0: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a int *pResOut);.
60f0: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e int (*xFileCon
6100: 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 trol)(sqlite3_fi
6110: 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 le*, int op, voi
6120: 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 d *pArg);. int
6130: 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 (*xSectorSize)(s
6140: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 qlite3_file*);.
6150: 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 int (*xDeviceCh
6160: 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 aracteristics)(s
6170: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 qlite3_file*);.
6180: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d /* Additional m
6190: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 ethods may be ad
61a0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
61b0: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a leases */.};../*
61c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 .** CAPI3REF: St
61d0: 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 andard File Cont
61e0: 72 6f 6c 20 4f 70 63 6f 64 65 73 20 7b 48 31 31 rol Opcodes {H11
61f0: 33 31 30 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 310} <S30800>.**
6200: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 .** These intege
6210: 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 r constants are
6220: 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 opcodes for the
6230: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 xFileControl met
6240: 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 hod.** of the [s
6250: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
6260: 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f s] object and fo
6270: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 r the [sqlite3_f
6280: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a ile_control()].*
6290: 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a * interface..**.
62a0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ** The [SQLITE_F
62b0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 CNTL_LOCKSTATE]
62c0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 opcode is used f
62d0: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 or debugging. T
62e0: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 his.** opcode ca
62f0: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f uses the xFileCo
6300: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 ntrol method to
6310: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e write the curren
6320: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 t state of.** th
6330: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b e lock (one of [
6340: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 SQLITE_LOCK_NONE
6350: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f ], [SQLITE_LOCK_
6360: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c SHARED],.** [SQL
6370: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 ITE_LOCK_RESERVE
6380: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b D], [SQLITE_LOCK
6390: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 _PENDING], or [S
63a0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 QLITE_LOCK_EXCLU
63b0: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 SIVE]).** into a
63c0: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 n integer that t
63d0: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 he pArg argument
63e0: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 points to. This
63f0: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 capability.** i
6400: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 s used during te
6410: 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e sting and only n
6420: 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f eeds to be suppo
6430: 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 rted when SQLITE
6440: 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 _TEST.** is defi
6450: 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ned..*/.#define
6460: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 SQLITE_FCNTL_LOC
6470: 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 31 0a KSTATE 1.
6480: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 #define SQLITE_G
6490: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 ET_LOCKPROXYFILE
64a0: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 2.#define
64b0: 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 SQLITE_SET_LOCKP
64c0: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 33 0a ROXYFILE 3.
64d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
64e0: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 AST_ERRNO
64f0: 20 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 4../*.** C
6500: 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 API3REF: Mutex H
6510: 61 6e 64 6c 65 20 7b 48 31 37 31 31 30 7d 20 3c andle {H17110} <
6520: 53 32 30 31 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S20130>.**.** Th
6530: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 e mutex module w
6540: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 ithin SQLite def
6550: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 ines [sqlite3_mu
6560: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a tex] to be an.**
6570: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 abstract type f
6580: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 or a mutex objec
6590: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 t. The SQLite c
65a0: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a ore never looks.
65b0: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e ** at the intern
65c0: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f al representatio
65d0: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 n of an [sqlite3
65e0: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c _mutex]. It onl
65f0: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 y.** deals with
6600: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 pointers to the
6610: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 [sqlite3_mutex]
6620: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 object..**.** Mu
6630: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 texes are create
6640: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
6650: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e _mutex_alloc()].
6660: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
6670: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 ct sqlite3_mutex
6680: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a sqlite3_mutex;.
6690: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
66a0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 OS Interface Ob
66b0: 6a 65 63 74 20 7b 48 31 31 31 34 30 7d 20 3c 53 ject {H11140} <S
66c0: 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 20100>.**.** An
66d0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 instance of the
66e0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 sqlite3_vfs obje
66f0: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 ct defines the i
6700: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e nterface between
6710: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 .** the SQLite c
6720: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 ore and the unde
6730: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 rlying operating
6740: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 system. The "v
6750: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 fs".** in the na
6760: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 me of the object
6770: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 stands for "vir
6780: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d tual file system
6790: 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c "..**.** The val
67a0: 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 ue of the iVersi
67b0: 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 on field is init
67c0: 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 ially 1 but may
67d0: 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 be larger in.**
67e0: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 future versions
67f0: 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 of SQLite. Addi
6800: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 tional fields ma
6810: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f y be appended to
6820: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 this.** object
6830: 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f when the iVersio
6840: 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 n value is incre
6850: 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 ased. Note that
6860: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a the structure.*
6870: 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 * of the sqlite3
6880: 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e _vfs object chan
6890: 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 ges in the trans
68a0: 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a action between.*
68b0: 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e * SQLite version
68c0: 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 3.5.9 and 3.6.0
68d0: 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 and yet the iVe
68e0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 rsion field was
68f0: 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e not.** modified.
6900: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 .**.** The szOsF
6910: 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 ile field is the
6920: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 size of the sub
6930: 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 classed [sqlite3
6940: 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 _file].** struct
6950: 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 ure used by this
6960: 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d VFS. mxPathnam
6970: 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d e is the maximum
6980: 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 length of.** a
6990: 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 pathname in this
69a0: 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 VFS..**.** Regi
69b0: 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 stered sqlite3_v
69c0: 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b fs objects are k
69d0: 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 ept on a linked
69e0: 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a list formed by.*
69f0: 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e * the pNext poin
6a00: 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 ter. The [sqlit
6a10: 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 e3_vfs_register(
6a20: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 )].** and [sqlit
6a30: 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 e3_vfs_unregiste
6a40: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 r()] interfaces
6a50: 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 manage this list
6a60: 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d .** in a thread-
6a70: 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b safe way. The [
6a80: 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 sqlite3_vfs_find
6a90: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a ()] interface.**
6aa0: 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 searches the li
6ab0: 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 st. Neither the
6ac0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 application cod
6ad0: 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a e nor the VFS.**
6ae0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
6af0: 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 should use the p
6b00: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a Next pointer..**
6b10: 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 .** The pNext fi
6b20: 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 eld is the only
6b30: 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c field in the sql
6b40: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 ite3_vfs.** stru
6b50: 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 cture that SQLit
6b60: 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 e will ever modi
6b70: 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c fy. SQLite will
6b80: 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 only access.**
6b90: 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 or modify this f
6ba0: 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 ield while holdi
6bb0: 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 ng a particular
6bc0: 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a static mutex..**
6bd0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
6be0: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f should never mo
6bf0: 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 dify anything wi
6c00: 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 thin the sqlite3
6c10: 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f _vfs.** object o
6c20: 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 nce the object h
6c30: 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 as been register
6c40: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e ed..**.** The zN
6c50: 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 ame field holds
6c60: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
6c70: 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 VFS module. The
6c80: 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 name must.** be
6c90: 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 unique across a
6ca0: 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a ll VFS modules..
6cb0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c **.** SQLite wil
6cc0: 6c 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 l guarantee that
6cd0: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 the zFilename p
6ce0: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 arameter to xOpe
6cf0: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 n.** is either a
6d00: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 NULL pointer or
6d10: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 string obtained
6d20: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 .** from xFullPa
6d30: 74 68 6e 61 6d 65 28 29 2e 20 20 53 51 4c 69 74 thname(). SQLit
6d40: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e e further guaran
6d50: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 tees that.** the
6d60: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 string will be
6d70: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e valid and unchan
6d80: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 ged until xClose
6d90: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e () is.** called.
6da0: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 Because of the
6db0: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 73 previous sentens
6dc0: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 e,.** the [sqlit
6dd0: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 e3_file] can saf
6de0: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e ely store a poin
6df0: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 ter to the.** fi
6e00: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 lename if it nee
6e10: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 ds to remember t
6e20: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 he filename for
6e30: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 some reason..**
6e40: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 If the zFilename
6e50: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 78 4f parameter is xO
6e60: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f pen is a NULL po
6e70: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e inter then xOpen
6e80: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 69 74 65 20 .** must invite
6e90: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 its own temporar
6ea0: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 y name for the f
6eb0: 69 6c 65 2e 20 20 57 68 65 6e 65 76 65 72 20 74 ile. Whenever t
6ec0: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 he .** xFilename
6ed0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 parameter is NU
6ee0: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 LL it will also
6ef0: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 be the case that
6f00: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 the.** flags pa
6f10: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 rameter will inc
6f20: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 lude [SQLITE_OPE
6f30: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d N_DELETEONCLOSE]
6f40: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 ..**.** The flag
6f50: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f s argument to xO
6f60: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 pen() includes a
6f70: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a ll bits set in.*
6f80: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 * the flags argu
6f90: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 ment to [sqlite3
6fa0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 _open_v2()]. Or
6fb0: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 if [sqlite3_ope
6fc0: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 n()].** or [sqli
6fd0: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 te3_open16()] is
6fe0: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 used, then flag
6ff0: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 s includes at le
7000: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f ast.** [SQLITE_O
7010: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c PEN_READWRITE] |
7020: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 [SQLITE_OPEN_CR
7030: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f EATE]. .** If xO
7040: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 pen() opens a fi
7050: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 le read-only the
7060: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 n it sets *pOutF
7070: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 lags to.** inclu
7080: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f de [SQLITE_OPEN_
7090: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 READONLY]. Othe
70a0: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 r bits in *pOutF
70b0: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e lags may be set.
70c0: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 .**.** SQLite wi
70d0: 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 ll also add one
70e0: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 of the following
70f0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f flags to the xO
7100: 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 pen().** call, d
7110: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 epending on the
7120: 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 object being ope
7130: 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a ned:.**.** <ul>.
7140: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
7150: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a _OPEN_MAIN_DB].*
7160: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
7170: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 OPEN_MAIN_JOURNA
7180: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c L].** <li> [SQL
7190: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 ITE_OPEN_TEMP_DB
71a0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 ].** <li> [SQLI
71b0: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 TE_OPEN_TEMP_JOU
71c0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b RNAL].** <li> [
71d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e SQLITE_OPEN_TRAN
71e0: 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 SIENT_DB].** <li
71f0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
7200: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c SUBJOURNAL].** <
7210: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
7220: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c N_MASTER_JOURNAL
7230: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a ].** </ul>.**.**
7240: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d The file I/O im
7250: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e plementation can
7260: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 use the object
7270: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a type flags to.**
7280: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 change the way
7290: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 it deals with fi
72a0: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c les. For exampl
72b0: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f e, an applicatio
72c0: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e n.** that does n
72d0: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 ot care about cr
72e0: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 ash recovery or
72f0: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d rollback might m
7300: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 ake.** the open
7310: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c of a journal fil
7320: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 e a no-op. Writ
7330: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e es to this journ
7340: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f al would.** also
7350: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 be no-ops, and
7360: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 any attempt to r
7370: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 ead the journal
7380: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 would return.**
7390: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f SQLITE_IOERR. O
73a0: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 r the implementa
73b0: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 tion might recog
73c0: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 nize that a data
73d0: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c base.** file wil
73e0: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d l be doing page-
73f0: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 aligned sector r
7400: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 eads and writes
7410: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f in a random.** o
7420: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 rder and set up
7430: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 its I/O subsyste
7440: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a m accordingly..*
7450: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 *.** SQLite migh
7460: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f t also add one o
7470: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 f the following
7480: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 flags to the xOp
7490: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a en method:.**.**
74a0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 <ul>.** <li> [S
74b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 QLITE_OPEN_DELET
74c0: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 EONCLOSE].** <li
74d0: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 > [SQLITE_OPEN_E
74e0: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 XCLUSIVE].** </u
74f0: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 l>.**.** The [SQ
7500: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 LITE_OPEN_DELETE
7510: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 ONCLOSE] flag me
7520: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f ans the file sho
7530: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 uld be.** delete
7540: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f d when it is clo
7550: 73 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 sed. The [SQLIT
7560: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 E_OPEN_DELETEONC
7570: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 LOSE].** will be
7580: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 20 64 set for TEMP d
7590: 61 74 61 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 atabases, journa
75a0: 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f ls and for subjo
75b0: 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 urnals..**.** Th
75c0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 e [SQLITE_OPEN_E
75d0: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 6d XCLUSIVE] flag m
75e0: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 eans the file sh
75f0: 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 0a 2a ould be opened.*
7600: 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 * for exclusive
7610: 61 63 63 65 73 73 2e 20 20 54 68 69 73 20 66 6c access. This fl
7620: 61 67 20 69 73 20 73 65 74 20 66 6f 72 20 61 6c ag is set for al
7630: 6c 20 66 69 6c 65 73 20 65 78 63 65 70 74 0a 2a l files except.*
7640: 2a 20 66 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 * for the main d
7650: 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a atabase file..**
7660: 0a 2a 2a 20 41 74 20 6c 65 61 73 74 20 73 7a 4f .** At least szO
7670: 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d sFile bytes of m
7680: 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 emory are alloca
7690: 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a ted by SQLite.**
76a0: 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 to hold the [s
76b0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 qlite3_file] str
76c0: 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 ucture passed as
76d0: 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 the third.** ar
76e0: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e gument to xOpen.
76f0: 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 The xOpen meth
7700: 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 od does not have
7710: 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 to.** allocate
7720: 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 the structure; i
7730: 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 t should just fi
7740: 6c 6c 20 69 74 20 69 6e 2e 0a 2a 2a 0a 2a 2a 20 ll it in..**.**
7750: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 The flags argume
7760: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 nt to xAccess()
7770: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 may be [SQLITE_A
7780: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a CCESS_EXISTS].**
7790: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 to test for the
77a0: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 existence of a
77b0: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 file, or [SQLITE
77c0: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 _ACCESS_READWRIT
77d0: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 E] to.** test wh
77e0: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 ether a file is
77f0: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 readable and wri
7800: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 table, or [SQLIT
7810: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a E_ACCESS_READ].*
7820: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 * to test whethe
7830: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c r a file is at l
7840: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 east readable.
7850: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 The file can be
7860: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e a.** directory.
7870: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 .**.** SQLite wi
7880: 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 ll always alloca
7890: 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 te at least mxPa
78a0: 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 thname+1 bytes f
78b0: 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 or the.** output
78c0: 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 buffer xFullPat
78d0: 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 hname. The exac
78e0: 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 t size of the ou
78f0: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 tput buffer.** i
7900: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 s also passed as
7910: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 a parameter to
7920: 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 both methods. I
7930: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 f the output buf
7940: 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 fer.** is not la
7950: 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c rge enough, [SQL
7960: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 ITE_CANTOPEN] sh
7970: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 ould be returned
7980: 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a . Since this is.
7990: 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 ** handled as a
79a0: 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 fatal error by S
79b0: 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 QLite, vfs imple
79c0: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c mentations shoul
79d0: 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f d endeavor.** to
79e0: 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 prevent this by
79f0: 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e setting mxPathn
7a00: 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 ame to a suffici
7a10: 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 ently large valu
7a20: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 e..**.** The xRa
7a30: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 ndomness(), xSle
7a40: 65 70 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 ep(), and xCurre
7a50: 6e 74 54 69 6d 65 28 29 20 69 6e 74 65 72 66 61 ntTime() interfa
7a60: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73 ces.** are not s
7a70: 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f trictly a part o
7a80: 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d f the filesystem
7a90: 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a , but they are.*
7aa0: 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 * included in th
7ab0: 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 e VFS structure
7ac0: 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 for completeness
7ad0: 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d ..** The xRandom
7ae0: 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 ness() function
7af0: 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 attempts to retu
7b00: 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a rn nBytes bytes.
7b10: 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 ** of good-quali
7b20: 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e ty randomness in
7b30: 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 to zOut. The re
7b40: 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a turn value is.**
7b50: 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 the actual numb
7b60: 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 er of bytes of r
7b70: 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e andomness obtain
7b80: 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 ed..** The xSlee
7b90: 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 p() method cause
7ba0: 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 s the calling th
7bb0: 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f read to sleep fo
7bc0: 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 r at.** least th
7bd0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 e number of micr
7be0: 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 oseconds given.
7bf0: 20 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d The xCurrentTim
7c00: 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 e().** method re
7c10: 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 turns a Julian D
7c20: 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 ay Number for th
7c30: 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 e current date a
7c40: 6e 64 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2f 0a 74 nd time..**.*/.t
7c50: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
7c60: 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 lite3_vfs sqlite
7c70: 33 5f 76 66 73 3b 0a 73 74 72 75 63 74 20 73 71 3_vfs;.struct sq
7c80: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e lite3_vfs {. in
7c90: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 t iVersion;
7ca0: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 /* Struct
7cb0: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 ure version numb
7cc0: 65 72 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 er */. int szOs
7cd0: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 File;
7ce0: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 /* Size of subc
7cf0: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 lassed sqlite3_f
7d00: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 ile */. int mxP
7d10: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 athname;
7d20: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c /* Maximum fil
7d30: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 e pathname lengt
7d40: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 h */. sqlite3_v
7d50: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 fs *pNext;
7d60: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 /* Next register
7d70: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 ed VFS */. cons
7d80: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 t char *zName;
7d90: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 /* Name of
7da0: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c this virtual fil
7db0: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f e system */. vo
7dc0: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 id *pAppData;
7dd0: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 /* Pointe
7de0: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e r to application
7df0: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a -specific data *
7e00: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 /. int (*xOpen)
7e10: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
7e20: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
7e30: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c , sqlite3_file*,
7e40: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 .
7e50: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a int flags, int *
7e60: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e pOutFlags);. in
7e70: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c t (*xDelete)(sql
7e80: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
7e90: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e char *zName, in
7ea0: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e t syncDir);. in
7eb0: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c t (*xAccess)(sql
7ec0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
7ed0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e char *zName, in
7ee0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 t flags, int *pR
7ef0: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a esOut);. int (*
7f00: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 xFullPathname)(s
7f10: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
7f20: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
7f30: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a int nOut, char *
7f40: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 zOut);. void *(
7f50: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 *xDlOpen)(sqlite
7f60: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
7f70: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a ar *zFilename);.
7f80: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f void (*xDlErro
7f90: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c r)(sqlite3_vfs*,
7fa0: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 int nByte, char
7fb0: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f *zErrMsg);. vo
7fc0: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 id (*(*xDlSym)(s
7fd0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 qlite3_vfs*,void
7fe0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
7ff0: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a Symbol))(void);.
8000: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 void (*xDlClos
8010: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c e)(sqlite3_vfs*,
8020: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 void*);. int (
8030: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 *xRandomness)(sq
8040: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 lite3_vfs*, int
8050: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 nByte, char *zOu
8060: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 t);. int (*xSle
8070: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ep)(sqlite3_vfs*
8080: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e , int microsecon
8090: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 ds);. int (*xCu
80a0: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 rrentTime)(sqlit
80b0: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a e3_vfs*, double*
80c0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c );. int (*xGetL
80d0: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 astError)(sqlite
80e0: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 3_vfs*, int, cha
80f0: 72 20 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 r *);. /* New f
8100: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 ields may be app
8110: 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 ended in figure
8120: 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 versions. The i
8130: 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c Version. ** val
8140: 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e ue will incremen
8150: 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 t whenever this
8160: 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a happens. */.};..
8170: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
8180: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 Flags for the xA
8190: 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 ccess VFS method
81a0: 20 7b 48 31 31 31 39 30 7d 20 3c 48 31 31 31 34 {H11190} <H1114
81b0: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 0>.**.** These i
81c0: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 nteger constants
81d0: 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 can be used as
81e0: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
81f0: 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 ter to.** the xA
8200: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 ccess method of
8210: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d an [sqlite3_vfs]
8220: 20 6f 62 6a 65 63 74 2e 20 7b 45 4e 44 7d 20 20 object. {END}
8230: 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a They determine.*
8240: 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 * what kind of p
8250: 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 ermissions the x
8260: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 Access method is
8270: 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a looking for..**
8280: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 With SQLITE_ACC
8290: 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 ESS_EXISTS, the
82a0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a xAccess method.*
82b0: 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 * simply checks
82c0: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 whether the file
82d0: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 exists..** With
82e0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 SQLITE_ACCESS_R
82f0: 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 EADWRITE, the xA
8300: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 ccess method.**
8310: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 checks whether t
8320: 68 65 20 66 69 6c 65 20 69 73 20 62 6f 74 68 20 he file is both
8330: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 readable and wri
8340: 74 61 62 6c 65 2e 0a 2a 2a 20 57 69 74 68 20 53 table..** With S
8350: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
8360: 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d D, the xAccess m
8370: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 ethod.** checks
8380: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 whether the file
8390: 20 69 73 20 72 65 61 64 61 62 6c 65 2e 0a 2a 2f is readable..*/
83a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
83b0: 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 ACCESS_EXISTS
83c0: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 0.#define SQLIT
83d0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 E_ACCESS_READWRI
83e0: 54 45 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c TE 1.#define SQL
83f0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 ITE_ACCESS_READ
8400: 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 2../*.** CA
8410: 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 PI3REF: Initiali
8420: 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 ze The SQLite Li
8430: 62 72 61 72 79 20 7b 48 31 30 31 33 30 7d 20 3c brary {H10130} <
8440: 53 32 30 30 30 30 3e 3c 53 33 30 31 30 30 3e 0a S20000><S30100>.
8450: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
8460: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 3_initialize() r
8470: 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a outine initializ
8480: 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 es the.** SQLite
8490: 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 library. The s
84a0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
84b0: 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 ) routine.** dea
84c0: 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 llocates any res
84d0: 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65 ources that were
84e0: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 allocated by sq
84f0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
8500: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c ()..**.** A call
8510: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 to sqlite3_init
8520: 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 ialize() is an "
8530: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 effective" call
8540: 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 if it is.** the
8550: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 first time sqlit
8560: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
8570: 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e is invoked durin
8580: 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f g the lifetime o
8590: 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 f.** the process
85a0: 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 , or if it is th
85b0: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c e first time sql
85c0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
85d0: 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 ) is invoked.**
85e0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c following a call
85f0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 to sqlite3_shut
8600: 64 6f 77 6e 28 29 2e 20 20 4f 6e 6c 79 20 61 6e down(). Only an
8610: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a effective call.
8620: 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e ** of sqlite3_in
8630: 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 itialize() does
8640: 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 any initializati
8650: 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 on. All other c
8660: 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d alls.** are harm
8670: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a less no-ops..**.
8680: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c ** A call to sql
8690: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 ite3_shutdown()
86a0: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 is an "effective
86b0: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 " call if it is
86c0: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c the first.** cal
86d0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 l to sqlite3_shu
86e0: 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 tdown() since th
86f0: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 e last sqlite3_i
8700: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 4f 6e nitialize(). On
8710: 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 ly.** an effecti
8720: 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 ve call to sqlit
8730: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f e3_shutdown() do
8740: 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c es any deinitial
8750: 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 ization..** All
8760: 6f 74 68 65 72 20 63 61 6c 6c 73 20 74 6f 20 73 other calls to s
8770: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
8780: 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e ) are harmless n
8790: 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f o-ops..**.** Amo
87a0: 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c ng other things,
87b0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
87c0: 69 7a 65 28 29 20 73 68 61 6c 6c 20 69 6e 76 6f ize() shall invo
87d0: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 ke.** sqlite3_os
87e0: 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 _init(). Simila
87f0: 72 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 68 75 rly, sqlite3_shu
8800: 74 64 6f 77 6e 28 29 0a 2a 2a 20 73 68 61 6c 6c tdown().** shall
8810: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f invoke sqlite3_
8820: 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 os_end()..**.**
8830: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 The sqlite3_init
8840: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 ialize() routine
8850: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
8860: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e _OK] on success.
8870: 0a 2a 2a 20 49 66 20 66 6f 72 20 73 6f 6d 65 20 .** If for some
8880: 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f reason, sqlite3_
8890: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 initialize() is
88a0: 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 unable to initia
88b0: 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 lize.** the libr
88c0: 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 ary (perhaps it
88d0: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c is unable to all
88e0: 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 ocate a needed r
88f0: 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 esource such.**
8900: 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 as a mutex) it r
8910: 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 eturns an [error
8920: 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 code] other tha
8930: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a n [SQLITE_OK]..*
8940: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
8950: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f _initialize() ro
8960: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 utine is called
8970: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 internally by ma
8980: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 ny other.** SQLi
8990: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f te interfaces so
89a0: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 that an applica
89b0: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 tion usually doe
89c0: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a s not need to.**
89d0: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f invoke sqlite3_
89e0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 initialize() dir
89f0: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d ectly. For exam
8a00: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ple, [sqlite3_op
8a10: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 en()].** calls s
8a20: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
8a30: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 e() so the SQLit
8a40: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 e library will b
8a50: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a e automatically.
8a60: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 ** initialized w
8a70: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 hen [sqlite3_ope
8a80: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 n()] is called i
8a90: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 f it has not be
8aa0: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 initialized.** a
8ab0: 6c 72 65 61 64 79 2e 20 20 48 6f 77 65 76 65 72 lready. However
8ac0: 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 , if SQLite is c
8ad0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 ompiled with the
8ae0: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 [SQLITE_OMIT_AU
8af0: 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 TOINIT].** compi
8b00: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 le-time option,
8b10: 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 then the automat
8b20: 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 ic calls to sqli
8b30: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
8b40: 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 .** are omitted
8b50: 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 and the applicat
8b60: 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 ion must call sq
8b70: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
8b80: 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 () directly.** p
8b90: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e rior to using an
8ba0: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 y other SQLite i
8bb0: 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d nterface. For m
8bc0: 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 aximum portabili
8bd0: 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 ty,.** it is rec
8be0: 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 ommended that ap
8bf0: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 plications alway
8c00: 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 s invoke sqlite3
8c10: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a _initialize().**
8c20: 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 directly prior
8c30: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 to using any oth
8c40: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 er SQLite interf
8c50: 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c ace. Future rel
8c60: 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 eases.** of SQLi
8c70: 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 te may require t
8c80: 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 his. In other w
8c90: 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 ords, the behavi
8ca0: 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 or exhibited.**
8cb0: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 when SQLite is c
8cc0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 ompiled with [SQ
8cd0: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e LITE_OMIT_AUTOIN
8ce0: 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 IT] might become
8cf0: 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 the.** default
8d00: 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 behavior in some
8d10: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 future release
8d20: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a of SQLite..**.**
8d30: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f The sqlite3_os_
8d40: 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 init() routine d
8d50: 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 oes operating-sy
8d60: 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a stem specific.**
8d70: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 initialization
8d80: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 of the SQLite li
8d90: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 brary. The sqli
8da0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 te3_os_end().**
8db0: 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 routine undoes t
8dc0: 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c he effect of sql
8dd0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 ite3_os_init().
8de0: 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a Typical tasks.*
8df0: 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 * performed by t
8e00: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e hese routines in
8e10: 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e clude allocation
8e20: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e or deallocation
8e30: 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 .** of static re
8e40: 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c sources, initial
8e50: 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 ization of globa
8e60: 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 l variables,.**
8e70: 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 setting up a def
8e80: 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 ault [sqlite3_vf
8e90: 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 s] module, or se
8ea0: 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 tting up.** a de
8eb0: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 fault configurat
8ec0: 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ion using [sqlit
8ed0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a e3_config()]..**
8ee0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
8ef0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 ion should never
8f00: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 invoke either s
8f10: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
8f20: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f .** or sqlite3_o
8f30: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 s_end() directly
8f40: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 . The applicati
8f50: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 on should only i
8f60: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 nvoke.** sqlite3
8f70: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e _initialize() an
8f80: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f d sqlite3_shutdo
8f90: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 wn(). The sqlit
8fa0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 e3_os_init().**
8fb0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c interface is cal
8fc0: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c led automaticall
8fd0: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 y by sqlite3_ini
8fe0: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a tialize() and.**
8ff0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
9000: 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 ) is called by s
9010: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
9020: 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a ). Appropriate.
9030: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
9040: 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f ns for sqlite3_o
9050: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c s_init() and sql
9060: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a ite3_os_end().**
9070: 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 are built into
9080: 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 SQLite when it i
9090: 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 75 s compiled for u
90a0: 6e 69 78 2c 20 77 69 6e 64 6f 77 73 2c 20 6f 72 nix, windows, or
90b0: 20 6f 73 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 62 os/2..** When b
90c0: 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 uilt for other p
90d0: 6c 61 74 66 6f 72 6d 73 20 28 75 73 69 6e 67 20 latforms (using
90e0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f the [SQLITE_OS_O
90f0: 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d THER=1] compile-
9100: 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 time.** option)
9110: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
9120: 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 must supply a su
9130: 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 itable implement
9140: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c ation for.** sql
9150: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 ite3_os_init() a
9160: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e nd sqlite3_os_en
9170: 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 d(). An applica
9180: 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a tion-supplied.**
9190: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
91a0: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e of sqlite3_os_in
91b0: 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f it() or sqlite3_
91c0: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 os_end().** must
91d0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
91e0: 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 OK] on success a
91f0: 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 nd some other [e
9200: 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a rror code] upon.
9210: 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 ** failure..*/.i
9220: 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 nt sqlite3_initi
9230: 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 alize(void);.int
9240: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
9250: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c n(void);.int sql
9260: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 ite3_os_init(voi
9270: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f d);.int sqlite3_
9280: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f os_end(void);../
9290: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
92a0: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 onfiguring The S
92b0: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b 48 QLite Library {H
92c0: 31 34 31 30 30 7d 20 3c 53 32 30 30 30 30 3e 3c 14100} <S20000><
92d0: 53 33 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 S30200>.** EXPER
92e0: 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 IMENTAL.**.** Th
92f0: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 e sqlite3_config
9300: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
9310: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f used to make glo
9320: 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f bal configuratio
9330: 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 n.** changes to
9340: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 SQLite in order
9350: 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 to tune SQLite t
9360: 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e o the specific n
9370: 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 eeds of.** the a
9380: 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 pplication. The
9390: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 default configu
93a0: 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d ration is recomm
93b0: 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a ended for most.*
93c0: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 * applications a
93d0: 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 nd so this routi
93e0: 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f ne is usually no
93f0: 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 t necessary. It
9400: 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 is.** provided
9410: 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 to support rare
9420: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 applications wit
9430: 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e h unusual needs.
9440: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
9450: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 e3_config() inte
9460: 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 rface is not thr
9470: 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 eadsafe. The ap
9480: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 plication.** mus
9490: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f t insure that no
94a0: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e other SQLite in
94b0: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 terfaces are inv
94c0: 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a oked by other.**
94d0: 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 threads while s
94e0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
94f0: 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 is running. Fur
9500: 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 thermore, sqlite
9510: 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 3_config().** ma
9520: 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 y only be invoke
9530: 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 d prior to libra
9540: 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f ry initializatio
9550: 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 n using.** [sqli
9560: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
9570: 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 ] or after shutd
9580: 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f own by [sqlite3_
9590: 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 shutdown()]..**
95a0: 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 Note, however, t
95b0: 68 61 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 hat sqlite3_conf
95c0: 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c ig() can be call
95d0: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 ed as part of th
95e0: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e.** implementat
95f0: 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 ion of an applic
9600: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 ation-defined [s
9610: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
9620: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 ]..**.** The fir
9630: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 st argument to s
9640: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
9650: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a is an integer.**
9660: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
9670: 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63 SINGLETHREAD | c
9680: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
9690: 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d ion] that determ
96a0: 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f ines.** what pro
96b0: 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 perty of SQLite
96c0: 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 is to be configu
96d0: 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 red. Subsequent
96e0: 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 arguments.** va
96f0: 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 ry depending on
9700: 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 the [SQLITE_CONF
9710: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 IG_SINGLETHREAD
9720: 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 | configuration
9730: 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 option].** in th
9740: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
9750: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 63 ..**.** When a c
9760: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
9770: 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 ion is set, sqli
9780: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 te3_config() ret
9790: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d urns [SQLITE_OK]
97a0: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 74 69 ..** If the opti
97b0: 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 on is unknown or
97c0: 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c SQLite is unabl
97d0: 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 e to set the opt
97e0: 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 ion.** then this
97f0: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
9800: 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 a non-zero [err
9810: 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 or code]..**.**
9820: 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
9830: 20 5b 48 31 34 31 30 33 5d 20 5b 48 31 34 31 30 [H14103] [H1410
9840: 36 5d 20 5b 48 31 34 31 32 30 5d 20 5b 48 31 34 6] [H14120] [H14
9850: 31 32 33 5d 20 5b 48 31 34 31 32 36 5d 20 5b 48 123] [H14126] [H
9860: 31 34 31 32 39 5d 20 5b 48 31 34 31 33 32 5d 20 14129] [H14132]
9870: 5b 48 31 34 31 33 35 5d 0a 2a 2a 20 5b 48 31 34 [H14135].** [H14
9880: 31 33 38 5d 20 5b 48 31 34 31 34 31 5d 20 5b 48 138] [H14141] [H
9890: 31 34 31 34 34 5d 20 5b 48 31 34 31 34 37 5d 20 14144] [H14147]
98a0: 5b 48 31 34 31 35 30 5d 20 5b 48 31 34 31 35 33 [H14150] [H14153
98b0: 5d 20 5b 48 31 34 31 35 36 5d 20 5b 48 31 34 31 ] [H14156] [H141
98c0: 35 39 5d 0a 2a 2a 20 5b 48 31 34 31 36 32 5d 20 59].** [H14162]
98d0: 5b 48 31 34 31 36 35 5d 20 5b 48 31 34 31 36 38 [H14165] [H14168
98e0: 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 ].*/.SQLITE_EXPE
98f0: 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c RIMENTAL int sql
9900: 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c ite3_config(int,
9910: 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ...);../*.** CA
9920: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 PI3REF: Configur
9930: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
9940: 63 74 69 6f 6e 73 20 20 7b 48 31 34 32 30 30 7d ctions {H14200}
9950: 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 <S20000>.** EXP
9960: 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 ERIMENTAL.**.**
9970: 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 The sqlite3_db_c
9980: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 onfig() interfac
9990: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b e is used to mak
99a0: 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a e configuration.
99b0: 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 ** changes to a
99c0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
99d0: 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 tion]. The inte
99e0: 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 rface is similar
99f0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
9a00: 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 config()] except
9a10: 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 that the change
9a20: 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e s apply to a sin
9a30: 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 gle.** [database
9a40: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 connection] (sp
9a50: 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 ecified in the f
9a60: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 20 irst argument).
9a70: 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f The.** sqlite3_
9a80: 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 db_config() inte
9a90: 72 66 61 63 65 20 63 61 6e 20 6f 6e 6c 79 20 62 rface can only b
9aa0: 65 20 75 73 65 64 20 69 6d 6d 65 64 69 61 74 65 e used immediate
9ab0: 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74 68 65 20 ly after.** the
9ac0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
9ad0: 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64 20 75 ion is created u
9ae0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 sing [sqlite3_op
9af0: 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 en()],.** [sqlit
9b00: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 e3_open16()], or
9b10: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
9b20: 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 2()]. .**.** Th
9b30: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
9b40: 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f t to sqlite3_db_
9b50: 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 config(D,V,...)
9b60: 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 is the.** confi
9b70: 67 75 72 61 74 69 6f 6e 20 76 65 72 62 20 2d 20 guration verb -
9b80: 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 an integer code
9b90: 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 that indicates w
9ba0: 68 61 74 0a 2a 2a 20 61 73 70 65 63 74 20 6f 66 hat.** aspect of
9bb0: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
9bc0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 onnection] is be
9bd0: 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a ing configured..
9be0: 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63 68 6f 69 ** The only choi
9bf0: 63 65 20 66 6f 72 20 74 68 69 73 20 76 61 6c 75 ce for this valu
9c00: 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 42 43 e is [SQLITE_DBC
9c10: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d ONFIG_LOOKASIDE]
9c20: 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62 73 20 61 ..** New verbs a
9c30: 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62 65 20 re likely to be
9c40: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 added in future
9c50: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 releases of SQLi
9c60: 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 te..** Additiona
9c70: 6c 20 61 72 67 75 6d 65 6e 74 73 20 64 65 70 65 l arguments depe
9c80: 6e 64 20 6f 6e 20 74 68 65 20 76 65 72 62 2e 0a nd on the verb..
9c90: 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
9ca0: 74 73 3a 0a 2a 2a 20 5b 48 31 34 32 30 33 5d 20 ts:.** [H14203]
9cb0: 5b 48 31 34 32 30 36 5d 20 5b 48 31 34 32 30 39 [H14206] [H14209
9cc0: 5d 20 5b 48 31 34 32 31 32 5d 20 5b 48 31 34 32 ] [H14212] [H142
9cd0: 31 35 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 15].*/.SQLITE_EX
9ce0: 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 PERIMENTAL int s
9cf0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
9d00: 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f (sqlite3*, int o
9d10: 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 p, ...);../*.**
9d20: 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 CAPI3REF: Memory
9d30: 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 Allocation Rout
9d40: 69 6e 65 73 20 7b 48 31 30 31 35 35 7d 20 3c 53 ines {H10155} <S
9d50: 32 30 31 32 30 3e 0a 2a 2a 20 45 58 50 45 52 49 20120>.** EXPERI
9d60: 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20 MENTAL.**.** An
9d70: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 instance of this
9d80: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 object defines
9d90: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 the interface be
9da0: 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 tween SQLite.**
9db0: 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 and low-level me
9dc0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
9dd0: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 routines..**.**
9de0: 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 This object is u
9df0: 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 sed in only one
9e00: 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c place in the SQL
9e10: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a ite interface..*
9e20: 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 * A pointer to a
9e30: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
9e40: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 is object is the
9e50: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 argument to.**
9e60: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
9e70: 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 )] when the conf
9e80: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
9e90: 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 is.** [SQLITE_C
9ea0: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 ONFIG_MALLOC].
9eb0: 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 By creating an i
9ec0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
9ed0: 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 object.** and pa
9ee0: 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c ssing it to [sql
9ef0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 64 ite3_config()] d
9f00: 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 uring configurat
9f10: 69 6f 6e 2c 20 61 6e 0a 2a 2a 20 61 70 70 6c 69 ion, an.** appli
9f20: 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 cation can speci
9f30: 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 fy an alternativ
9f40: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
9f50: 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a ion subsystem.**
9f60: 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 for SQLite to u
9f70: 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 se for all of it
9f80: 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 s dynamic memory
9f90: 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f needs..**.** No
9fa0: 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 te that SQLite c
9fb0: 6f 6d 65 73 20 77 69 74 68 20 61 20 62 75 69 6c omes with a buil
9fc0: 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f t-in memory allo
9fd0: 63 61 74 6f 72 20 74 68 61 74 20 69 73 0a 2a 2a cator that is.**
9fe0: 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 perfectly adequ
9ff0: 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 ate for the over
a000: 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 whelming majorit
a010: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e y of application
a020: 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 s.** and that th
a030: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c is object is onl
a040: 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 y useful to a ti
a050: 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 ny minority of a
a060: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 pplications.** w
a070: 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 ith specialized
a080: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
a090: 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 n requirements.
a0a0: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a This object is.
a0b0: 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 ** also used dur
a0c0: 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 ing testing of S
a0d0: 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 QLite in order t
a0e0: 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 o specify an alt
a0f0: 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f ernative.** memo
a100: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 ry allocator tha
a110: 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f t simulates memo
a120: 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 ry out-of-memory
a130: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a conditions in.*
a140: 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 * order to verif
a150: 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 y that SQLite re
a160: 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c covers gracefull
a170: 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 y from such.** c
a180: 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a onditions..**.**
a190: 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 46 The xMalloc, xF
a1a0: 72 65 65 2c 20 61 6e 64 20 78 52 65 61 6c 6c 6f ree, and xReallo
a1b0: 63 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 c methods must w
a1c0: 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 ork like the.**
a1d0: 6d 61 6c 6c 6f 63 28 29 2c 20 66 72 65 65 28 29 malloc(), free()
a1e0: 2c 20 61 6e 64 20 72 65 61 6c 6c 6f 63 28 29 20 , and realloc()
a1f0: 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 functions from t
a200: 68 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62 72 he standard libr
a210: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 ary..**.** xSize
a220: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 should return t
a230: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a he allocated siz
a240: 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c e of a memory al
a250: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 location.** prev
a260: 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 iously obtained
a270: 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 from xMalloc or
a280: 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 xRealloc. The a
a290: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a llocated size.**
a2a0: 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 is always at le
a2b0: 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 ast as big as th
a2c0: 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 e requested size
a2d0: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 but may be larg
a2e0: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 er..**.** The xR
a2f0: 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 oundup method re
a300: 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 turns what would
a310: 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 be the allocate
a320: 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d d size of.** a m
a330: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
a340: 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 given a particu
a350: 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 lar requested si
a360: 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 ze. Most memory
a370: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 .** allocators r
a380: 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 ound up memory a
a390: 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 llocations at le
a3a0: 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 ast to the next
a3b0: 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 multiple.** of 8
a3c0: 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f . Some allocato
a3d0: 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 rs round up to a
a3e0: 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 larger multiple
a3f0: 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f or to a power o
a400: 66 20 32 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 f 2..**.** The x
a410: 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 Init method init
a420: 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f ializes the memo
a430: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 ry allocator. (
a440: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 For example,.**
a450: 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 it might allocat
a460: 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 e any require mu
a470: 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c texes or initial
a480: 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 ize internal dat
a490: 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e a.** structures.
a4a0: 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 The xShutdown
a4b0: 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 method is invoke
a4c0: 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 d (indirectly) b
a4d0: 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 y.** [sqlite3_sh
a4e0: 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 utdown()] and sh
a4f0: 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 ould deallocate
a500: 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 any resources ac
a510: 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e quired.** by xIn
a520: 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 it. The pAppDat
a530: 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 a pointer is use
a540: 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 d as the only pa
a550: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 rameter to.** xI
a560: 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 nit and xShutdow
a570: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 n..*/.typedef st
a580: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d ruct sqlite3_mem
a590: 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 _methods sqlite3
a5a0: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 _mem_methods;.st
a5b0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d ruct sqlite3_mem
a5c0: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 _methods {. voi
a5d0: 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e d *(*xMalloc)(in
a5e0: 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d t); /* M
a5f0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
a600: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 function */. v
a610: 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 oid (*xFree)(voi
a620: 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a d*); /*
a630: 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c Free a prior al
a640: 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f location */. vo
a650: 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 id *(*xRealloc)(
a660: 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 void*,int); /*
a670: 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 Resize an alloca
a680: 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a tion */. int (*
a690: 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 xSize)(void*);
a6a0: 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 /* Retu
a6b0: 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 rn the size of a
a6c0: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a n allocation */.
a6d0: 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 int (*xRoundup
a6e0: 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 )(int);
a6f0: 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 /* Round up req
a700: 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c uest size to all
a710: 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a ocation size */.
a720: 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 int (*xInit)(v
a730: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 oid*);
a740: 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 /* Initialize t
a750: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
a760: 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a tor */. void (*
a770: 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a xShutdown)(void*
a780: 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 ); /* Deini
a790: 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f tialize the memo
a7a0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a ry allocator */.
a7b0: 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 void *pAppData
a7c0: 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ;
a7d0: 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 /* Argument to
a7e0: 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 xInit() and xShu
a7f0: 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f tdown() */.};../
a800: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
a810: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 onfiguration Opt
a820: 69 6f 6e 73 20 7b 48 31 30 31 36 30 7d 20 3c 53 ions {H10160} <S
a830: 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 20000>.** EXPERI
a840: 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 MENTAL.**.** The
a850: 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 se constants are
a860: 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 the available i
a870: 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 nteger configura
a880: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 tion options tha
a890: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 t.** can be pass
a8a0: 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 ed as the first
a8b0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
a8c0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
a8d0: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a )] interface..**
a8e0: 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 .** New configur
a8f0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 ation options ma
a900: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 y be added in fu
a910: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 ture releases of
a920: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 SQLite..** Exis
a930: 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 ting configurati
a940: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 on options might
a950: 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 be discontinued
a960: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a . Applications.
a970: 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 ** should check
a980: 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 the return code
a990: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f from [sqlite3_co
a9a0: 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 nfig()] to make
a9b0: 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 sure that.** the
a9c0: 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 call worked. T
a9d0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 he [sqlite3_conf
a9e0: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 ig()] interface
a9f0: 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a will return a.**
aa00: 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 non-zero [error
aa10: 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 code] if a disc
aa20: 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 ontinued or unsu
aa30: 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 pported configur
aa40: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 ation option.**
aa50: 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a is invoked..**.*
aa60: 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 * <dl>.** <dt>SQ
aa70: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 LITE_CONFIG_SING
aa80: 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a LETHREAD</dt>.**
aa90: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e <dd>There are n
aaa0: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 o arguments to t
aab0: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 his option. Thi
aac0: 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c 65 s option disable
aad0: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e s.** all mutexin
aae0: 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 g and puts SQLit
aaf0: 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 e into a mode wh
ab00: 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 ere it can only
ab10: 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 be used.** by a
ab20: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 3c 2f single thread.</
ab30: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
ab40: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 LITE_CONFIG_MULT
ab50: 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 ITHREAD</dt>.**
ab60: 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f <dd>There are no
ab70: 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 arguments to th
ab80: 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 is option. This
ab90: 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 option disables
aba0: 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 .** mutexing on
abb0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
abc0: 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 tion] and [prepa
abd0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f red statement] o
abe0: 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 bjects..** The a
abf0: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 pplication is re
ac00: 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 sponsible for se
ac10: 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 rializing access
ac20: 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 to.** [database
ac30: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e connections] an
ac40: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
ac50: 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 ements]. But ot
ac60: 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 her mutexes.** a
ac70: 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 re enabled so th
ac80: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 at SQLite will b
ac90: 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e e safe to use in
aca0: 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 a multi-threade
acb0: 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 d.** environment
acc0: 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 as long as no t
acd0: 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d wo threads attem
ace0: 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 pt to use the sa
acf0: 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 me.** [database
ad00: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 connection] at t
ad10: 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 53 he same time. S
ad20: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e ee the [threadin
ad30: 67 20 6d 6f 64 65 5d 0a 2a 2a 20 64 6f 63 75 6d g mode].** docum
ad40: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 entation for add
ad50: 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 itional informat
ad60: 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ion.</dd>.**.**
ad70: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
ad80: 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 G_SERIALIZED</dt
ad90: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 >.** <dd>There a
ada0: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 re no arguments
adb0: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 to this option.
adc0: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 This option ena
add0: 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 bles.** all mute
ade0: 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 xes including th
adf0: 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d e recursive.** m
ae00: 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 utexes on [datab
ae10: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
ae20: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 and [prepared st
ae30: 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 atement] objects
ae40: 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 ..** In this mod
ae50: 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20 e (which is the
ae60: 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c default when SQL
ae70: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
ae80: 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f with.** [SQLITE_
ae90: 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 THREADSAFE=1]) t
aea0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 he SQLite librar
aeb0: 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 y will itself se
aec0: 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a rialize access.*
aed0: 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 * to [database c
aee0: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 onnections] and
aef0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
af00: 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 ents] so that th
af10: 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e e.** application
af20: 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 is free to use
af30: 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 the same [databa
af40: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f se connection] o
af50: 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 r the.** same [p
af60: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
af70: 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 t] in different
af80: 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 threads at the s
af90: 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 53 65 65 ame time..** See
afa0: 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 the [threading
afb0: 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 mode] documentat
afc0: 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e ion for addition
afd0: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c al information.<
afe0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
aff0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c QLITE_CONFIG_MAL
b000: 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e LOC</dt>.** <dd>
b010: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
b020: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
b030: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 ent which is a p
b040: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 ointer to an.**
b050: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 instance of the
b060: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 [sqlite3_mem_met
b070: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e hods] structure.
b080: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 The argument s
b090: 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 pecifies.** alte
b0a0: 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 rnative low-leve
b0b0: 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 l memory allocat
b0c0: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 ion routines to
b0d0: 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 be used in place
b0e0: 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 of.** the memor
b0f0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 y allocation rou
b100: 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f tines built into
b110: 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a SQLite.</dd>.**
b120: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
b130: 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c ONFIG_GETMALLOC<
b140: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 /dt>.** <dd>This
b150: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
b160: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
b170: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 which is a point
b180: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 er to an.** inst
b190: 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c ance of the [sql
b1a0: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
b1b0: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 ] structure. Th
b1c0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d e [sqlite3_mem_m
b1d0: 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 ethods].** struc
b1e0: 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 ture is filled w
b1f0: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c ith the currentl
b200: 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 y defined memory
b210: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 allocation rout
b220: 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 ines..** This op
b230: 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 tion can be used
b240: 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 to overload the
b250: 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 default memory
b260: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f allocation.** ro
b270: 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 utines with a wr
b280: 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c apper that simul
b290: 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c ations memory al
b2a0: 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 location failure
b2b0: 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 or.** tracks me
b2c0: 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 mory usage, for
b2d0: 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a example.</dd>.**
b2e0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
b2f0: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c ONFIG_MEMSTATUS<
b300: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 /dt>.** <dd>This
b310: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 option takes si
b320: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 ngle argument of
b330: 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 type int, inter
b340: 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 preted as a .**
b350: 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 boolean, which e
b360: 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c nables or disabl
b370: 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f es the collectio
b380: 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f n of memory allo
b390: 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 cation .** stati
b3a0: 73 74 69 63 73 2e 20 57 68 65 6e 20 64 69 73 61 stics. When disa
b3b0: 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 bled, the follow
b3c0: 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 ing SQLite inter
b3d0: 66 61 63 65 73 20 62 65 63 6f 6d 65 20 0a 2a 2a faces become .**
b3e0: 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c non-operational
b3f0: 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 :.** <ul>.**
b400: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d <li> [sqlite3_m
b410: 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a emory_used()].**
b420: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 <li> [sqlite3
b430: 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 _memory_highwate
b440: 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b r()].** <li> [
b450: 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 sqlite3_soft_hea
b460: 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 20 20 p_limit()].**
b470: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 <li> [sqlite3_st
b480: 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 atus()].** </u
b490: 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a l>.** </dd>.**.*
b4a0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
b4b0: 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e FIG_SCRATCH</dt>
b4c0: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 .** <dd>This opt
b4d0: 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 ion specifies a
b4e0: 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 static memory bu
b4f0: 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 ffer that SQLite
b500: 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 can use for.**
b510: 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 scratch memory.
b520: 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 There are three
b530: 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 arguments: A p
b540: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 ointer to the me
b550: 6d 6f 72 79 2c 20 74 68 65 0a 2a 2a 20 73 69 7a mory, the.** siz
b560: 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 e of each scratc
b570: 68 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 h buffer (sz), a
b580: 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 nd the number of
b590: 20 62 75 66 66 65 72 73 20 28 4e 29 2e 20 20 54 buffers (N). T
b5a0: 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e he sz.** argumen
b5b0: 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74 t must be a mult
b5c0: 69 70 6c 65 20 6f 66 20 31 36 2e 20 54 68 65 20 iple of 16. The
b5d0: 73 7a 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f sz parameter sho
b5e0: 75 6c 64 20 62 65 20 61 20 66 65 77 20 62 79 74 uld be a few byt
b5f0: 65 73 0a 2a 2a 20 6c 61 72 67 65 72 20 74 68 61 es.** larger tha
b600: 6e 20 74 68 65 20 61 63 74 75 61 6c 20 73 63 72 n the actual scr
b610: 61 74 63 68 20 73 70 61 63 65 20 72 65 71 75 69 atch space requi
b620: 72 65 64 20 64 75 65 20 69 6e 74 65 72 6e 61 6c red due internal
b630: 20 6f 76 65 72 68 65 61 64 2e 0a 2a 2a 20 54 68 overhead..** Th
b640: 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d e first.** argum
b650: 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 ent should point
b660: 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f to an allocatio
b670: 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a n of at least sz
b680: 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f *N bytes of memo
b690: 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 ry..** SQLite wi
b6a0: 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 ll use no more t
b6b0: 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20 han one scratch
b6c0: 62 75 66 66 65 72 20 61 74 20 6f 6e 63 65 20 70 buffer at once p
b6d0: 65 72 20 74 68 72 65 61 64 2c 20 73 6f 0a 2a 2a er thread, so.**
b6e0: 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 N should be set
b6f0: 20 74 6f 20 74 68 65 20 65 78 70 65 63 74 65 64 to the expected
b700: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
b710: 6f 66 20 74 68 72 65 61 64 73 2e 20 20 54 68 65 of threads. The
b720: 20 73 7a 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 sz.** parameter
b730: 20 73 68 6f 75 6c 64 20 62 65 20 36 20 74 69 6d should be 6 tim
b740: 65 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 es the size of t
b750: 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 he largest datab
b760: 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a ase page size..*
b770: 2a 20 53 63 72 61 74 63 68 20 62 75 66 66 65 72 * Scratch buffer
b780: 73 20 61 72 65 20 75 73 65 64 20 61 73 20 70 61 s are used as pa
b790: 72 74 20 6f 66 20 74 68 65 20 62 74 72 65 65 20 rt of the btree
b7a0: 62 61 6c 61 6e 63 65 20 6f 70 65 72 61 74 69 6f balance operatio
b7b0: 6e 2e 20 20 49 66 0a 2a 2a 20 54 68 65 20 62 74 n. If.** The bt
b7c0: 72 65 65 20 62 61 6c 61 6e 63 65 72 20 6e 65 65 ree balancer nee
b7d0: 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 20 6d 65 ds additional me
b7e0: 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 mory beyond what
b7f0: 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 0a is provided by.
b800: 2a 2a 20 73 63 72 61 74 63 68 20 62 75 66 66 65 ** scratch buffe
b810: 72 73 20 6f 72 20 69 66 20 6e 6f 20 73 63 72 61 rs or if no scra
b820: 74 63 68 20 62 75 66 66 65 72 20 73 70 61 63 65 tch buffer space
b830: 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 is specified, t
b840: 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6f hen SQLite.** go
b850: 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d es to [sqlite3_m
b860: 61 6c 6c 6f 63 28 29 5d 20 74 6f 20 6f 62 74 61 alloc()] to obta
b870: 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 69 74 in the memory it
b880: 20 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a needs.</dd>.**.
b890: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ** <dt>SQLITE_CO
b8a0: 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f NFIG_PAGECACHE</
b8b0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
b8c0: 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 option specifies
b8d0: 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 a static memory
b8e0: 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c buffer that SQL
b8f0: 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a ite can use for.
b900: 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ** the database
b910: 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20 page cache with
b920: 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 the default page
b930: 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 61 cache implemena
b940: 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 tion. .** This
b950: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 configuration sh
b960: 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 ould not be used
b970: 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 if an applicati
b980: 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a on-define page.*
b990: 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e * cache implemen
b9a0: 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 tation is loaded
b9b0: 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 using the SQLIT
b9c0: 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 E_CONFIG_PCACHE
b9d0: 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 option..** There
b9e0: 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d are three argum
b9f0: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 ents to this opt
ba00: 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 ion: A pointer t
ba10: 6f 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c o the.** memory,
ba20: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 the size of eac
ba30: 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73 h page buffer (s
ba40: 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 z), and the numb
ba50: 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e er of pages (N).
ba60: 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d .** The sz argum
ba70: 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f ent must be a po
ba80: 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 wer of two betwe
ba90: 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 en 512 and 32768
baa0: 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 . The first.**
bab0: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 argument should
bac0: 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f point to an allo
bad0: 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 cation of at lea
bae0: 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 st sz*N bytes of
baf0: 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 memory..** SQLi
bb00: 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 te will use the
bb10: 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 memory provided
bb20: 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 by the first arg
bb30: 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 ument to satisfy
bb40: 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e its.** memory n
bb50: 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 eeds for the fir
bb60: 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 st N pages that
bb70: 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 it adds to cache
bb80: 2e 20 20 49 66 20 61 64 64 69 74 69 6f 6e 61 6c . If additional
bb90: 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d .** page cache m
bba0: 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 emory is needed
bbb0: 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 beyond what is p
bbc0: 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 rovided by this
bbd0: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 option, then.**
bbe0: 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b SQLite goes to [
bbf0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
bc00: 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 ] for the additi
bc10: 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 onal storage spa
bc20: 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 ce..** The imple
bc30: 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 mentation might
bc40: 75 73 65 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 use one or more
bc50: 6f 66 20 74 68 65 20 4e 20 62 75 66 66 65 72 73 of the N buffers
bc60: 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a 20 6d 65 6d to hold .** mem
bc70: 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20 69 ory accounting i
bc80: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20 3c 2f 64 64 nformation. </dd
bc90: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
bca0: 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f TE_CONFIG_HEAP</
bcb0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
bcc0: 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 option specifies
bcd0: 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 a static memory
bce0: 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c buffer that SQL
bcf0: 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 ite will use.**
bd00: 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 for all of its d
bd10: 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c ynamic memory al
bd20: 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 location needs b
bd30: 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 eyond those prov
bd40: 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b ided.** for by [
bd50: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 SQLITE_CONFIG_SC
bd60: 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 RATCH] and [SQLI
bd70: 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 TE_CONFIG_PAGECA
bd80: 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 CHE]..** There a
bd90: 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e re three argumen
bda0: 74 73 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f ts: A pointer to
bdb0: 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20 74 68 65 the memory, the
bdc0: 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 number of.** by
bdd0: 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 tes in the memor
bde0: 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 y buffer, and th
bdf0: 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 e minimum alloca
be00: 74 69 6f 6e 20 73 69 7a 65 2e 20 20 49 66 0a 2a tion size. If.*
be10: 2a 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e * the first poin
be20: 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 ter (the memory
be30: 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c pointer) is NULL
be40: 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 , then SQLite re
be50: 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e verts.** to usin
be60: 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 g its default me
be70: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 mory allocator (
be80: 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f the system mallo
be90: 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 c() implementati
bea0: 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 on),.** undoing
beb0: 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 any prior invoca
bec0: 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f tion of [SQLITE_
bed0: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 CONFIG_MALLOC].
bee0: 20 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 If the.** memor
bef0: 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 y pointer is not
bf00: 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 NULL and either
bf10: 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f [SQLITE_ENABLE_
bf20: 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b MEMSYS3] or.** [
bf30: 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 SQLITE_ENABLE_ME
bf40: 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e MSYS5] are defin
bf50: 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 ed, then the alt
bf60: 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a ernative memory.
bf70: 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 ** allocator is
bf80: 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c engaged to handl
bf90: 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 e all of SQLites
bfa0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
bfb0: 6f 6e 20 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a 2a on needs.</dd>.*
bfc0: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
bfd0: 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 CONFIG_MUTEX</dt
bfe0: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 >.** <dd>This op
bff0: 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e tion takes a sin
c000: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 gle argument whi
c010: 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 ch is a pointer
c020: 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 to an.** instanc
c030: 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 e of the [sqlite
c040: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 3_mutex_methods]
c050: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 structure. The
c060: 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 argument specif
c070: 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 ies.** alternati
c080: 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 ve low-level mut
c090: 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 ex routines to b
c0a0: 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a e used in place.
c0b0: 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 ** the mutex rou
c0c0: 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f tines built into
c0d0: 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a SQLite.</dd>.**
c0e0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
c0f0: 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f ONFIG_GETMUTEX</
c100: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
c110: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
c120: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 ingle argument w
c130: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 hich is a pointe
c140: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 r to an.** insta
c150: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 nce of the [sqli
c160: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 te3_mutex_method
c170: 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 s] structure. T
c180: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d he.** [sqlite3_m
c190: 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a utex_methods].**
c1a0: 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 structure is fi
c1b0: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 lled with the cu
c1c0: 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 rrently defined
c1d0: 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 0a mutex routines..
c1e0: 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 ** This option c
c1f0: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 an be used to ov
c200: 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 erload the defau
c210: 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 lt mutex allocat
c220: 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 ion.** routines
c230: 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 with a wrapper u
c240: 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 sed to track mut
c250: 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 ex usage for per
c260: 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 formance.** prof
c270: 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 iling or testing
c280: 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f , for example.</
c290: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
c2a0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b LITE_CONFIG_LOOK
c2b0: 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ASIDE</dt>.** <d
c2c0: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 d>This option ta
c2d0: 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 kes two argument
c2e0: 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 s that determine
c2f0: 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 the default.**
c300: 6d 65 6d 6f 72 79 20 61 6c 6c 63 61 74 69 6f 6e memory allcation
c310: 20 6c 6f 6f 6b 61 73 69 64 65 20 6f 70 74 69 6d lookaside optim
c320: 69 7a 61 74 69 6f 6e 2e 20 20 54 68 65 20 66 69 ization. The fi
c330: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 rst argument is
c340: 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 the.** size of e
c350: 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 ach lookaside bu
c360: 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 ffer slot and th
c370: 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 e second is the
c380: 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f number of.** slo
c390: 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 ts allocated to
c3a0: 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f each database co
c3b0: 6e 6e 65 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a nnection.</dd>.*
c3c0: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
c3d0: 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 3c 2f 64 CONFIG_PCACHE</d
c3e0: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f t>.** <dd>This o
c3f0: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
c400: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 ngle argument wh
c410: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ich is a pointer
c420: 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 to.** an [sqlit
c430: 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 e3_pcache_method
c440: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 s] object. This
c450: 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 object specifie
c460: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a s the interface.
c470: 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 ** to a custom p
c480: 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d age cache implem
c490: 65 6e 74 61 74 69 6f 6e 2e 20 20 53 51 4c 69 74 entation. SQLit
c4a0: 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f e makes a copy o
c4b0: 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 f the.** object
c4c0: 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 20 and uses it for
c4d0: 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 page cache memor
c4e0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f y allocations.</
c4f0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
c500: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 LITE_CONFIG_GETP
c510: 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 CACHE</dt>.** <d
c520: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 d>This option ta
c530: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 kes a single arg
c540: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 ument which is a
c550: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a pointer to an.*
c560: 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 * [sqlite3_pcach
c570: 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 e_methods] objec
c580: 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 t. SQLite copie
c590: 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 s of the current
c5a0: 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 .** page cache i
c5b0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e mplementation in
c5c0: 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 3c to that object.<
c5d0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e /dd>.**.** </dl>
c5e0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
c5f0: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 TE_CONFIG_SINGLE
c600: 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 THREAD 1 /* ni
c610: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c l */.#define SQL
c620: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 ITE_CONFIG_MULTI
c630: 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e THREAD 2 /* n
c640: 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 il */.#define SQ
c650: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 LITE_CONFIG_SERI
c660: 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 ALIZED 3 /*
c670: 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nil */.#define S
c680: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c QLITE_CONFIG_MAL
c690: 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a LOC 4 /*
c6a0: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 sqlite3_mem_met
c6b0: 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 hods* */.#define
c6c0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 SQLITE_CONFIG_G
c6d0: 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 ETMALLOC 5
c6e0: 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d /* sqlite3_mem_m
c6f0: 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 ethods* */.#defi
c700: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
c710: 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 _SCRATCH 6
c720: 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 /* void*, int
c730: 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 sz, int N */.#de
c740: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
c750: 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 IG_PAGECACHE
c760: 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 7 /* void*, in
c770: 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 t sz, int N */.#
c780: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
c790: 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 NFIG_HEAP
c7a0: 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 8 /* void*,
c7b0: 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d int nByte, int m
c7c0: 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 in */.#define SQ
c7d0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 LITE_CONFIG_MEMS
c7e0: 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 TATUS 9 /*
c7f0: 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 boolean */.#defi
c800: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
c810: 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 _MUTEX 10
c820: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 /* sqlite3_mut
c830: 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 ex_methods* */.#
c840: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
c850: 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 NFIG_GETMUTEX
c860: 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 11 /* sqlite3
c870: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 _mutex_methods*
c880: 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 */./* previously
c890: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 SQLITE_CONFIG_C
c8a0: 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 HUNKALLOC 12 whi
c8b0: 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 ch is now unused
c8c0: 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 . */ .#define SQ
c8d0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b LITE_CONFIG_LOOK
c8e0: 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 ASIDE 13 /*
c8f0: 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 int int */.#defi
c900: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
c910: 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34 _PCACHE 14
c920: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 /* sqlite3_pca
c930: 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a che_methods* */.
c940: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
c950: 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 ONFIG_GETPCACHE
c960: 20 20 20 31 35 20 20 2f 2a 20 73 71 6c 69 74 65 15 /* sqlite
c970: 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3_pcache_methods
c980: 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 * */../*.** CAPI
c990: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 3REF: Configurat
c9a0: 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 48 31 30 ion Options {H10
c9b0: 31 37 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 170} <S20000>.**
c9c0: 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a EXPERIMENTAL.**
c9d0: 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 .** These consta
c9e0: 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 nts are the avai
c9f0: 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f lable integer co
ca00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
ca10: 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 ons that.** can
ca20: 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 be passed as the
ca30: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
ca40: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
ca50: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e _db_config()] in
ca60: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e terface..**.** N
ca70: 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ew configuration
ca80: 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 options may be
ca90: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 added in future
caa0: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 releases of SQLi
cab0: 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 te..** Existing
cac0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
cad0: 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 tions might be d
cae0: 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 iscontinued. Ap
caf0: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 plications.** sh
cb00: 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 ould check the r
cb10: 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 eturn code from
cb20: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 [sqlite3_db_conf
cb30: 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 ig()] to make su
cb40: 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 re that.** the c
cb50: 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 all worked. The
cb60: 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e [sqlite3_db_con
cb70: 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 fig()] interface
cb80: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a will return a.*
cb90: 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f * non-zero [erro
cba0: 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 r code] if a dis
cbb0: 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 continued or uns
cbc0: 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 upported configu
cbd0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a ration option.**
cbe0: 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a is invoked..**.
cbf0: 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 ** <dl>.** <dt>S
cc00: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c QLITE_DBCONFIG_L
cc10: 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a OOKASIDE</dt>.**
cc20: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e <dd>This option
cc30: 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 takes three add
cc40: 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 itional argument
cc50: 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 s that determine
cc60: 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 the .** [lookas
cc70: 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ide memory alloc
cc80: 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 ator] configurat
cc90: 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 ion for the [dat
cca0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
ccb0: 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 ]..** The first
ccc0: 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 argument (the th
ccd0: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ird parameter to
cce0: 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e [sqlite3_db_con
ccf0: 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 fig()] is a.** p
cd00: 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f ointer to a memo
cd10: 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 ry buffer to use
cd20: 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d for lookaside m
cd30: 65 6d 6f 72 79 2e 20 20 54 68 65 20 66 69 72 73 emory. The firs
cd40: 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 61 t.** argument ma
cd50: 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 y be NULL in whi
cd60: 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 ch case SQLite w
cd70: 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 ill allocate the
cd80: 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 62 75 lookaside.** bu
cd90: 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e ffer itself usin
cda0: 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f g [sqlite3_mallo
cdb0: 63 28 29 5d 2e 20 20 54 68 65 20 73 65 63 6f 6e c()]. The secon
cdc0: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
cdd0: 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 e.** size of eac
cde0: 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 h lookaside buff
cdf0: 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 er slot and the
ce00: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 third argument i
ce10: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a s the number of.
ce20: 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 ** slots. The s
ce30: 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 ize of the buffe
ce40: 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 r in the first a
ce50: 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 rgument must be
ce60: 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 greater than.**
ce70: 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 or equal to the
ce80: 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 product of the s
ce90: 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 econd and third
cea0: 61 72 67 75 6d 65 6e 74 73 2e 3c 2f 64 64 3e 0a arguments.</dd>.
ceb0: 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 **.** </dl>.*/.#
cec0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 define SQLITE_DB
ced0: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
cee0: 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 1001 /* voi
cef0: 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a 0a d* int int */...
cf00: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
cf10: 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c Enable Or Disabl
cf20: 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c e Extended Resul
cf30: 74 20 43 6f 64 65 73 20 7b 48 31 32 32 30 30 7d t Codes {H12200}
cf40: 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S10700>.**.**
cf50: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 The sqlite3_exte
cf60: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 nded_result_code
cf70: 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 s() routine enab
cf80: 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 les or disables
cf90: 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 the.** [extended
cfa0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 result codes] f
cfb0: 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 eature of SQLite
cfc0: 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 . The extended r
cfd0: 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 esult.** codes a
cfe0: 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 re disabled by d
cff0: 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f efault for histo
d000: 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c rical compatibil
d010: 69 74 79 20 63 6f 6e 73 69 64 65 72 61 74 69 6f ity consideratio
d020: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 ns..**.** Requir
d030: 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 ements:.** [H122
d040: 30 31 5d 20 5b 48 31 32 32 30 32 5d 0a 2a 2f 0a 01] [H12202].*/.
d050: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 int sqlite3_exte
d060: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 nded_result_code
d070: 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 s(sqlite3*, int
d080: 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 onoff);../*.** C
d090: 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e API3REF: Last In
d0a0: 73 65 72 74 20 52 6f 77 69 64 20 7b 48 31 32 32 sert Rowid {H122
d0b0: 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 20} <S10700>.**.
d0c0: 2a 2a 20 45 61 63 68 20 65 6e 74 72 79 20 69 6e ** Each entry in
d0d0: 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 an SQLite table
d0e0: 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 has a unique 64
d0f0: 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 -bit signed.** i
d100: 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 nteger key calle
d110: 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 d the [ROWID | "
d120: 72 6f 77 69 64 22 5d 2e 20 54 68 65 20 72 6f 77 rowid"]. The row
d130: 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 id is always ava
d140: 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 ilable.** as an
d150: 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d undeclared colum
d160: 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f n named ROWID, O
d170: 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 ID, or _ROWID_ a
d180: 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a s long as those.
d190: 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 ** names are not
d1a0: 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 also used by ex
d1b0: 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 plicitly declare
d1c0: 64 20 63 6f 6c 75 6d 6e 73 2e 20 49 66 0a 2a 2a d columns. If.**
d1d0: 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 the table has a
d1e0: 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 column of type
d1f0: 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 [INTEGER PRIMARY
d200: 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 KEY] then that
d210: 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f column.** is ano
d220: 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 ther alias for t
d230: 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 he rowid..**.**
d240: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 This routine ret
d250: 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d urns the [rowid]
d260: 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 of the most rec
d270: 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 ent.** successfu
d280: 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 l [INSERT] into
d290: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f the database fro
d2a0: 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 m the [database
d2b0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 connection].** i
d2c0: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 n the first argu
d2d0: 6d 65 6e 74 2e 20 20 49 66 20 6e 6f 20 73 75 63 ment. If no suc
d2e0: 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d cessful [INSERT]
d2f0: 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f s.** have ever o
d300: 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20 ccurred on that
d310: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
d320: 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 ion, zero is ret
d330: 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 urned..**.** If
d340: 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 an [INSERT] occu
d350: 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 rs within a trig
d360: 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20 5b 72 ger, then the [r
d370: 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 owid] of the ins
d380: 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 69 73 20 erted.** row is
d390: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 returned by this
d3a0: 20 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 routine as long
d3b0: 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 as the trigger
d3c0: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 is running..** B
d3d0: 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 ut once the trig
d3e0: 67 65 72 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 ger terminates,
d3f0: 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
d400: 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 ed by this routi
d410: 6e 65 0a 2a 2a 20 72 65 76 65 72 74 73 20 74 6f ne.** reverts to
d420: 20 74 68 65 20 6c 61 73 74 20 76 61 6c 75 65 20 the last value
d430: 69 6e 73 65 72 74 65 64 20 62 65 66 6f 72 65 20 inserted before
d440: 74 68 65 20 74 72 69 67 67 65 72 20 66 69 72 65 the trigger fire
d450: 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 49 4e 53 d..**.** An [INS
d460: 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 ERT] that fails
d470: 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 due to a constra
d480: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 int violation is
d490: 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 not a.** succes
d4a0: 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e sful [INSERT] an
d4b0: 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 d does not chang
d4c0: 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 e the value retu
d4d0: 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 rned by this.**
d4e0: 72 6f 75 74 69 6e 65 2e 20 20 54 68 75 73 20 49 routine. Thus I
d4f0: 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 NSERT OR FAIL, I
d500: 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c NSERT OR IGNORE,
d510: 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 INSERT OR ROLLB
d520: 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 ACK,.** and INSE
d530: 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 RT OR ABORT make
d540: 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 no changes to t
d550: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
d560: 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 of this.** routi
d570: 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e ne when their in
d580: 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 sertion fails.
d590: 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 When INSERT OR R
d5a0: 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e EPLACE.** encoun
d5b0: 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e ters a constrain
d5c0: 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 t violation, it
d5d0: 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 does not fail.
d5e0: 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f The.** INSERT co
d5f0: 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c ntinues to compl
d600: 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 etion after dele
d610: 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 ting rows that c
d620: 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e aused.** the con
d630: 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 straint problem
d640: 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 so INSERT OR REP
d650: 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 LACE will always
d660: 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 change.** the r
d670: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 eturn value of t
d680: 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a his interface..*
d690: 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 *.** For the pur
d6a0: 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f poses of this ro
d6b0: 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 utine, an [INSER
d6c0: 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 T] is considered
d6d0: 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 to.** be succes
d6e0: 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 sful even if it
d6f0: 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 is subsequently
d700: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a rolled back..**.
d710: 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
d720: 0a 2a 2a 20 5b 48 31 32 32 32 31 5d 20 5b 48 31 .** [H12221] [H1
d730: 32 32 32 33 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 61 2223].**.** If a
d740: 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 separate thread
d750: 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 performs a new
d760: 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 [INSERT] on the
d770: 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 same.** database
d780: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c connection whil
d790: 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c e the [sqlite3_l
d7a0: 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 ast_insert_rowid
d7b0: 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ()].** function
d7c0: 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 is running and t
d7d0: 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 hus changes the
d7e0: 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 last insert [row
d7f0: 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 id],.** then the
d800: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
d810: 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 by [sqlite3_last
d820: 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d _insert_rowid()]
d830: 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 is.** unpredict
d840: 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e able and might n
d850: 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 ot equal either
d860: 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e the old or the n
d870: 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 ew.** last inser
d880: 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 t [rowid]..*/.sq
d890: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 lite3_int64 sqli
d8a0: 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f te3_last_insert_
d8b0: 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b rowid(sqlite3*);
d8c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
d8d0: 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 : Count The Numb
d8e0: 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 er Of Rows Modif
d8f0: 69 65 64 20 7b 48 31 32 32 34 30 7d 20 3c 53 31 ied {H12240} <S1
d900: 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 0600>.**.** This
d910: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e function return
d920: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
d930: 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 database rows th
d940: 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a at were changed.
d950: 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f ** or inserted o
d960: 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 r deleted by the
d970: 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 most recently c
d980: 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 ompleted SQL sta
d990: 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 tement.** on the
d9a0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
d9b0: 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 ction] specified
d9c0: 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 by the first pa
d9d0: 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 4f 6e 6c 79 rameter..** Only
d9e0: 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 changes that ar
d9f0: 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 e directly speci
da00: 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53 fied by the [INS
da10: 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a ERT], [UPDATE],.
da20: 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 ** or [DELETE] s
da30: 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 tatement are cou
da40: 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 nted. Auxiliary
da50: 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 changes caused
da60: 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 61 by.** triggers a
da70: 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 re not counted.
da80: 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 Use the [sqlite3
da90: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 _total_changes()
daa0: 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 6f ] function.** to
dab0: 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 find the total
dac0: 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 number of change
dad0: 73 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e s including chan
dae0: 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72 ges caused by tr
daf0: 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 43 68 iggers..**.** Ch
db00: 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 anges to a view
db10: 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74 that are simulat
db20: 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 ed by an [INSTEA
db30: 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a D OF trigger].**
db40: 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 are not counted
db50: 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 . Only real tab
db60: 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 le changes are c
db70: 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 20 ounted..**.** A
db80: 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73 20 "row change" is
db90: 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69 a change to a si
dba0: 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69 ngle row of a si
dbb0: 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 ngle table.** ca
dbc0: 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52 used by an INSER
dbd0: 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 T, DELETE, or UP
dbe0: 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 DATE statement.
dbf0: 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 Rows that.** ar
dc00: 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 69 64 e changed as sid
dc10: 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b 52 45 e effects of [RE
dc20: 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e PLACE] constrain
dc30: 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a t resolution,.**
dc40: 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 rollback, ABORT
dc50: 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 processing, [DR
dc60: 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 OP TABLE], or by
dc70: 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 any other.** me
dc80: 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 chanisms do not
dc90: 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74 20 count as direct
dca0: 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a row changes..**.
dcb0: 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f ** A "trigger co
dcc0: 6e 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 ntext" is a scop
dcd0: 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 e of execution t
dce0: 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a hat begins and.*
dcf0: 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 * ends with the
dd00: 73 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45 script of a [CRE
dd10: 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 ATE TRIGGER | tr
dd20: 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 igger]. .** Most
dd30: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
dd40: 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 are.** evaluated
dd50: 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 outside of any
dd60: 74 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 trigger. This i
dd70: 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c s the "top level
dd80: 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e ".** trigger con
dd90: 74 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 text. If a trig
dda0: 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 ger fires from t
ddb0: 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a he top level, a.
ddc0: 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 ** new trigger c
ddd0: 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 ontext is entere
dde0: 64 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 d for the durati
ddf0: 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a on of that one.*
de00: 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 * trigger. Subt
de10: 72 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73 riggers create s
de20: 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 ubcontexts for t
de30: 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a heir duration..*
de40: 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 5b 73 71 *.** Calling [sq
de50: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 lite3_exec()] or
de60: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
de70: 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f ] recursively do
de80: 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 es.** not create
de90: 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 a new trigger c
dea0: 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 ontext..**.** Th
deb0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 is function retu
dec0: 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
ded0: 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 f direct row cha
dee0: 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d nges in the.** m
def0: 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 ost recent INSER
df00: 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 T, UPDATE, or DE
df10: 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 LETE statement w
df20: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a ithin the same.*
df30: 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 * trigger contex
df40: 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 75 73 2c 20 77 t..**.** Thus, w
df50: 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 hen called from
df60: 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 the top level, t
df70: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 his function ret
df80: 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 urns the.** numb
df90: 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e er of changes in
dfa0: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
dfb0: 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c INSERT, UPDATE,
dfc0: 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 or DELETE.** th
dfd0: 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 at also occurred
dfe0: 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 at the top leve
dff0: 6c 2e 20 20 57 69 74 68 69 6e 20 74 68 65 20 62 l. Within the b
e000: 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 ody of a trigger
e010: 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 ,.** the sqlite3
e020: 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 _changes() inter
e030: 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c face can be call
e040: 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e ed to find the n
e050: 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e umber of.** chan
e060: 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 ges in the most
e070: 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 recently complet
e080: 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 ed INSERT, UPDAT
e090: 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 E, or DELETE.**
e0a0: 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e statement within
e0b0: 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 the body of the
e0c0: 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a same trigger..*
e0d0: 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e * However, the n
e0e0: 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 umber returned d
e0f0: 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 oes not include
e100: 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 changes.** cause
e110: 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73 d by subtriggers
e120: 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 since those hav
e130: 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 e their own cont
e140: 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ext..**.** See a
e150: 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 lso the [sqlite3
e160: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 _total_changes()
e170: 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 20 ] interface and
e180: 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 the.** [count_ch
e190: 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2e 0a 2a anges pragma]..*
e1a0: 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
e1b0: 73 3a 0a 2a 2a 20 5b 48 31 32 32 34 31 5d 20 5b s:.** [H12241] [
e1c0: 48 31 32 32 34 33 5d 0a 2a 2a 0a 2a 2a 20 49 66 H12243].**.** If
e1d0: 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 a separate thre
e1e0: 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 ad makes changes
e1f0: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 on the same dat
e200: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
e210: 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 .** while [sqlit
e220: 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 e3_changes()] is
e230: 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 running then th
e240: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
e250: 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 .** is unpredict
e260: 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 able and not mea
e270: 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 ningful..*/.int
e280: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 sqlite3_changes(
e290: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a sqlite3*);../*.*
e2a0: 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 * CAPI3REF: Tota
e2b0: 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 l Number Of Rows
e2c0: 20 4d 6f 64 69 66 69 65 64 20 7b 48 31 32 32 36 Modified {H1226
e2d0: 30 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 0} <S10600>.**.*
e2e0: 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 * This function
e2f0: 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
e300: 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 er of row change
e310: 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53 s caused by [INS
e320: 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 ERT],.** [UPDATE
e330: 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 ] or [DELETE] st
e340: 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 atements since t
e350: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
e360: 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 nection] was ope
e370: 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 63 6f 75 6e ned..** The coun
e380: 74 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 t includes all c
e390: 68 61 6e 67 65 73 20 66 72 6f 6d 20 61 6c 6c 20 hanges from all
e3a0: 0a 2a 2a 20 5b 43 52 45 41 54 45 20 54 52 49 47 .** [CREATE TRIG
e3b0: 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63 GER | trigger] c
e3c0: 6f 6e 74 65 78 74 73 2e 20 20 48 6f 77 65 76 65 ontexts. Howeve
e3d0: 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 r,.** the count
e3e0: 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 does not include
e3f0: 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f changes used to
e400: 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c implement [REPL
e410: 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 ACE] constraints
e420: 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b ,.** do rollback
e430: 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65 s or ABORT proce
e440: 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 ssing, or [DROP
e450: 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e TABLE] processin
e460: 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 g. The.** count
e470: 20 64 6f 65 73 20 6e 6f 74 20 72 6f 77 73 20 6f does not rows o
e480: 66 20 76 69 65 77 73 20 74 68 61 74 20 66 69 72 f views that fir
e490: 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 e an [INSTEAD OF
e4a0: 20 74 72 69 67 67 65 72 5d 2c 20 74 68 6f 75 67 trigger], thoug
e4b0: 68 20 69 66 0a 2a 2a 20 74 68 65 20 49 4e 53 54 h if.** the INST
e4c0: 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d EAD OF trigger m
e4d0: 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20 akes changes of
e4e0: 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 its own, those c
e4f0: 68 61 6e 67 65 73 20 61 72 65 0a 2a 2a 20 63 6f hanges are.** co
e500: 75 6e 74 65 64 2e 0a 2a 2a 20 54 68 65 20 63 68 unted..** The ch
e510: 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 anges are counte
e520: 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 d as soon as the
e530: 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 statement that
e540: 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 0a 2a 2a makes them is.**
e550: 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e completed (when
e560: 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 the statement h
e570: 61 6e 64 6c 65 20 69 73 20 70 61 73 73 65 64 20 andle is passed
e580: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 to [sqlite3_rese
e590: 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 t()] or.** [sqli
e5a0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 te3_finalize()])
e5b0: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
e5c0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 the [sqlite3_ch
e5d0: 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 anges()] interfa
e5e0: 63 65 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 63 ce and the.** [c
e5f0: 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 ount_changes pra
e600: 67 6d 61 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 gma]..**.** Requ
e610: 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
e620: 32 32 36 31 5d 20 5b 48 31 32 32 36 33 5d 0a 2a 2261] [H12263].*
e630: 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 *.** If a separa
e640: 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 te thread makes
e650: 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 changes on the s
e660: 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e ame database con
e670: 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 nection.** while
e680: 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f [sqlite3_total_
e690: 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 changes()] is ru
e6a0: 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 nning then the v
e6b0: 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 alue.** returned
e6c0: 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c is unpredictabl
e6d0: 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e e and not meanin
e6e0: 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c gful..*/.int sql
e6f0: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
e700: 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f es(sqlite3*);../
e710: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 *.** CAPI3REF: I
e720: 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d nterrupt A Long-
e730: 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 20 7b 48 Running Query {H
e740: 31 32 32 37 30 7d 20 3c 53 33 30 35 30 30 3e 0a 12270} <S30500>.
e750: 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 **.** This funct
e760: 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 ion causes any p
e770: 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 ending database
e780: 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f operation to abo
e790: 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e rt and.** return
e7a0: 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 at its earliest
e7b0: 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 opportunity. Th
e7c0: 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 is routine is ty
e7d0: 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 pically.** calle
e7e0: 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f d in response to
e7f0: 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 a user action s
e800: 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 uch as pressing
e810: 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 "Cancel".** or C
e820: 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 trl-C where the
e830: 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e user wants a lon
e840: 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f g query operatio
e850: 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d n to halt.** imm
e860: 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 ediately..**.**
e870: 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 It is safe to ca
e880: 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 ll this routine
e890: 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 from a thread di
e8a0: 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 fferent from the
e8b0: 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 .** thread that
e8c0: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e is currently run
e8d0: 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 ning the databas
e8e0: 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 e operation. Bu
e8f0: 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 t it.** is not s
e900: 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 afe to call this
e910: 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 routine with a
e920: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
e930: 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 tion] that.** is
e940: 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 closed or might
e950: 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 close before sq
e960: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
e970: 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a ) returns..**.**
e980: 20 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 If an SQL opera
e990: 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 tion is very nea
e9a0: 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 rly finished at
e9b0: 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a the time when.**
e9c0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
e9d0: 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 pt() is called,
e9e0: 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f then it might no
e9f0: 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 t have an opport
ea00: 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 unity.** to be i
ea10: 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d nterrupted and m
ea20: 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f ight continue to
ea30: 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a completion..**.
ea40: 2a 2a 20 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 ** An SQL operat
ea50: 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 ion that is inte
ea60: 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 rrupted will ret
ea70: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 urn [SQLITE_INTE
ea80: 52 52 55 50 54 5d 2e 0a 2a 2a 20 49 66 20 74 68 RRUPT]..** If th
ea90: 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 e interrupted SQ
eaa0: 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 L operation is a
eab0: 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 n INSERT, UPDATE
eac0: 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 , or DELETE.** t
ead0: 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e hat is inside an
eae0: 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 explicit transa
eaf0: 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 ction, then the
eb00: 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 entire transacti
eb10: 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f on.** will be ro
eb20: 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 lled back automa
eb30: 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 tically..**.** T
eb40: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 he sqlite3_inter
eb50: 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 rupt(D) call is
eb60: 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 in effect until
eb70: 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 all currently ru
eb80: 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 nning.** SQL sta
eb90: 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 tements on [data
eba0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
ebb0: 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 41 6e D complete. An
ebc0: 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d y new SQL statem
ebd0: 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 ents.** that are
ebe0: 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 started after t
ebf0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 he sqlite3_inter
ec00: 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 rupt() call and
ec10: 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 before the .** r
ec20: 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 unning statement
ec30: 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 s reaches zero a
ec40: 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 re interrupted a
ec50: 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 s if they had be
ec60: 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 en.** running pr
ec70: 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ior to the sqlit
ec80: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 e3_interrupt() c
ec90: 61 6c 6c 2e 20 20 4e 65 77 20 53 51 4c 20 73 74 all. New SQL st
eca0: 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 atements.** that
ecb0: 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 are started aft
ecc0: 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 er the running s
ecd0: 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 tatement count r
ece0: 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a eaches zero are.
ecf0: 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 ** not effected
ed00: 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 by the sqlite3_i
ed10: 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 41 nterrupt()..** A
ed20: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
ed30: 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 _interrupt(D) th
ed40: 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 at occurs when t
ed50: 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e here are no runn
ed60: 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 ing.** SQL state
ed70: 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 ments is a no-op
ed80: 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 and has no effe
ed90: 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d ct on SQL statem
eda0: 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 ents.** that are
edb0: 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 started after t
edc0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 he sqlite3_inter
edd0: 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 rupt() call retu
ede0: 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 rns..**.** Requi
edf0: 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 rements:.** [H12
ee00: 32 37 31 5d 20 5b 48 31 32 32 37 32 5d 0a 2a 2a 271] [H12272].**
ee10: 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 .** If the datab
ee20: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 ase connection c
ee30: 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c loses while [sql
ee40: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
ee50: 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 ].** is running
ee60: 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 then bad things
ee70: 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 will likely happ
ee80: 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 en..*/.void sqli
ee90: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 te3_interrupt(sq
eea0: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 lite3*);../*.**
eeb0: 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d CAPI3REF: Determ
eec0: 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 ine If An SQL St
eed0: 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c atement Is Compl
eee0: 65 74 65 20 7b 48 31 30 35 31 30 7d 20 3c 53 37 ete {H10510} <S7
eef0: 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 0200>.**.** Thes
ef00: 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 e routines are u
ef10: 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d seful during com
ef20: 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 mand-line input
ef30: 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 to determine if
ef40: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 the.** currently
ef50: 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 entered text se
ef60: 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f ems to form a co
ef70: 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 mplete SQL state
ef80: 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 ment or.** if ad
ef90: 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 ditional input i
efa0: 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 s needed before
efb0: 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 sending the text
efc0: 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 into.** SQLite
efd0: 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 54 68 for parsing. Th
efe0: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 ese routines ret
eff0: 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 urn 1 if the inp
f000: 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 ut string.** app
f010: 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d ears to be a com
f020: 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d plete SQL statem
f030: 65 6e 74 2e 20 20 41 20 73 74 61 74 65 6d 65 6e ent. A statemen
f040: 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 t is judged to b
f050: 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 e.** complete if
f060: 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 it ends with a
f070: 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 semicolon token
f080: 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 and is not a pre
f090: 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c fix of a.** well
f0a0: 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 -formed CREATE T
f0b0: 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 RIGGER statement
f0c0: 2e 20 20 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 . Semicolons th
f0d0: 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 at are embedded
f0e0: 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 within.** string
f0f0: 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f literals or quo
f100: 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e ted identifier n
f110: 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 ames or comments
f120: 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 are not.** inde
f130: 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 pendent tokens (
f140: 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 they are part of
f150: 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 the token in wh
f160: 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 ich they are.**
f170: 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 embedded) and th
f180: 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 us do not count
f190: 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 as a statement t
f1a0: 65 72 6d 69 6e 61 74 6f 72 2e 20 20 57 68 69 74 erminator. Whit
f1b0: 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f espace.** and co
f1c0: 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c mments that foll
f1d0: 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d ow the final sem
f1e0: 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 icolon are ignor
f1f0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ed..**.** These
f200: 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
f210: 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 0 if the stateme
f220: 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 nt is incomplete
f230: 2e 20 20 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 . If a.** memor
f240: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 y allocation fai
f250: 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f ls, then SQLITE_
f260: 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 NOMEM is returne
f270: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 d..**.** These r
f280: 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 outines do not p
f290: 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 arse the SQL sta
f2a0: 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 tements thus.**
f2b0: 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 will not detect
f2c0: 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e syntactically in
f2d0: 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a correct SQL..**.
f2e0: 2a 2a 20 49 66 20 53 51 4c 69 74 65 20 68 61 73 ** If SQLite has
f2f0: 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 not been initia
f300: 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c lized using [sql
f310: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
f320: 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 )] prior .** to
f330: 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 invoking sqlite3
f340: 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 _complete16() th
f350: 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 en sqlite3_initi
f360: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b alize() is invok
f370: 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 ed.** automatica
f380: 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 lly by sqlite3_c
f390: 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 omplete16(). If
f3a0: 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 that initializa
f3b0: 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 tion fails,.** t
f3c0: 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 hen the return v
f3d0: 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 alue from sqlite
f3e0: 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 3_complete16() w
f3f0: 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a ill be non-zero.
f400: 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 ** regardless of
f410: 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
f420: 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 the input SQL is
f430: 20 63 6f 6d 70 6c 65 74 65 2e 0a 2a 2a 0a 2a 2a complete..**.**
f440: 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b Requirements: [
f450: 48 31 30 35 31 31 5d 20 5b 48 31 30 35 31 32 5d H10511] [H10512]
f460: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 .**.** The input
f470: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d to [sqlite3_com
f480: 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 plete()] must be
f490: 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 a zero-terminat
f4a0: 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 ed.** UTF-8 stri
f4b0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e ng..**.** The in
f4c0: 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f put to [sqlite3_
f4d0: 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 complete16()] mu
f4e0: 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 st be a zero-ter
f4f0: 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 minated.** UTF-1
f500: 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 6 string in nati
f510: 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a ve byte order..*
f520: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f /.int sqlite3_co
f530: 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 mplete(const cha
f540: 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c r *sql);.int sql
f550: 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 ite3_complete16(
f560: 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 const void *sql)
f570: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
f580: 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61 F: Register A Ca
f590: 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 llback To Handle
f5a0: 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 SQLITE_BUSY Err
f5b0: 6f 72 73 20 7b 48 31 32 33 31 30 7d 20 3c 53 34 ors {H12310} <S4
f5c0: 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 0400>.**.** This
f5d0: 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 routine sets a
f5e0: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
f5f0: 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 n that might be
f600: 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 invoked whenever
f610: 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 .** an attempt i
f620: 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 s made to open a
f630: 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 database table
f640: 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 that another thr
f650: 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 ead.** or proces
f660: 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a s has locked..**
f670: 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79 20 .** If the busy
f680: 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c callback is NULL
f690: 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 , then [SQLITE_B
f6a0: 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f USY] or [SQLITE_
f6b0: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a IOERR_BLOCKED].*
f6c0: 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d * is returned im
f6d0: 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 mediately upon e
f6e0: 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 ncountering the
f6f0: 6c 6f 63 6b 2e 20 49 66 20 74 68 65 20 62 75 73 lock. If the bus
f700: 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 y callback.** is
f710: 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 not NULL, then
f720: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c the callback wil
f730: 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 l be invoked wit
f740: 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e h two arguments.
f750: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 .**.** The first
f760: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
f770: 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f handler is a co
f780: 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 py of the void*
f790: 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a pointer which.**
f7a0: 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72 is the third ar
f7b0: 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 gument to sqlite
f7c0: 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 3_busy_handler()
f7d0: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 . The second ar
f7e0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 gument to.** the
f7f0: 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 handler callbac
f800: 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 k is the number
f810: 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 of times that th
f820: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 e busy handler h
f830: 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b as.** been invok
f840: 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b ed for this lock
f850: 69 6e 67 20 65 76 65 6e 74 2e 20 20 49 66 20 74 ing event. If t
f860: 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 he.** busy callb
f870: 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 ack returns 0, t
f880: 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 hen no additiona
f890: 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d l attempts are m
f8a0: 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 ade to.** access
f8b0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e the database an
f8c0: 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 d [SQLITE_BUSY]
f8d0: 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 or [SQLITE_IOERR
f8e0: 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 _BLOCKED] is ret
f8f0: 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 urned..** If the
f900: 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
f910: 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e s non-zero, then
f920: 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 another attempt
f930: 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f .** is made to o
f940: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 pen the database
f950: 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 for reading and
f960: 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 the cycle repea
f970: 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 ts..**.** The pr
f980: 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 esence of a busy
f990: 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f handler does no
f9a0: 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 t guarantee that
f9b0: 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f it will be invo
f9c0: 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 ked.** when ther
f9d0: 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e e is lock conten
f9e0: 74 69 6f 6e 2e 20 49 66 20 53 51 4c 69 74 65 20 tion. If SQLite
f9f0: 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 determines that
fa00: 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 invoking the bus
fa10: 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 y.** handler cou
fa20: 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 ld result in a d
fa30: 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c eadlock, it will
fa40: 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 go ahead and re
fa50: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 turn [SQLITE_BUS
fa60: 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 Y].** or [SQLITE
fa70: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 _IOERR_BLOCKED]
fa80: 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b instead of invok
fa90: 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e ing the busy han
faa0: 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 dler..** Conside
fab0: 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 r a scenario whe
fac0: 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 re one process i
fad0: 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 s holding a read
fae0: 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 lock that.** it
faf0: 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 is trying to pr
fb00: 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 omote to a reser
fb10: 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 ved lock and.**
fb20: 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 a second process
fb30: 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 is holding a re
fb40: 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 served lock that
fb50: 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a it is trying.**
fb60: 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 to promote to a
fb70: 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b n exclusive lock
fb80: 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f . The first pro
fb90: 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 cess cannot proc
fba0: 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 eed.** because i
fbb0: 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 t is blocked by
fbc0: 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 the second and t
fbd0: 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 he second proces
fbe0: 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 s cannot.** proc
fbf0: 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 eed because it i
fc00: 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 s blocked by the
fc10: 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 first. If both
fc20: 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e processes.** in
fc30: 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 voke the busy ha
fc40: 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 ndlers, neither
fc50: 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 will make any pr
fc60: 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f ogress. Therefo
fc70: 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 re,.** SQLite re
fc80: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 turns [SQLITE_BU
fc90: 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 SY] for the firs
fca0: 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e t process, hopin
fcb0: 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 g that this.** w
fcc0: 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 ill induce the f
fcd0: 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 irst process to
fce0: 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 release its read
fcf0: 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a lock and allow.
fd00: 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 ** the second pr
fd10: 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 ocess to proceed
fd20: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 ..**.** The defa
fd30: 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 ult busy callbac
fd40: 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a k is NULL..**.**
fd50: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 The [SQLITE_BUS
fd60: 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 Y] error is conv
fd70: 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 erted to [SQLITE
fd80: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a _IOERR_BLOCKED].
fd90: 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 ** when SQLite i
fda0: 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 s in the middle
fdb0: 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 of a large trans
fdc0: 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c action where all
fdd0: 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 the.** changes
fde0: 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 will not fit int
fdf0: 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 o the in-memory
fe00: 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 cache. SQLite w
fe10: 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 ill.** already h
fe20: 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c old a RESERVED l
fe30: 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 ock on the datab
fe40: 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 ase file, but it
fe50: 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f needs.** to pro
fe60: 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 mote this lock t
fe70: 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 o EXCLUSIVE so t
fe80: 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c hat it can spill
fe90: 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 cache.** pages
fea0: 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 into the databas
feb0: 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 e file without h
fec0: 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e arm to concurren
fed0: 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 49 t.** readers. I
fee0: 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 f it is unable t
fef0: 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f o promote the lo
ff00: 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d ck, then the in-
ff10: 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 memory.** cache
ff20: 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 will be left in
ff30: 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 an inconsistent
ff40: 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 state and so the
ff50: 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 error.** code i
ff60: 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 s promoted from
ff70: 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 the relatively b
ff80: 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 enign [SQLITE_BU
ff90: 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f SY] to.** the mo
ffa0: 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 re severe [SQLIT
ffb0: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d E_IOERR_BLOCKED]
ffc0: 2e 20 20 54 68 69 73 20 65 72 72 6f 72 20 63 6f . This error co
ffd0: 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 de promotion.**
ffe0: 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 forces an automa
fff0: 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 tic rollback of
10000 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 the changes. Se
10010 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 e the.** <a href
10020 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f ="/cvstrac/wiki?
10030 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c p=CorruptionFoll
10040 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e owingBusyError">
10050 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f .** CorruptionFo
10060 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 llowingBusyError
10070 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 </a> wiki page f
10080 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 or a discussion
10090 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 of why.** this i
100a0 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a s important..**.
100b0 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c ** There can onl
100c0 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 y be a single bu
100d0 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e sy handler defin
100e0 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b ed for each.** [
100f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
10100 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 ion]. Setting a
10110 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 new busy handle
10120 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 r clears any.**
10130 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 previously set h
10140 61 6e 64 6c 65 72 2e 20 20 4e 6f 74 65 20 74 68 andler. Note th
10150 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 at calling [sqli
10160 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 te3_busy_timeout
10170 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f ()].** will also
10180 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 set or clear th
10190 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a e busy handler..
101a0 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 **.** The busy c
101b0 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e allback should n
101c0 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 ot take any acti
101d0 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 ons which modify
101e0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 the.** database
101f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 connection that
10200 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 invoked the bus
10210 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 y handler. Any
10220 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 such actions.**
10230 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 result in undefi
10240 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a ned behavior..**
10250 20 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 .** Requirement
10260 73 3a 0a 2a 2a 20 5b 48 31 32 33 31 31 5d 20 5b s:.** [H12311] [
10270 48 31 32 33 31 32 5d 20 5b 48 31 32 33 31 34 5d H12312] [H12314]
10280 20 5b 48 31 32 33 31 36 5d 20 5b 48 31 32 33 31 [H12316] [H1231
10290 38 5d 0a 2a 2a 0a 2a 2a 20 41 20 62 75 73 79 20 8].**.** A busy
102a0 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 handler must not
102b0 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 close the datab
102c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase connection.*
102d0 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 * or [prepared s
102e0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 tatement] that i
102f0 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 nvoked the busy
10300 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 handler..*/.int
10310 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e sqlite3_busy_han
10320 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 dler(sqlite3*, i
10330 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 nt(*)(void*,int)
10340 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a , void*);../*.**
10350 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 CAPI3REF: Set A
10360 20 42 75 73 79 20 54 69 6d 65 6f 75 74 20 7b 48 Busy Timeout {H
10370 31 32 33 34 30 7d 20 3c 53 34 30 34 31 30 3e 0a 12340} <S40410>.
10380 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
10390 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 ne sets a [sqlit
103a0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 e3_busy_handler
103b0 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 | busy handler]
103c0 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 that sleeps.** f
103d0 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61 or a specified a
103e0 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 mount of time wh
103f0 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f en a table is lo
10400 63 6b 65 64 2e 20 20 54 68 65 20 68 61 6e 64 6c cked. The handl
10410 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 er.** will sleep
10420 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 multiple times
10430 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 until at least "
10440 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 ms" milliseconds
10450 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 of sleeping.**
10460 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 have accumulated
10470 2e 20 7b 48 31 32 33 34 33 7d 20 41 66 74 65 72 . {H12343} After
10480 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e "ms" millisecon
10490 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a ds of sleeping,.
104a0 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 ** the handler r
104b0 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 eturns 0 which c
104c0 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 auses [sqlite3_s
104d0 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e tep()] to return
104e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 .** [SQLITE_BUSY
104f0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 ] or [SQLITE_IOE
10500 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a RR_BLOCKED]..**.
10510 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 ** Calling this
10520 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 routine with an
10530 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 argument less th
10540 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a an or equal to z
10550 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 ero.** turns off
10560 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 all busy handle
10570 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 rs..**.** There
10580 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 can only be a si
10590 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 ngle busy handle
105a0 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c r for a particul
105b0 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 ar.** [database
105c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 connection] any
105d0 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 any given moment
105e0 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 . If another bu
105f0 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 sy handler.** wa
10600 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e s defined (usin
10610 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f g [sqlite3_busy_
10620 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f handler()]) prio
10630 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 r to calling.**
10640 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 this routine, th
10650 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 at other busy ha
10660 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 ndler is cleared
10670 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
10680 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 33 34 31 ents:.** [H12341
10690 5d 20 5b 48 31 32 33 34 33 5d 20 5b 48 31 32 33 ] [H12343] [H123
106a0 34 34 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 44].*/.int sqlit
106b0 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 e3_busy_timeout(
106c0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 sqlite3*, int ms
106d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
106e0 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 EF: Convenience
106f0 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e Routines For Run
10700 6e 69 6e 67 20 51 75 65 72 69 65 73 20 7b 48 31 ning Queries {H1
10710 32 33 37 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2370} <S10000>.*
10720 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a *.** Definition:
10730 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 A <b>result tab
10740 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 le</b> is memory
10750 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 data structure
10760 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a created by the.*
10770 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 * [sqlite3_get_t
10780 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 able()] interfac
10790 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 e. A result tab
107a0 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a le records the.*
107b0 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 * complete query
107c0 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e results from on
107d0 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 e or more querie
107e0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 s..**.** The tab
107f0 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 le conceptually
10800 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 has a number of
10810 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 rows and columns
10820 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 . But.** these
10830 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 numbers are not
10840 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 part of the resu
10850 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e lt table itself.
10860 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 These.** numbe
10870 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 rs are obtained
10880 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 separately. Let
10890 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 N be the number
108a0 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 of rows.** and
108b0 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 M be the number
108c0 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a of columns..**.*
108d0 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 * A result table
108e0 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 is an array of
108f0 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f pointers to zero
10900 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d -terminated UTF-
10910 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 8 strings..** Th
10920 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 ere are (N+1)*M
10930 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 elements in the
10940 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 array. The firs
10950 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 t M pointers poi
10960 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 nt.** to zero-te
10970 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 rminated strings
10980 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 that contain t
10990 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 he names of the
109a0 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 columns..** The
109b0 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 remaining entrie
109c0 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 s all point to q
109d0 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e uery results. N
109e0 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c ULL values resul
109f0 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 t.** in NULL poi
10a00 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 nters. All othe
10a10 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 r values are in
10a20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f their UTF-8 zero
10a30 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 -terminated.** s
10a40 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 tring representa
10a50 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 tion as returned
10a60 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c by [sqlite3_col
10a70 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a umn_text()]..**.
10a80 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c ** A result tabl
10a90 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 e might consist
10aa0 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d of one or more m
10ab0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
10ac0 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 s..** It is not
10ad0 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 safe to pass a r
10ae0 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 esult table dire
10af0 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 ctly to [sqlite3
10b00 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 _free()]..** A r
10b10 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 esult table shou
10b20 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 ld be deallocate
10b30 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
10b40 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a _free_table()]..
10b50 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61 6d **.** As an exam
10b60 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c ple of the resul
10b70 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 t table format,
10b80 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 suppose a query
10b90 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 result.** is as
10ba0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c follows:.**.** <
10bb0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
10bc0 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 .** Name
10bd0 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 | Age.**
10be0 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d ---------
10bf0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a --------------.*
10c00 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 * Alice
10c10 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 | 43.**
10c20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 Bob
10c30 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 | 28.** C
10c40 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a indy | 21.
10c50 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
10c60 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 quote>.**.** The
10c70 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d re are two colum
10c80 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 n (M==2) and thr
10c90 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 ee rows (N==3).
10ca0 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 Thus the.** res
10cb0 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 ult table has 8
10cc0 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 entries. Suppos
10cd0 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 e the result tab
10ce0 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 le is stored.**
10cf0 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 in an array name
10d00 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 s azResult. The
10d10 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 n azResult holds
10d20 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a this content:.*
10d30 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
10d40 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 ><pre>.**
10d50 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d azResult[0]
10d60 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 = "Name";.**
10d70 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
10d80 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 1;1] = "Age";.**
10d90 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
10da0 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 [2] = "Alice
10db0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
10dc0 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 esult[3] = "
10dd0 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 43";.** a
10de0 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d zResult[4] =
10df0 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 "Bob";.**
10e00 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 azResult[5
10e10 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 ] = "28";.**
10e20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
10e30 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a ;6] = "Cindy";.*
10e40 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
10e50 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b t[7] = "21";
10e60 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
10e70 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 kquote>.**.** Th
10e80 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 e sqlite3_get_ta
10e90 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 ble() function e
10ea0 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 valuates one or
10eb0 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f more.** semicolo
10ec0 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 n-separated SQL
10ed0 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 statements in th
10ee0 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 e zero-terminate
10ef0 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e d UTF-8.** strin
10f00 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 g of its 2nd par
10f10 61 6d 65 74 65 72 2e 20 20 49 74 20 72 65 74 75 ameter. It retu
10f20 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 rns a result tab
10f30 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 le to the.** poi
10f40 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 nter given in it
10f50 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e s 3rd parameter.
10f60 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 .**.** After the
10f70 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f calling functio
10f80 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 n has finished u
10f90 73 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2c sing the result,
10fa0 20 69 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 70 61 it should.** pa
10fb0 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 ss the pointer t
10fc0 6f 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 o the result tab
10fd0 6c 65 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 le to sqlite3_fr
10fe0 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 ee_table() in or
10ff0 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 der to.** releas
11000 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 e the memory tha
11010 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 t was malloced.
11020 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 Because of the
11030 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 way the.** [sqli
11040 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 te3_malloc()] ha
11050 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c ppens within sql
11060 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
11070 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a , the calling.**
11080 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e function must n
11090 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b ot try to call [
110a0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 sqlite3_free()]
110b0 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a directly. Only.
110c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ** [sqlite3_free
110d0 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c _table()] is abl
110e0 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 e to release the
110f0 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 memory properly
11100 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a and safely..**.
11110 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 ** The sqlite3_g
11120 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 et_table() inter
11130 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e face is implemen
11140 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 ted as a wrapper
11150 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 around.** [sqli
11160 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 te3_exec()]. Th
11170 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 e sqlite3_get_ta
11180 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f ble() routine do
11190 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 es not have acce
111a0 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 ss.** to any int
111b0 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 ernal data struc
111c0 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e tures of SQLite.
111d0 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 It uses only t
111e0 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 he public.** int
111f0 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 erface defined h
11200 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 ere. As a conse
11210 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 quence, errors t
11220 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 hat occur in the
11230 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 .** wrapper laye
11240 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 r outside of the
11250 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 internal [sqlit
11260 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 e3_exec()] call
11270 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 are not.** refle
11280 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 cted in subseque
11290 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c nt calls to [sql
112a0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 ite3_errcode()]
112b0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d or [sqlite3_errm
112c0 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 sg()]..**.** Req
112d0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
112e0 31 32 33 37 31 5d 20 5b 48 31 32 33 37 33 5d 20 12371] [H12373]
112f0 5b 48 31 32 33 37 34 5d 20 5b 48 31 32 33 37 36 [H12374] [H12376
11300 5d 20 5b 48 31 32 33 37 39 5d 20 5b 48 31 32 33 ] [H12379] [H123
11310 38 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 82].*/.int sqlit
11320 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 e3_get_table(.
11330 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
11340 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e /* An open
11350 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 database */. c
11360 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c onst char *zSql,
11370 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 /* SQL to b
11380 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 e evaluated */.
11390 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 char ***pazResu
113a0 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 lt, /* Result
113b0 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a s of the query *
113c0 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 /. int *pnRow,
113d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d /* Num
113e0 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f ber of result ro
113f0 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 ws written here
11400 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 */. int *pnColu
11410 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 mn, /* Nu
11420 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 mber of result c
11430 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 olumns written h
11440 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a ere */. char **
11450 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f pzErrmsg /
11460 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 * Error msg writ
11470 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 ten here */.);.v
11480 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 oid sqlite3_free
11490 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 _table(char **re
114a0 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 sult);../*.** CA
114b0 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 PI3REF: Formatte
114c0 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e d String Printin
114d0 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 37 g Functions {H17
114e0 34 30 30 7d 20 3c 53 37 30 30 30 30 3e 3c 53 32 400} <S70000><S2
114f0 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 0000>.**.** Thes
11500 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 e routines are w
11510 6f 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 orkalikes of the
11520 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 "printf()" fami
11530 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a ly of functions.
11540 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e ** from the stan
11550 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a dard C library..
11560 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
11570 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 3_mprintf() and
11580 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 sqlite3_vmprintf
11590 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 () routines writ
115a0 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c e their.** resul
115b0 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f ts into memory o
115c0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
115d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e lite3_malloc()].
115e0 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 .** The strings
115f0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 returned by thes
11600 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 e two routines s
11610 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 hould be.** rele
11620 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 ased by [sqlite3
11630 5f 66 72 65 65 28 29 5d 2e 20 20 42 6f 74 68 20 _free()]. Both
11640 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
11650 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 a.** NULL pointe
11660 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 r if [sqlite3_ma
11670 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c lloc()] is unabl
11680 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e e to allocate en
11690 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 ough.** memory t
116a0 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c o hold the resul
116b0 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a ting string..**.
116c0 2a 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e ** In sqlite3_sn
116d0 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 printf() routine
116e0 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 is similar to "
116f0 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d snprintf()" from
11700 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 .** the standard
11710 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 C library. The
11720 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 result is writt
11730 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 en into the.** b
11740 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 uffer supplied a
11750 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 s the second par
11760 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a ameter whose siz
11770 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a e is given by.**
11780 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
11790 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 eter. Note that
117a0 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 the order of the
117b0 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 .** first two pa
117c0 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 rameters is reve
117d0 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e rsed from snprin
117e0 74 66 28 29 2e 20 20 54 68 69 73 20 69 73 20 61 tf(). This is a
117f0 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 n.** historical
11800 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 accident that ca
11810 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 nnot be fixed wi
11820 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a thout breaking.*
11830 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 * backwards comp
11840 61 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65 atibility. Note
11850 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 also that sqlit
11860 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a e3_snprintf().**
11870 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
11880 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 er to its buffer
11890 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 instead of the
118a0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 number of.** cha
118b0 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 racters actually
118c0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 written into th
118d0 65 20 62 75 66 66 65 72 2e 20 20 57 65 20 61 64 e buffer. We ad
118e0 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 mit that.** the
118f0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 number of charac
11900 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 ters written wou
11910 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 ld be a more use
11920 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 ful return.** va
11930 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f lue but we canno
11940 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 t change the imp
11950 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 lementation of s
11960 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
11970 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 ).** now without
11980 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 breaking compat
11990 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 ibility..**.** A
119a0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 s long as the bu
119b0 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 ffer size is gre
119c0 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 ater than zero,
119d0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
119e0 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 ().** guarantees
119f0 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 that the buffer
11a00 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d is always zero-
11a10 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 terminated. The
11a20 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 first.** parame
11a30 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 ter "n" is the t
11a40 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 otal size of the
11a50 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 buffer, includi
11a60 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 ng space for.**
11a70 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 the zero termina
11a80 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e tor. So the lon
11a90 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 gest string that
11aa0 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 can be complete
11ab0 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 ly.** written wi
11ac0 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 ll be n-1 charac
11ad0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ters..**.** Thes
11ae0 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 e routines all i
11af0 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 mplement some ad
11b00 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 ditional formatt
11b10 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 ing.** options t
11b20 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 hat are useful f
11b30 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 or constructing
11b40 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a SQL statements..
11b50 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 ** All of the us
11b60 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 ual printf() for
11b70 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 matting options
11b80 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 apply. In addit
11b90 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 ion, there.** is
11ba0 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c are "%q", "%Q",
11bb0 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e and "%z" option
11bc0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 s..**.** The %q
11bd0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b option works lik
11be0 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 e %s in that it
11bf0 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 substitutes a nu
11c00 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ll-terminated.**
11c10 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 string from the
11c20 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 argument list.
11c30 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 But %q also dou
11c40 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 bles every '\''
11c50 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 character..** %q
11c60 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 is designed for
11c70 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 use inside a st
11c80 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 ring literal. B
11c90 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 y doubling each
11ca0 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 '\''.** characte
11cb0 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61 r it escapes tha
11cc0 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 t character and
11cd0 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 allows it to be
11ce0 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a inserted into.**
11cf0 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a the string..**.
11d00 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 ** For example,
11d10 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e assume the strin
11d20 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 g variable zText
11d30 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 contains text a
11d40 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a s follows:.**.**
11d50 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
11d60 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 e>.** char *zTe
11d70 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 xt = "It's a hap
11d80 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 py day!";.** </p
11d90 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
11da0 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 .**.** One can u
11db0 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 se this text in
11dc0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 an SQL statement
11dd0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a as follows:.**.
11de0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
11df0 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a pre>.** char *z
11e00 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 SQL = sqlite3_mp
11e10 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e rintf("INSERT IN
11e20 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 TO table VALUES(
11e30 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a '%q')", zText);.
11e40 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 ** sqlite3_exec
11e50 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c (db, zSQL, 0, 0,
11e60 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 0);.** sqlite3
11e70 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 _free(zSQL);.**
11e80 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
11e90 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 te>.**.** Becaus
11ea0 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 e the %q format
11eb0 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 string is used,
11ec0 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 the '\'' charact
11ed0 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 er in zText.** i
11ee0 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 s escaped and th
11ef0 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 e SQL generated
11f00 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a is as follows:.*
11f10 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
11f20 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 ><pre>.** INSER
11f30 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 T INTO table1 VA
11f40 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61 LUES('It''s a ha
11f50 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f ppy day!').** </
11f60 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
11f70 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 >.**.** This is
11f80 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 correct. Had we
11f90 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 used %s instead
11fa0 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 of %q, the gene
11fb0 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 rated SQL.** wou
11fc0 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c ld have looked l
11fd0 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 ike this:.**.**
11fe0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
11ff0 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 >.** INSERT INT
12000 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 O table1 VALUES(
12010 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 'It's a happy da
12020 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c y!');.** </pre><
12030 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
12040 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 ** This second e
12050 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c xample is an SQL
12060 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 syntax error.
12070 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c As a general rul
12080 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 e you should.**
12090 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e always use %q in
120a0 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e stead of %s when
120b0 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 inserting text
120c0 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 into a string li
120d0 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 teral..**.** The
120e0 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 %Q option works
120f0 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 like %q except
12100 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e it also adds sin
12110 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e gle quotes aroun
12120 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 d.** the outside
12130 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 of the total st
12140 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 ring. Additiona
12150 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 lly, if the para
12160 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 meter in the.**
12170 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 argument list is
12180 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
12190 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 %Q substitutes
121a0 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 the text "NULL"
121b0 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 (without.** sing
121c0 6c 65 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c le quotes) in pl
121d0 61 63 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70 ace of the %Q op
121e0 74 69 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65 tion. So, for e
121f0 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c xample, one coul
12200 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c d say:.**.** <bl
12210 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
12220 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 * char *zSQL =
12230 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
12240 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 "INSERT INTO tab
12250 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 le VALUES(%Q)",
12260 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 zText);.** sqli
12270 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 te3_exec(db, zSQ
12280 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 L, 0, 0, 0);.**
12290 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 sqlite3_free(zS
122a0 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f QL);.** </pre></
122b0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
122c0 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 * The code above
122d0 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 will render a c
122e0 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 orrect SQL state
122f0 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c ment in the zSQL
12300 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 .** variable eve
12310 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 n if the zText v
12320 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c ariable is a NUL
12330 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a L pointer..**.**
12340 20 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 The "%z" format
12350 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b ting option work
12360 73 20 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 s exactly like "
12370 25 73 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 %s" with the.**
12380 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 addition that af
12390 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 ter the string h
123a0 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 as been read and
123b0 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 copied into.**
123c0 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c the result, [sql
123d0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 ite3_free()] is
123e0 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e called on the in
123f0 70 75 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44 put string. {END
12400 7d 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d }.**.** Requirem
12410 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 34 30 33 ents:.** [H17403
12420 5d 20 5b 48 31 37 34 30 36 5d 20 5b 48 31 37 34 ] [H17406] [H174
12430 30 37 5d 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 07].*/.char *sql
12440 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e ite3_mprintf(con
12450 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 st char*,...);.c
12460 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 har *sqlite3_vmp
12470 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 rintf(const char
12480 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 *, va_list);.cha
12490 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 r *sqlite3_snpri
124a0 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f ntf(int,char*,co
124b0 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b nst char*, ...);
124c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
124d0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 : Memory Allocat
124e0 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 20 7b 48 ion Subsystem {H
124f0 31 37 33 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 17300} <S20000>.
12500 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 **.** The SQLite
12510 20 63 6f 72 65 20 20 75 73 65 73 20 74 68 65 73 core uses thes
12520 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 e three routines
12530 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 for all of its
12540 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 own.** internal
12550 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
12560 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 n needs. "Core"
12570 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 in the previous
12580 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 sentence.** does
12590 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 not include ope
125a0 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 rating-system sp
125b0 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 ecific VFS imple
125c0 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a mentation. The.
125d0 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 ** Windows VFS u
125e0 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f ses native mallo
125f0 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 c() and free() f
12600 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f or some operatio
12610 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ns..**.** The sq
12620 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 lite3_malloc() r
12630 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 outine returns a
12640 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c pointer to a bl
12650 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 ock.** of memory
12660 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 at least N byte
12670 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 s in length, whe
12680 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 re N is the para
12690 6d 65 74 65 72 2e 0a 2a 2a 20 49 66 20 73 71 6c meter..** If sql
126a0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 ite3_malloc() is
126b0 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 unable to obtai
126c0 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 n sufficient fre
126d0 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 e.** memory, it
126e0 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 returns a NULL p
126f0 6f 69 6e 74 65 72 2e 20 20 49 66 20 74 68 65 20 ointer. If the
12700 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a parameter N to.*
12710 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 * sqlite3_malloc
12720 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 () is zero or ne
12730 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 gative then sqli
12740 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 te3_malloc() ret
12750 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 urns.** a NULL p
12760 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 ointer..**.** Ca
12770 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 lling sqlite3_fr
12780 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e ee() with a poin
12790 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 ter previously r
127a0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 eturned.** by sq
127b0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f lite3_malloc() o
127c0 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f r sqlite3_reallo
127d0 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 c() releases tha
127e0 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 t memory so.** t
127f0 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 hat it might be
12800 72 65 75 73 65 64 2e 20 20 54 68 65 20 73 71 6c reused. The sql
12810 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 ite3_free() rout
12820 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f ine is.** a no-o
12830 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 p if is called w
12840 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 ith a NULL point
12850 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e er. Passing a N
12860 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 ULL pointer.** t
12870 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 o sqlite3_free()
12880 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 is harmless. A
12890 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 fter being freed
128a0 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 , memory.** shou
128b0 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 ld neither be re
128c0 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 ad nor written.
128d0 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 Even reading pr
128e0 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a eviously freed.*
128f0 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 * memory might r
12900 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 esult in a segme
12910 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 ntation fault or
12920 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 other severe er
12930 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 ror..** Memory c
12940 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 orruption, a seg
12950 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c mentation fault,
12960 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 or other severe
12970 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 error.** might
12980 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 result if sqlite
12990 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 3_free() is call
129a0 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 ed with a non-NU
129b0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a LL pointer that.
129c0 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 ** was not obtai
129d0 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 ned from sqlite3
129e0 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c _malloc() or sql
129f0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a ite3_realloc()..
12a00 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
12a10 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 3_realloc() inte
12a20 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 rface attempts t
12a30 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 o resize a.** pr
12a40 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ior memory alloc
12a50 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c ation to be at l
12a60 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 east N bytes, wh
12a70 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 ere N is the.**
12a80 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
12a90 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c . The memory al
12aa0 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 location to be r
12ab0 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 esized is the fi
12ac0 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 rst.** parameter
12ad0 2e 20 20 49 66 20 74 68 65 20 66 69 72 73 74 20 . If the first
12ae0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
12af0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a ite3_realloc().*
12b00 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e * is a NULL poin
12b10 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 ter then its beh
12b20 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 avior is identic
12b30 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a al to calling.**
12b40 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
12b50 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 N) where N is th
12b60 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
12b70 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 er to sqlite3_re
12b80 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66 20 74 alloc()..** If t
12b90 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
12ba0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 ter to sqlite3_r
12bb0 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f ealloc() is zero
12bc0 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 or.** negative
12bd0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f then the behavio
12be0 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 r is exactly the
12bf0 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 same as calling
12c00 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 .** sqlite3_free
12c10 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74 (P) where P is t
12c20 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
12c30 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 er to sqlite3_re
12c40 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 73 71 6c 69 alloc()..** sqli
12c50 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 te3_realloc() re
12c60 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
12c70 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f to a memory allo
12c80 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 cation.** of at
12c90 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e least N bytes in
12ca0 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 size or NULL if
12cb0 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f sufficient memo
12cc0 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c ry is unavailabl
12cd0 65 2e 0a 2a 2a 20 49 66 20 4d 20 69 73 20 74 68 e..** If M is th
12ce0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 e size of the pr
12cf0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 ior allocation,
12d00 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 then min(N,M) by
12d10 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 tes.** of the pr
12d20 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 ior allocation a
12d30 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 re copied into t
12d40 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 he beginning of
12d50 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a buffer returned.
12d60 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 ** by sqlite3_re
12d70 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 alloc() and the
12d80 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e prior allocation
12d90 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 is freed..** If
12da0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
12db0 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c () returns NULL,
12dc0 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 then the prior
12dd0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 allocation.** is
12de0 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a not freed..**.*
12df0 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 * The memory ret
12e00 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
12e10 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 _malloc() and sq
12e20 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a lite3_realloc().
12e30 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 ** is always ali
12e40 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 gned to at least
12e50 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 an 8 byte bound
12e60 61 72 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a ary. {END}.**.**
12e70 20 54 68 65 20 64 65 66 61 75 6c 74 20 69 6d 70 The default imp
12e80 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 lementation of t
12e90 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
12ea0 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 75 tion subsystem u
12eb0 73 65 73 0a 2a 2a 20 74 68 65 20 6d 61 6c 6c 6f ses.** the mallo
12ec0 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 c(), realloc() a
12ed0 6e 64 20 66 72 65 65 28 29 20 70 72 6f 76 69 64 nd free() provid
12ee0 65 64 20 62 79 20 74 68 65 20 73 74 61 6e 64 61 ed by the standa
12ef0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a rd C library..**
12f00 20 7b 48 31 37 33 38 32 7d 20 48 6f 77 65 76 65 {H17382} Howeve
12f10 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 r, if SQLite is
12f20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 compiled with th
12f30 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 45 4d 4f e.** SQLITE_MEMO
12f40 52 59 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f RY_SIZE=<i>NNN</
12f50 69 3e 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f i> C preprocesso
12f60 72 20 6d 61 63 72 6f 20 28 77 68 65 72 65 20 3c r macro (where <
12f70 69 3e 4e 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69 73 20 i>NNN</i>.** is
12f80 61 6e 20 69 6e 74 65 67 65 72 29 2c 20 74 68 65 an integer), the
12f90 6e 20 53 51 4c 69 74 65 20 63 72 65 61 74 65 20 n SQLite create
12fa0 61 20 73 74 61 74 69 63 20 61 72 72 61 79 20 6f a static array o
12fb0 66 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 3c 69 f at least.** <i
12fc0 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 74 65 73 20 69 >NNN</i> bytes i
12fd0 6e 20 73 69 7a 65 20 61 6e 64 20 75 73 65 73 20 n size and uses
12fe0 74 68 61 74 20 61 72 72 61 79 20 66 6f 72 20 61 that array for a
12ff0 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 ll of its dynami
13000 63 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f c.** memory allo
13010 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 cation needs. {E
13020 4e 44 7d 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 ND} Additional
13030 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
13040 20 6f 70 74 69 6f 6e 73 0a 2a 2a 20 6d 61 79 20 options.** may
13050 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 be added in futu
13060 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a re releases..**.
13070 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 ** In SQLite ver
13080 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 sion 3.5.0 and 3
13090 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 .5.1, it was pos
130a0 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a sible to define.
130b0 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d ** the SQLITE_OM
130c0 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 IT_MEMORY_ALLOCA
130d0 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 TION which would
130e0 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 cause the built
130f0 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 -in.** implement
13100 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 ation of these r
13110 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d outines to be om
13120 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 itted. That cap
13130 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f ability.** is no
13140 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 longer provided
13150 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e . Only built-in
13160 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
13170 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a rs can be used..
13180 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 **.** The Window
13190 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c s OS interface l
131a0 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 ayer calls.** th
131b0 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 e system malloc(
131c0 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 ) and free() dir
131d0 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 ectly when conve
131e0 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d rting.** filenam
131f0 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 es between the U
13200 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 TF-8 encoding us
13210 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 ed by SQLite.**
13220 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c and whatever fil
13230 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 ename encoding i
13240 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 s used by the pa
13250 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 rticular Windows
13260 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e .** installation
13270 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 . Memory alloca
13280 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 tion errors are
13290 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a detected, but.**
132a0 20 74 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 they are report
132b0 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 ed back as [SQLI
132c0 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a TE_CANTOPEN] or.
132d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 ** [SQLITE_IOERR
132e0 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 ] rather than [S
132f0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a QLITE_NOMEM]..**
13300 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
13310 3a 0a 2a 2a 20 5b 48 31 37 33 30 33 5d 20 5b 48 :.** [H17303] [H
13320 31 37 33 30 34 5d 20 5b 48 31 37 33 30 35 5d 20 17304] [H17305]
13330 5b 48 31 37 33 30 36 5d 20 5b 48 31 37 33 31 30 [H17306] [H17310
13340 5d 20 5b 48 31 37 33 31 32 5d 20 5b 48 31 37 33 ] [H17312] [H173
13350 31 35 5d 20 5b 48 31 37 33 31 38 5d 0a 2a 2a 20 15] [H17318].**
13360 5b 48 31 37 33 32 31 5d 20 5b 48 31 37 33 32 32 [H17321] [H17322
13370 5d 20 5b 48 31 37 33 32 33 5d 0a 2a 2a 0a 2a 2a ] [H17323].**.**
13380 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 The pointer arg
13390 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 uments to [sqlit
133a0 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b e3_free()] and [
133b0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
133c0 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 )].** must be ei
133d0 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 ther NULL or els
133e0 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 e pointers obtai
133f0 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 ned from a prior
13400 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f .** invocation o
13410 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f f [sqlite3_mallo
13420 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 c()] or [sqlite3
13430 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 _realloc()] that
13440 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 have.** not yet
13450 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a been released..
13460 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 **.** The applic
13470 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 ation must not r
13480 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 ead or write any
13490 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c part of.** a bl
134a0 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 ock of memory af
134b0 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 ter it has been
134c0 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a released using.*
134d0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 * [sqlite3_free(
134e0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 )] or [sqlite3_r
134f0 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f ealloc()]..*/.vo
13500 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c id *sqlite3_mall
13510 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 oc(int);.void *s
13520 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 qlite3_realloc(v
13530 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 oid*, int);.void
13540 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f sqlite3_free(vo
13550 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 id*);../*.** CAP
13560 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c I3REF: Memory Al
13570 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 locator Statisti
13580 63 73 20 7b 48 31 37 33 37 30 7d 20 3c 53 33 30 cs {H17370} <S30
13590 32 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 210>.**.** SQLit
135a0 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 e provides these
135b0 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 two interfaces
135c0 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e for reporting on
135d0 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f the status.** o
135e0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
135f0 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 alloc()], [sqlit
13600 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 e3_free()], and
13610 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
13620 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c ()].** routines,
13630 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 which form the
13640 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 built-in memory
13650 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 allocation subsy
13660 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 stem..**.** Requ
13670 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
13680 37 33 37 31 5d 20 5b 48 31 37 33 37 33 5d 20 5b 7371] [H17373] [
13690 48 31 37 33 37 34 5d 20 5b 48 31 37 33 37 35 5d H17374] [H17375]
136a0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 .*/.sqlite3_int6
136b0 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 4 sqlite3_memory
136c0 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c _used(void);.sql
136d0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 ite3_int64 sqlit
136e0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
136f0 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 ter(int resetFla
13700 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 g);../*.** CAPI3
13710 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 REF: Pseudo-Rand
13720 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 om Number Genera
13730 74 6f 72 20 7b 48 31 37 33 39 30 7d 20 3c 53 32 tor {H17390} <S2
13740 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 0000>.**.** SQLi
13750 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 te contains a hi
13760 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 gh-quality pseud
13770 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 o-random number
13780 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 generator (PRNG)
13790 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 used to.** sele
137a0 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 ct random [ROWID
137b0 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 | ROWIDs] when
137c0 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 inserting new re
137d0 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 cords into a tab
137e0 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 le that.** alrea
137f0 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 dy uses the larg
13800 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f est possible [RO
13810 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 WID]. The PRNG
13820 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 is also used for
13830 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e .** the build-in
13840 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 random() and ra
13850 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 ndomblob() SQL f
13860 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 unctions. This
13870 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 interface allows
13880 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 .** applications
13890 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 to access the s
138a0 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 ame PRNG for oth
138b0 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a er purposes..**.
138c0 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 ** A call to thi
138d0 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 s routine stores
138e0 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 N bytes of rand
138f0 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 omness into buff
13900 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 er P..**.** The
13910 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 first time this
13920 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b routine is invok
13930 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 ed (either inter
13940 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 nally or by.** t
13950 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 he application)
13960 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 the PRNG is seed
13970 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e ed using randomn
13980 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 ess obtained.**
13990 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d from the xRandom
139a0 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 ness method of t
139b0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 he default [sqli
139c0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e te3_vfs] object.
139d0 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73 75 62 73 65 .** On all subse
139e0 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e quent invocation
139f0 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 s, the pseudo-ra
13a00 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 ndomness is gene
13a10 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 rated.** interna
13a20 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 lly and without
13a30 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 recourse to the
13a40 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 [sqlite3_vfs] xR
13a50 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 andomness.** met
13a60 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 hod..**.** Requi
13a70 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 rements:.** [H17
13a80 33 39 32 5d 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 392].*/.void sql
13a90 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 ite3_randomness(
13aa0 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b int N, void *P);
13ab0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
13ac0 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 : Compile-Time A
13ad0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c uthorization Cal
13ae0 6c 62 61 63 6b 73 20 7b 48 31 32 35 30 30 7d 20 lbacks {H12500}
13af0 3c 53 37 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S70100>.**.** T
13b00 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 his routine regi
13b10 73 74 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a sters a authoriz
13b20 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 er callback with
13b30 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a a particular.**
13b40 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
13b50 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 ction], supplied
13b60 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
13b70 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 gument..** The a
13b80 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
13b90 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 ck is invoked as
13ba0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
13bb0 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c are being compil
13bc0 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 ed.** by [sqlite
13bd0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 3_prepare()] or
13be0 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 its variants [sq
13bf0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
13c00 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
13c10 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e _prepare16()] an
13c20 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 d [sqlite3_prepa
13c30 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 41 74 20 re16_v2()]. At
13c40 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 various.** point
13c50 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d s during the com
13c60 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 pilation process
13c70 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 , as logic is be
13c80 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 ing created.** t
13c90 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 o perform variou
13ca0 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 s actions, the a
13cb0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
13cc0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f ck is invoked to
13cd0 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 .** see if those
13ce0 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c actions are all
13cf0 6f 77 65 64 2e 20 20 54 68 65 20 61 75 74 68 6f owed. The autho
13d00 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 rizer callback s
13d10 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 hould.** return
13d20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 [SQLITE_OK] to a
13d30 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c llow the action,
13d40 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d [SQLITE_IGNORE]
13d50 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 to disallow the
13d60 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 .** specific act
13d70 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 ion but allow th
13d80 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
13d90 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 to continue to b
13da0 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f e.** compiled, o
13db0 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 r [SQLITE_DENY]
13dc0 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 to cause the ent
13dd0 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ire SQL statemen
13de0 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 t to be.** rejec
13df0 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f ted with an erro
13e00 72 2e 20 20 49 66 20 74 68 65 20 61 75 74 68 6f r. If the autho
13e10 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 rizer callback r
13e20 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 eturns.** any va
13e30 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b lue other than [
13e40 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 SQLITE_IGNORE],
13e50 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 [SQLITE_OK], or
13e60 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a [SQLITE_DENY].**
13e70 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 then the [sqlit
13e80 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
13e90 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 or equivalent c
13ea0 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 all that trigger
13eb0 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 ed.** the author
13ec0 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 izer will fail w
13ed0 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 ith an error mes
13ee0 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e sage..**.** When
13ef0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 the callback re
13f00 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b turns [SQLITE_OK
13f10 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 ], that means th
13f20 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 e operation.** r
13f30 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 equested is ok.
13f40 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 When the callba
13f50 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ck returns [SQLI
13f60 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a TE_DENY], the.**
13f70 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
13f80 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 e_v2()] or equiv
13f90 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 alent call that
13fa0 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a triggered the.**
13fb0 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c authorizer will
13fc0 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 fail with an er
13fd0 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c ror message expl
13fe0 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 aining that.** a
13ff0 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e ccess is denied.
14000 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 .**.** The firs
14010 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 t parameter to t
14020 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
14030 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 llback is a copy
14040 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a of the third.**
14050 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
14060 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 e sqlite3_set_au
14070 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 thorizer() inter
14080 66 61 63 65 2e 20 54 68 65 20 73 65 63 6f 6e 64 face. The second
14090 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f parameter.** to
140a0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 the callback is
140b0 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c an integer [SQL
140c0 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f ITE_COPY | actio
140d0 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 n code] that spe
140e0 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 cifies.** the pa
140f0 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 rticular action
14100 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 to be authorized
14110 2e 20 54 68 65 20 74 68 69 72 64 20 74 68 72 6f . The third thro
14120 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 ugh sixth parame
14130 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 ters.** to the c
14140 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f allback are zero
14150 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 -terminated stri
14160 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e ngs that contain
14170 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 additional.** d
14180 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 etails about the
14190 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 action to be au
141a0 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 thorized..**.**
141b0 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f If the action co
141c0 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 de is [SQLITE_RE
141d0 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 AD].** and the c
141e0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
141f0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 [SQLITE_IGNORE]
14200 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 then the.** [pre
14210 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
14220 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f statement is co
14230 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 nstructed to sub
14240 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c stitute.** a NUL
14250 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 L value in place
14260 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f of the table co
14270 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 lumn that would
14280 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 have.** been rea
14290 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d d if [SQLITE_OK]
142a0 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e had been return
142b0 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 ed. The [SQLITE
142c0 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 _IGNORE].** retu
142d0 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 rn can be used t
142e0 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 o deny an untrus
142f0 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 ted user access
14300 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a to individual.**
14310 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 columns of a ta
14320 62 6c 65 2e 0a 2a 2a 20 49 66 20 74 68 65 20 61 ble..** If the a
14330 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 ction code is [S
14340 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e QLITE_DELETE] an
14350 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 d the callback r
14360 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 eturns.** [SQLIT
14370 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 E_IGNORE] then t
14380 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 he [DELETE] oper
14390 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 ation proceeds b
143a0 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 ut the.** [trunc
143b0 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e ate optimization
143c0 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e ] is disabled an
143d0 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 d all rows are d
143e0 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 eleted individua
143f0 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 lly..**.** An au
14400 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 thorizer is used
14410 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 when [sqlite3_p
14420 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 repare | prepari
14430 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 ng].** SQL state
14440 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e ments from an un
14450 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 trusted source,
14460 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 to ensure that t
14470 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
14480 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 s.** do not try
14490 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 to access data t
144a0 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f hey are not allo
144b0 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 wed to see, or t
144c0 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a hat they do not.
144d0 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 ** try to execut
144e0 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 e malicious stat
144f0 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 ements that dama
14500 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e ge the database.
14510 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 For.** example
14520 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e , an application
14530 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 may allow a use
14540 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 r to enter arbit
14550 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 rary.** SQL quer
14560 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 ies for evaluati
14570 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 on by a database
14580 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 . But the appli
14590 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e cation does.** n
145a0 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 ot want the user
145b0 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d to be able to m
145c0 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 ake arbitrary ch
145d0 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 anges to the.**
145e0 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 database. An au
145f0 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 thorizer could t
14600 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c hen be put in pl
14610 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a ace while the.**
14620 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 user-entered SQ
14630 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 L is being [sqli
14640 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 te3_prepare | pr
14650 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 epared] that.**
14660 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 disallows everyt
14670 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c hing except [SEL
14680 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e ECT] statements.
14690 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 .**.** Applicati
146a0 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f ons that need to
146b0 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f process SQL fro
146c0 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 m untrusted sour
146d0 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 ces.** might als
146e0 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 o consider lower
146f0 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d ing resource lim
14700 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 its using [sqlit
14710 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 e3_limit()].** a
14720 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 nd limiting data
14730 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 base size using
14740 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f the [max_page_co
14750 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a unt] [PRAGMA].**
14760 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 in addition to
14770 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 using an authori
14780 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 zer..**.** Only
14790 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 a single authori
147a0 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c zer can be in pl
147b0 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 ace on a databas
147c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
147d0 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 at a time. Each
147e0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
147f0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 _set_authorizer
14800 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a overrides the.**
14810 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20 previous call.
14820 20 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 Disable the aut
14830 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 horizer by insta
14840 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c lling a NULL cal
14850 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 lback..** The au
14860 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 thorizer is disa
14870 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e bled by default.
14880 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f .**.** The autho
14890 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d rizer callback m
148a0 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 ust not do anyth
148b0 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f ing that will mo
148c0 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 dify.** the data
148d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
148e0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 that invoked the
148f0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
14900 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 back..** Note th
14910 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 at [sqlite3_prep
14920 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 are_v2()] and [s
14930 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 qlite3_step()] b
14940 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 oth modify their
14950 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
14960 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 nections for the
14970 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 meaning of "mod
14980 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 ify" in this par
14990 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 57 68 agraph..**.** Wh
149a0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 en [sqlite3_prep
149b0 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 are_v2()] is use
149c0 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 d to prepare a s
149d0 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a tatement, the.**
149e0 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 statement might
149f0 20 62 65 20 72 65 70 72 65 70 61 72 65 64 20 64 be reprepared d
14a00 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 uring [sqlite3_s
14a10 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 tep()] due to a
14a20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 .** schema chang
14a30 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 e. Hence, the a
14a40 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
14a50 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 d ensure that th
14a60 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 e.** correct aut
14a70 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
14a80 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 remains in plac
14a90 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 e during the [sq
14aa0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a lite3_step()]..*
14ab0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 *.** Note that t
14ac0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
14ad0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
14ae0 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a d only during.**
14af0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
14b00 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 e()] or its vari
14b10 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 ants. Authoriza
14b20 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 tion is not.** p
14b30 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 erformed during
14b40 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 statement evalua
14b50 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 tion in [sqlite3
14b60 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 _step()], unless
14b70 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e .** as stated in
14b80 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 the previous pa
14b90 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 ragraph, sqlite3
14ba0 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a _step() invokes.
14bb0 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 ** sqlite3_prepa
14bc0 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 re_v2() to repre
14bd0 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 pare a statement
14be0 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 after a schema
14bf0 63 68 61 6e 67 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 change..**.** Re
14c00 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
14c10 48 31 32 35 30 31 5d 20 5b 48 31 32 35 30 32 5d H12501] [H12502]
14c20 20 5b 48 31 32 35 30 33 5d 20 5b 48 31 32 35 30 [H12503] [H1250
14c30 34 5d 20 5b 48 31 32 35 30 35 5d 20 5b 48 31 32 4] [H12505] [H12
14c40 35 30 36 5d 20 5b 48 31 32 35 30 37 5d 20 5b 48 506] [H12507] [H
14c50 31 32 35 31 30 5d 0a 2a 2a 20 5b 48 31 32 35 31 12510].** [H1251
14c60 31 5d 20 5b 48 31 32 35 31 32 5d 20 5b 48 31 32 1] [H12512] [H12
14c70 35 32 30 5d 20 5b 48 31 32 35 32 31 5d 20 5b 48 520] [H12521] [H
14c80 31 32 35 32 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 12522].*/.int sq
14c90 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
14ca0 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a izer(. sqlite3*
14cb0 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 ,. int (*xAuth)
14cc0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 (void*,int,const
14cd0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 char*,const cha
14ce0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 r*,const char*,c
14cf0 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 onst char*),. v
14d00 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 oid *pUserData.)
14d10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
14d20 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 F: Authorizer Re
14d30 74 75 72 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 turn Codes {H125
14d40 39 30 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 90} <H12500>.**.
14d50 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f ** The [sqlite3_
14d60 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c set_authorizer |
14d70 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
14d80 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d back function] m
14d90 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 ust.** return ei
14da0 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d ther [SQLITE_OK]
14db0 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 or one of these
14dc0 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 two constants i
14dd0 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 n order.** to si
14de0 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 gnal SQLite whet
14df0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 her or not the a
14e00 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 ction is permitt
14e10 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 ed. See the.**
14e20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 [sqlite3_set_aut
14e30 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 horizer | author
14e40 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 izer documentati
14e50 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e on] for addition
14e60 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f al.** informatio
14e70 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 n..*/.#define SQ
14e80 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 LITE_DENY 1
14e90 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c /* Abort the SQL
14ea0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 statement with
14eb0 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 an error */.#def
14ec0 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 ine SQLITE_IGNOR
14ed0 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 E 2 /* Don't a
14ee0 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 llow access, but
14ef0 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 don't generate
14f00 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a an error */../*.
14f10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 ** CAPI3REF: Aut
14f20 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 horizer Action C
14f30 6f 64 65 73 20 7b 48 31 32 35 35 30 7d 20 3c 48 odes {H12550} <H
14f40 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 12500>.**.** The
14f50 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
14f60 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 thorizer()] inte
14f70 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 rface registers
14f80 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 a callback funct
14f90 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 ion.** that is i
14fa0 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 nvoked to author
14fb0 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 ize certain SQL
14fc0 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e statement action
14fd0 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e s. The.** secon
14fe0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 d parameter to t
14ff0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 he callback is a
15000 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 n integer code t
15010 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a hat specifies.**
15020 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 what action is
15030 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 being authorized
15040 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 . These are the
15050 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 integer action
15060 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 codes that.** th
15070 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
15080 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 lback may be pas
15090 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 sed..**.** These
150a0 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c action code val
150b0 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 ues signify what
150c0 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 kind of operati
150d0 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 on is to be.** a
150e0 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 uthorized. The
150f0 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 3rd and 4th para
15100 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 meters to the au
15110 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 thorization.** c
15120 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
15130 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 will be paramet
15140 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 ers or NULL depe
15150 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f nding on which o
15160 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 f these.** codes
15170 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 is used as the
15180 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
15190 2e 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d . The 5th param
151a0 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 eter to the.** a
151b0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
151c0 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f ck is the name o
151d0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 f the database (
151e0 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a "main", "temp",.
151f0 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c ** etc.) if appl
15200 69 63 61 62 6c 65 2e 20 20 54 68 65 20 36 74 68 icable. The 6th
15210 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
15220 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
15230 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 lback.** is the
15240 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 name of the inne
15250 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f r-most trigger o
15260 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 r view that is r
15270 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a esponsible for.*
15280 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 * the access att
15290 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 empt or NULL if
152a0 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 this access atte
152b0 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 mpt is directly
152c0 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 from.** top-leve
152d0 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a l SQL code..**.*
152e0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
152f0 2a 2a 20 5b 48 31 32 35 35 31 5d 20 5b 48 31 32 ** [H12551] [H12
15300 35 35 32 5d 20 5b 48 31 32 35 35 33 5d 20 5b 48 552] [H12553] [H
15310 31 32 35 35 34 5d 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 12554].*/./*****
15320 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
15330 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
15340 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a ****** 3rd *****
15350 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a ******* 4th ****
15360 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 *******/.#define
15370 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 SQLITE_CREATE_I
15380 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 NDEX 1
15390 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 /* Index Name
153a0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 Table Name
153b0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
153c0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 SQLITE_CREATE_TA
153d0 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 BLE 2
153e0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
153f0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
15400 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
15410 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d QLITE_CREATE_TEM
15420 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 P_INDEX 3
15430 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 /* Index Name
15440 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
15450 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
15460 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 LITE_CREATE_TEMP
15470 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f _TABLE 4 /
15480 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
15490 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
154a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
154b0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f ITE_CREATE_TEMP_
154c0 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a TRIGGER 5 /*
154d0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 Trigger Name
154e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
154f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
15500 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 TE_CREATE_TEMP_V
15510 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 IEW 6 /*
15520 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 View Name
15530 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
15540 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
15550 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 E_CREATE_TRIGGER
15560 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 7 /* T
15570 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 rigger Name T
15580 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
15590 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
155a0 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 _CREATE_VIEW
155b0 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 8 /* Vi
155c0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 ew Name NU
155d0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
155e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
155f0 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 DELETE
15600 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 9 /* Tab
15610 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
15620 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
15630 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
15640 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 ROP_INDEX
15650 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 10 /* Inde
15660 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c x Name Tabl
15670 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
15680 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
15690 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 OP_TABLE
156a0 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 11 /* Table
156b0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
156c0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
156d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
156e0 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 P_TEMP_INDEX
156f0 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 12 /* Index
15700 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 Name Table
15710 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
15720 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
15730 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 _TEMP_TABLE
15740 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 13 /* Table N
15750 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
15760 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
15770 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
15780 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 TEMP_TRIGGER
15790 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 14 /* Trigger
157a0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 Name Table Na
157b0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
157c0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
157d0 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 EMP_VIEW 1
157e0 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 5 /* View Name
157f0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
15800 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
15810 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 e SQLITE_DROP_TR
15820 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 IGGER 16
15830 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 /* Trigger Na
15840 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 me Table Name
15850 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
15860 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 SQLITE_DROP_VIE
15870 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 W 17
15880 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 /* View Name
15890 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
158a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
158b0 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 SQLITE_INSERT
158c0 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 18
158d0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
158e0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
158f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
15900 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 QLITE_PRAGMA
15910 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 19
15920 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 /* Pragma Name
15930 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 1st arg or NU
15940 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 LL */.#define SQ
15950 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 LITE_READ
15960 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 20 /
15970 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
15980 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 Column Name
15990 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
159a0 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 ITE_SELECT
159b0 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 21 /*
159c0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
159d0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
159e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
159f0 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 TE_TRANSACTION
15a00 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 22 /*
15a10 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 Operation
15a20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
15a30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
15a40 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 E_UPDATE
15a50 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 23 /* T
15a60 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 able Name C
15a70 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a olumn Name *
15a80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
15a90 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 _ATTACH
15aa0 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 24 /* Fi
15ab0 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 lename NU
15ac0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
15ad0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
15ae0 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 DETACH
15af0 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 25 /* Dat
15b00 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c abase Name NUL
15b10 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
15b20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
15b30 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 LTER_TABLE
15b40 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 26 /* Data
15b50 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c base Name Tabl
15b60 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
15b70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 define SQLITE_RE
15b80 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 INDEX
15b90 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 27 /* Index
15ba0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
15bb0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
15bc0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 efine SQLITE_ANA
15bd0 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 LYZE
15be0 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 28 /* Table
15bf0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
15c00 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
15c10 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
15c20 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 TE_VTABLE
15c30 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 29 /* Table N
15c40 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 ame Module
15c50 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 Name */.#def
15c60 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
15c70 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 VTABLE
15c80 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 30 /* Table Na
15c90 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e me Module N
15ca0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 ame */.#defi
15cb0 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 ne SQLITE_FUNCTI
15cc0 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 ON 3
15cd0 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 1 /* NULL
15ce0 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 Function
15cf0 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e Name */.#defin
15d00 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 e SQLITE_SAVEPOI
15d10 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 NT 32
15d20 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 /* Operation
15d30 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 Savepoint
15d40 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 Name */.#define
15d50 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 SQLITE_COPY
15d60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 0
15d70 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 /* No longer u
15d80 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 sed */../*.** CA
15d90 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 PI3REF: Tracing
15da0 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 And Profiling Fu
15db0 6e 63 74 69 6f 6e 73 20 7b 48 31 32 32 38 30 7d nctions {H12280}
15dc0 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 20 45 58 50 <S60400>.** EXP
15dd0 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 ERIMENTAL.**.**
15de0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
15df0 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b egister callback
15e00 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 functions that
15e10 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a can be used for.
15e20 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 ** tracing and p
15e30 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 rofiling the exe
15e40 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 cution of SQL st
15e50 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 atements..**.**
15e60 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e The callback fun
15e70 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 ction registered
15e80 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 by sqlite3_trac
15e90 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 e() is invoked a
15ea0 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d t.** various tim
15eb0 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 es when an SQL s
15ec0 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e tatement is bein
15ed0 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 g run by [sqlite
15ee0 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 3_step()]..** Th
15ef0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 e callback retur
15f00 6e 73 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 ns a UTF-8 rende
15f10 72 69 6e 67 20 6f 66 20 74 68 65 20 53 51 4c 20 ring of the SQL
15f20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 0a 2a statement text.*
15f30 2a 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 * as the stateme
15f40 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 nt first begins
15f50 65 78 65 63 75 74 69 6e 67 2e 20 20 41 64 64 69 executing. Addi
15f60 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 tional callbacks
15f70 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 occur.** as eac
15f80 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 h triggered subp
15f90 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 rogram is entere
15fa0 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b d. The callback
15fb0 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a s for triggers.*
15fc0 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d * contain a UTF-
15fd0 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 8 SQL comment th
15fe0 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 at identifies th
15ff0 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a e trigger..**.**
16000 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 The callback fu
16010 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 nction registere
16020 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f d by sqlite3_pro
16030 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 file() is invoke
16040 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c d.** as each SQL
16050 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 statement finis
16060 68 65 73 2e 20 20 54 68 65 20 70 72 6f 66 69 6c hes. The profil
16070 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 e callback conta
16080 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 ins.** the origi
16090 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 nal statement te
160a0 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 xt and an estima
160b0 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b te of wall-clock
160c0 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 time.** of how
160d0 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d long that statem
160e0 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e ent took to run.
160f0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
16100 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 38 31 5d nts:.** [H12281]
16110 20 5b 48 31 32 32 38 32 5d 20 5b 48 31 32 32 38 [H12282] [H1228
16120 33 5d 20 5b 48 31 32 32 38 34 5d 20 5b 48 31 32 3] [H12284] [H12
16130 32 38 35 5d 20 5b 48 31 32 32 38 37 5d 20 5b 48 285] [H12287] [H
16140 31 32 32 38 38 5d 20 5b 48 31 32 32 38 39 5d 0a 12288] [H12289].
16150 2a 2a 20 5b 48 31 32 32 39 30 5d 0a 2a 2f 0a 53 ** [H12290].*/.S
16160 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 QLITE_EXPERIMENT
16170 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 AL void *sqlite3
16180 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c _trace(sqlite3*,
16190 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 void(*xTrace)(v
161a0 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a oid*,const char*
161b0 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 ), void*);.SQLIT
161c0 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 E_EXPERIMENTAL v
161d0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f oid *sqlite3_pro
161e0 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 file(sqlite3*,.
161f0 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 void(*xProfile
16200 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 )(void*,const ch
16210 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 ar*,sqlite3_uint
16220 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 64), void*);../*
16230 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 .** CAPI3REF: Qu
16240 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c ery Progress Cal
16250 6c 62 61 63 6b 73 20 7b 48 31 32 39 31 30 7d 20 lbacks {H12910}
16260 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S60400>.**.** T
16270 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 his routine conf
16280 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62 61 63 igures a callbac
16290 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 k function - the
162a0 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 63 61 6c .** progress cal
162b0 6c 62 61 63 6b 20 2d 20 74 68 61 74 20 69 73 20 lback - that is
162c0 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 invoked periodic
162d0 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 ally during long
162e0 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c .** running call
162f0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 s to [sqlite3_ex
16300 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f ec()], [sqlite3_
16310 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b step()] and.** [
16320 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
16330 65 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d 70 6c e()]. An exampl
16340 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a e use for this.*
16350 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 * interface is t
16360 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 o keep a GUI upd
16370 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 ated during a la
16380 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a rge query..**.**
16390 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 If the progress
163a0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
163b0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 s non-zero, the
163c0 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 operation is.**
163d0 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 interrupted. Th
163e0 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 is feature can b
163f0 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d e used to implem
16400 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c ent a.** "Cancel
16410 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 " button on a GU
16420 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f I progress dialo
16430 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 g box..**.** The
16440 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 progress handle
16450 72 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e r must not do an
16460 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c ything that will
16470 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 modify.** the d
16480 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
16490 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 on that invoked
164a0 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e the progress han
164b0 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 dler..** Note th
164c0 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 at [sqlite3_prep
164d0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 are_v2()] and [s
164e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 qlite3_step()] b
164f0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 oth modify their
16500 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
16510 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 nections for the
16520 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 meaning of "mod
16530 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 ify" in this par
16540 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 agraph..**.** Re
16550 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
16560 48 31 32 39 31 31 5d 20 5b 48 31 32 39 31 32 5d H12911] [H12912]
16570 20 5b 48 31 32 39 31 33 5d 20 5b 48 31 32 39 31 [H12913] [H1291
16580 34 5d 20 5b 48 31 32 39 31 35 5d 20 5b 48 31 32 4] [H12915] [H12
16590 39 31 36 5d 20 5b 48 31 32 39 31 37 5d 20 5b 48 916] [H12917] [H
165a0 31 32 39 31 38 5d 0a 2a 2a 0a 2a 2f 0a 76 6f 69 12918].**.*/.voi
165b0 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 d sqlite3_progre
165c0 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 ss_handler(sqlit
165d0 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 e3*, int, int(*)
165e0 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b (void*), void*);
165f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
16600 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 : Opening A New
16610 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 Database Connect
16620 69 6f 6e 20 7b 48 31 32 37 30 30 7d 20 3c 53 34 ion {H12700} <S4
16630 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 0200>.**.** Thes
16640 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 e routines open
16650 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 an SQLite databa
16660 73 65 20 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 se file whose na
16670 6d 65 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 me is given by t
16680 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 he.** filename a
16690 72 67 75 6d 65 6e 74 2e 20 54 68 65 20 66 69 6c rgument. The fil
166a0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 ename argument i
166b0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 s interpreted as
166c0 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 UTF-8 for.** sq
166d0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 lite3_open() and
166e0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
166f0 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 () and as UTF-16
16700 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 in the native b
16710 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 yte.** order for
16720 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 sqlite3_open16(
16730 29 2e 20 41 20 5b 64 61 74 61 62 61 73 65 20 63 ). A [database c
16740 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c onnection] handl
16750 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 e is usually.**
16760 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 returned in *ppD
16770 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 b, even if an er
16780 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 ror occurs. The
16790 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 only exception
167a0 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 is that.** if SQ
167b0 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 Lite is unable t
167c0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 o allocate memor
167d0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 y to hold the [s
167e0 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a qlite3] object,.
167f0 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 ** a NULL will b
16800 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a e written into *
16810 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 ppDb instead of
16820 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
16830 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 [sqlite3].** ob
16840 6a 65 63 74 2e 20 49 66 20 74 68 65 20 64 61 74 ject. If the dat
16850 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 abase is opened
16860 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 (and/or created)
16870 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 successfully, t
16880 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f hen.** [SQLITE_O
16890 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 K] is returned.
168a0 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 Otherwise an [e
168b0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 rror code] is re
168c0 74 75 72 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20 turned. The.**
168d0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 [sqlite3_errmsg(
168e0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 )] or [sqlite3_e
168f0 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 rrmsg16()] routi
16900 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 nes can be used
16910 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 to obtain.** an
16920 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 English language
16930 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 description of
16940 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a the error..**.**
16950 20 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 The default enc
16960 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 oding for the da
16970 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 tabase will be U
16980 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 TF-8 if.** sqlit
16990 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c e3_open() or sql
169a0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 ite3_open_v2() i
169b0 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 s called and.**
169c0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 UTF-16 in the na
169d0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 tive byte order
169e0 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 if sqlite3_open1
169f0 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 6() is used..**.
16a00 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f ** Whether or no
16a10 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 t an error occur
16a20 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 s when it is ope
16a30 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a ned, resources.*
16a40 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 * associated wit
16a50 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 h the [database
16a60 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 connection] hand
16a70 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c le should be rel
16a80 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 eased by.** pass
16a90 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 ing it to [sqlit
16aa0 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e e3_close()] when
16ab0 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 it is no longer
16ac0 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a required..**.**
16ad0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 The sqlite3_ope
16ae0 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 n_v2() interface
16af0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 works like sqli
16b00 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 te3_open().** ex
16b10 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 cept that it acc
16b20 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f epts two additio
16b30 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 nal parameters f
16b40 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f or additional co
16b50 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 ntrol.** over th
16b60 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 e new database c
16b70 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 onnection. The
16b80 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 flags parameter
16b90 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a can take one of.
16ba0 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 ** the following
16bb0 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f three values, o
16bc0 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e ptionally combin
16bd0 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 ed with the .**
16be0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d [SQLITE_OPEN_NOM
16bf0 55 54 45 58 5d 20 6f 72 20 5b 53 51 4c 49 54 45 UTEX] or [SQLITE
16c00 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d _OPEN_FULLMUTEX]
16c10 20 66 6c 61 67 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 flags:.**.** <d
16c20 6c 3e 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 l>.** <dt>[SQLIT
16c30 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d E_OPEN_READONLY]
16c40 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
16c50 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
16c60 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 ned in read-only
16c70 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 mode. If the d
16c80 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 atabase does not
16c90 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 .** already exis
16ca0 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 t, an error is r
16cb0 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a eturned.</dd>.**
16cc0 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f .** <dt>[SQLITE_
16cd0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c OPEN_READWRITE]<
16ce0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
16cf0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e database is open
16d00 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 ed for reading a
16d10 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f nd writing if po
16d20 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 ssible, or readi
16d30 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 ng.** only if th
16d40 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 e file is write
16d50 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 protected by the
16d60 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 operating syste
16d70 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a m. In either.**
16d80 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61 case the databa
16d90 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 se must already
16da0 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 exist, otherwise
16db0 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 an error is ret
16dc0 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a urned.</dd>.**.*
16dd0 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 * <dt>[SQLITE_OP
16de0 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 EN_READWRITE] |
16df0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 [SQLITE_OPEN_CRE
16e00 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 ATE]</dt>.** <dd
16e10 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 >The database is
16e20 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 opened for read
16e30 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c ing and writing,
16e40 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 73 20 and is creates
16e50 69 74 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 it if.** it does
16e60 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 not already exi
16e70 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 st. This is the
16e80 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 behavior that is
16e90 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 always used for
16ea0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e .** sqlite3_open
16eb0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f () and sqlite3_o
16ec0 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 0a 2a 2a pen16().</dd>.**
16ed0 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 </dl>.**.** If
16ee0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 the 3rd paramete
16ef0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 r to sqlite3_ope
16f00 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e n_v2() is not on
16f10 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 e of the.** comb
16f20 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 inations shown a
16f30 62 6f 76 65 20 6f 72 20 6f 6e 65 20 6f 66 20 74 bove or one of t
16f40 68 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 he combinations
16f50 73 68 6f 77 6e 20 61 62 6f 76 65 20 63 6f 6d 62 shown above comb
16f60 69 6e 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 ined.** with the
16f70 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f [SQLITE_OPEN_NO
16f80 4d 55 54 45 58 5d 20 6f 72 20 5b 53 51 4c 49 54 MUTEX] or [SQLIT
16f90 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 E_OPEN_FULLMUTEX
16fa0 5d 20 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 6e ] flags,.** then
16fb0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
16fc0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
16fd0 2a 20 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 * If the [SQLITE
16fe0 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 _OPEN_NOMUTEX] f
16ff0 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e lag is set, then
17000 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
17010 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e nnection.** open
17020 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 s in the multi-t
17030 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 hread [threading
17040 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 mode] as long a
17050 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 s the single-thr
17060 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 ead.** mode has
17070 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 not been set at
17080 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 compile-time or
17090 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 49 66 20 start-time. If
170a0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f the.** [SQLITE_O
170b0 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 PEN_FULLMUTEX] f
170c0 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 lag is set then
170d0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
170e0 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a nection opens.**
170f0 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a in the serializ
17100 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ed [threading mo
17110 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c de] unless singl
17120 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 e-thread was.**
17130 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 previously selec
17140 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 ted at compile-t
17150 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d ime or start-tim
17160 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 e..**.** If the
17170 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 filename is ":me
17180 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 mory:", then a p
17190 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 rivate, temporar
171a0 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 y in-memory data
171b0 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 base.** is creat
171c0 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 ed for the conne
171d0 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d ction. This in-
171e0 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 memory database
171f0 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e will vanish when
17200 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 .** the database
17210 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 connection is c
17220 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 losed. Future v
17230 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
17240 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 e might.** make
17250 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 use of additiona
17260 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 l special filena
17270 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 mes that begin w
17280 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 ith the ":" char
17290 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 acter..** It is
172a0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 recommended that
172b0 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 when a database
172c0 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c filename actual
172d0 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 ly does begin wi
172e0 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 th.** a ":" char
172f0 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 acter you should
17300 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 prefix the file
17310 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 name with a path
17320 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 name such as.**
17330 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d "./" to avoid am
17340 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 biguity..**.** I
17350 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 f the filename i
17360 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e s an empty strin
17370 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 g, then a privat
17380 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 e, temporary.**
17390 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 on-disk database
173a0 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 will be created
173b0 2e 20 20 54 68 69 73 20 70 72 69 76 61 74 65 20 . This private
173c0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 database will be
173d0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c .** automaticall
173e0 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f y deleted as soo
173f0 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 n as the databas
17400 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
17410 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 closed..**.** Th
17420 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
17430 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 er to sqlite3_op
17440 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e en_v2() is the n
17450 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 ame of the.** [s
17460 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
17470 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 ct that defines
17480 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 the operating sy
17490 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 stem interface t
174a0 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 hat.** the new d
174b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
174c0 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 on should use.
174d0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 If the fourth pa
174e0 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 rameter is.** a
174f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 NULL pointer the
17500 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 n the default [s
17510 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
17520 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a ct is used..**.*
17530 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e * <b>Note to Win
17540 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 dows users:</b>
17550 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 The encoding us
17560 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e ed for the filen
17570 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 ame argument.**
17580 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 of sqlite3_open(
17590 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 ) and sqlite3_op
175a0 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 en_v2() must be
175b0 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 UTF-8, not whate
175c0 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 ver.** codepage
175d0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 is currently def
175e0 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 ined. Filenames
175f0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 containing inte
17600 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 rnational.** cha
17610 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 racters must be
17620 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 converted to UTF
17630 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 -8 prior to pass
17640 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a ing them into.**
17650 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 sqlite3_open()
17660 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f or sqlite3_open_
17670 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 v2()..**.** Requ
17680 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
17690 32 37 30 31 5d 20 5b 48 31 32 37 30 32 5d 20 5b 2701] [H12702] [
176a0 48 31 32 37 30 33 5d 20 5b 48 31 32 37 30 34 5d H12703] [H12704]
176b0 20 5b 48 31 32 37 30 36 5d 20 5b 48 31 32 37 30 [H12706] [H1270
176c0 37 5d 20 5b 48 31 32 37 30 39 5d 20 5b 48 31 32 7] [H12709] [H12
176d0 37 31 31 5d 0a 2a 2a 20 5b 48 31 32 37 31 32 5d 711].** [H12712]
176e0 20 5b 48 31 32 37 31 33 5d 20 5b 48 31 32 37 31 [H12713] [H1271
176f0 34 5d 20 5b 48 31 32 37 31 37 5d 20 5b 48 31 32 4] [H12717] [H12
17700 37 31 39 5d 20 5b 48 31 32 37 32 31 5d 20 5b 48 719] [H12721] [H
17710 31 32 37 32 33 5d 0a 2a 2f 0a 69 6e 74 20 73 71 12723].*/.int sq
17720 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f lite3_open(. co
17730 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 nst char *filena
17740 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 me, /* Databas
17750 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d e filename (UTF-
17760 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 8) */. sqlite3
17770 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 **ppDb
17780 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 /* OUT: SQLite d
17790 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 b handle */.);.i
177a0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 nt sqlite3_open1
177b0 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 6(. const void
177c0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 *filename, /*
177d0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d Database filenam
177e0 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 e (UTF-16) */.
177f0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 sqlite3 **ppDb
17800 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 /* OUT:
17810 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 SQLite db handle
17820 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 */.);.int sqlit
17830 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f e3_open_v2(. co
17840 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 nst char *filena
17850 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 me, /* Databas
17860 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d e filename (UTF-
17870 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 8) */. sqlite3
17880 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 **ppDb,
17890 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 /* OUT: SQLite d
178a0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e b handle */. in
178b0 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 t flags,
178c0 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a /* Flags *
178d0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
178e0 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e zVfs /* N
178f0 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c ame of VFS modul
17900 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a e to use */.);..
17910 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
17920 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 Error Codes And
17930 4d 65 73 73 61 67 65 73 20 7b 48 31 32 38 30 30 Messages {H12800
17940 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 0a 2a 2a } <S60200>.**.**
17950 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 The sqlite3_err
17960 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 code() interface
17970 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
17980 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 eric [result cod
17990 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 e] or.** [extend
179a0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 ed result code]
179b0 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 for the most rec
179c0 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 ent failed sqlit
179d0 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a e3_* API call.**
179e0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
179f0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e a [database con
17a00 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 nection]. If a p
17a10 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 rior API call fa
17a20 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 iled.** but the
17a30 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 most recent API
17a40 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 call succeeded,
17a50 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
17a60 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 from.** sqlite3
17a70 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e _errcode() is un
17a80 64 65 66 69 6e 65 64 2e 20 20 54 68 65 20 73 71 defined. The sq
17a90 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 lite3_extended_e
17aa0 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 rrcode().** inte
17ab0 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d rface is the sam
17ac0 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 e except that it
17ad0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 always returns
17ae0 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 the .** [extende
17af0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 d result code] e
17b00 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 ven when extende
17b10 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 d result codes a
17b20 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a re.** disabled..
17b30 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
17b40 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 3_errmsg() and s
17b50 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 qlite3_errmsg16(
17b60 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 ) return English
17b70 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 -language.** tex
17b80 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 t that describes
17b90 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 the error, as e
17ba0 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 ither UTF-8 or U
17bb0 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 TF-16 respective
17bc0 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f ly..** Memory to
17bd0 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 hold the error
17be0 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 message string i
17bf0 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e s managed intern
17c00 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 ally..** The app
17c10 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f lication does no
17c20 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 t need to worry
17c30 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 about freeing th
17c40 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 e result..** How
17c50 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 ever, the error
17c60 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 string might be
17c70 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 overwritten or d
17c80 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a eallocated by.**
17c90 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c subsequent call
17ca0 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 s to other SQLit
17cb0 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 e interface func
17cc0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 tions..**.** Whe
17cd0 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 n the serialized
17ce0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
17cf0 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 ] is in use, it
17d00 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 might be the.**
17d10 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f case that a seco
17d20 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 nd error occurs
17d30 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68 on a separate th
17d40 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a read in between.
17d50 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 ** the time of t
17d60 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 he first error a
17d70 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 nd the call to t
17d80 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e hese interfaces.
17d90 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 .** When that ha
17da0 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e ppens, the secon
17db0 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 d error will be
17dc0 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 reported since t
17dd0 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 hese.** interfac
17de0 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 es always report
17df0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
17e00 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f result. To avo
17e10 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 id.** this, each
17e20 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 thread can obta
17e30 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 in exclusive use
17e40 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 of the [databas
17e50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a e connection] D.
17e60 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b ** by invoking [
17e70 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e sqlite3_mutex_en
17e80 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 ter]([sqlite3_db
17e90 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f _mutex](D)) befo
17ea0 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 re beginning.**
17eb0 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 to use D and inv
17ec0 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d oking [sqlite3_m
17ed0 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c utex_leave]([sql
17ee0 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 ite3_db_mutex](D
17ef0 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 )) after.** all
17f00 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 calls to the int
17f10 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 erfaces listed h
17f20 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 ere are complete
17f30 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 d..**.** If an i
17f40 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 nterface fails w
17f50 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 ith SQLITE_MISUS
17f60 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 E, that means th
17f70 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 e interface.** w
17f80 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 as invoked incor
17f90 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 rectly by the ap
17fa0 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 plication. In t
17fb0 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a hat case, the.**
17fc0 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 error code and
17fd0 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d message may or m
17fe0 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a ay not be set..*
17ff0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
18000 73 3a 0a 2a 2a 20 5b 48 31 32 38 30 31 5d 20 5b s:.** [H12801] [
18010 48 31 32 38 30 32 5d 20 5b 48 31 32 38 30 33 5d H12802] [H12803]
18020 20 5b 48 31 32 38 30 37 5d 20 5b 48 31 32 38 30 [H12807] [H1280
18030 38 5d 20 5b 48 31 32 38 30 39 5d 0a 2a 2f 0a 69 8] [H12809].*/.i
18040 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f nt sqlite3_errco
18050 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b de(sqlite3 *db);
18060 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 .int sqlite3_ext
18070 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 ended_errcode(sq
18080 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 lite3 *db);.cons
18090 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
180a0 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 errmsg(sqlite3*)
180b0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 ;.const void *sq
180c0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 lite3_errmsg16(s
180d0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
180e0 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 CAPI3REF: SQL S
180f0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 tatement Object
18100 7b 48 31 33 30 30 30 7d 20 3c 48 31 33 30 31 30 {H13000} <H13010
18110 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b >.** KEYWORDS: {
18120 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
18130 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 nt} {prepared st
18140 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 atements}.**.**
18150 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 An instance of t
18160 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 his object repre
18170 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 sents a single S
18180 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a QL statement..**
18190 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 This object is
181a0 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 variously known
181b0 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73 as a "prepared s
181c0 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a tatement" or a.*
181d0 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 * "compiled SQL
181e0 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 statement" or si
181f0 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 mply as a "state
18200 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ment"..**.** The
18210 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 life of a state
18220 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 ment object goes
18230 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 something like
18240 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e this:.**.** <ol>
18250 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 .** <li> Create
18260 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 the object using
18270 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
18280 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c e_v2()] or a rel
18290 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e ated.** fun
182a0 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 ction..** <li> B
182b0 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 ind values to [h
182c0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 ost parameters]
182d0 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 using the sqlite
182e0 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 3_bind_*().**
182f0 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a interfaces..*
18300 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 * <li> Run the S
18310 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 QL by calling [s
18320 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f qlite3_step()] o
18330 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 ne or more times
18340 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 ..** <li> Reset
18350 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 the statement us
18360 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ing [sqlite3_res
18370 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 et()] then go ba
18380 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 ck.** to st
18390 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a ep 2. Do this z
183a0 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 ero or more time
183b0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 s..** <li> Destr
183c0 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 oy the object us
183d0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e ing [sqlite3_fin
183e0 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f alize()]..** </o
183f0 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 l>.**.** Refer t
18400 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 o documentation
18410 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 on individual me
18420 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 thods above for
18430 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e additional.** in
18440 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 formation..*/.ty
18450 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
18460 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 ite3_stmt sqlite
18470 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 3_stmt;../*.** C
18480 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d API3REF: Run-tim
18490 65 20 4c 69 6d 69 74 73 20 7b 48 31 32 37 36 30 e Limits {H12760
184a0 7d 20 3c 53 32 30 36 30 30 3e 0a 2a 2a 0a 2a 2a } <S20600>.**.**
184b0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 This interface
184c0 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 allows the size
184d0 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 of various const
184e0 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 ructs to be limi
184f0 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e ted.** on a conn
18500 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 ection by connec
18510 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 tion basis. The
18520 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
18530 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 is the.** [data
18540 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
18550 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 whose limit is
18560 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 to be set or que
18570 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 ried. The.** se
18580 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 cond parameter i
18590 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 s one of the [li
185a0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 mit categories]
185b0 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a that define a.**
185c0 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 class of constr
185d0 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 ucts to be size
185e0 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 limited. The th
185f0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ird parameter is
18600 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 the.** new limi
18610 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 t for that const
18620 72 75 63 74 2e 20 20 54 68 65 20 66 75 6e 63 74 ruct. The funct
18630 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 ion returns the
18640 6f 6c 64 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a old limit..**.**
18650 20 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 If the new limi
18660 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 t is a negative
18670 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 number, the limi
18680 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a t is unchanged..
18690 2a 2a 20 46 6f 72 20 74 68 65 20 6c 69 6d 69 74 ** For the limit
186a0 20 63 61 74 65 67 6f 72 79 20 6f 66 20 53 51 4c category of SQL
186b0 49 54 45 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 68 ITE_LIMIT_XYZ th
186c0 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 ere is a .** [li
186d0 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 mits | hard uppe
186e0 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 r bound].** set
186f0 62 79 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d by a compile-tim
18700 65 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 e C preprocessor
18710 20 6d 61 63 72 6f 20 6e 61 6d 65 64 20 0a 2a 2a macro named .**
18720 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 [limits | SQLIT
18730 45 5f 4d 41 58 5f 58 59 5a 5d 2e 0a 2a 2a 20 28 E_MAX_XYZ]..** (
18740 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e The "_LIMIT_" in
18750 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 the name is cha
18760 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e nged to "_MAX_".
18770 29 0a 2a 2a 20 41 74 74 65 6d 70 74 73 20 74 6f ).** Attempts to
18780 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 increase a limi
18790 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 t above its hard
187a0 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 upper bound are
187b0 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 .** silently tru
187c0 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 ncated to the ha
187d0 72 64 20 75 70 70 65 72 20 6c 69 6d 69 74 2e 0a rd upper limit..
187e0 2a 2a 0a 2a 2a 20 52 75 6e 20 74 69 6d 65 20 6c **.** Run time l
187f0 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 imits are intend
18800 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 ed for use in ap
18810 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 plications that
18820 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 manage.** both t
18830 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 heir own interna
18840 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 l database and a
18850 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 lso databases th
18860 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 at are controlle
18870 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 d.** by untruste
18880 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 d external sourc
18890 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 es. An example
188a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 application migh
188b0 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 t be a.** web br
188c0 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 owser that has i
188d0 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 ts own databases
188e0 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 for storing his
188f0 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 tory and.** sepa
18900 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 rate databases c
18910 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 ontrolled by Jav
18920 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 aScript applicat
18930 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a ions downloaded.
18940 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 ** off the Inter
18950 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e net. The intern
18960 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e al databases can
18970 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a be given the.**
18980 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 large, default
18990 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 limits. Databas
189a0 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 es managed by ex
189b0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 ternal sources c
189c0 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d an.** be given m
189d0 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 uch smaller limi
189e0 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 ts designed to p
189f0 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 revent a denial
18a00 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 of service.** at
18a10 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 tack. Developer
18a20 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e s might also wan
18a30 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 t to use the [sq
18a40 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
18a50 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 izer()].** inter
18a60 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 face to further
18a70 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 control untruste
18a80 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 d SQL. The size
18a90 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
18aa0 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 .** created by a
18ab0 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 n untrusted scri
18ac0 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 pt can be contai
18ad0 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a ned using the.**
18ae0 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 [max_page_count
18af0 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a ] [PRAGMA]..**.*
18b00 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c * New run-time l
18b10 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 imit categories
18b20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 may be added in
18b30 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e future releases.
18b40 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
18b50 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 37 36 32 5d nts:.** [H12762]
18b60 20 5b 48 31 32 37 36 36 5d 20 5b 48 31 32 37 36 [H12766] [H1276
18b70 39 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 9].*/.int sqlite
18b80 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 3_limit(sqlite3*
18b90 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 , int id, int ne
18ba0 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 wVal);../*.** CA
18bb0 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 PI3REF: Run-Time
18bc0 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 Limit Categorie
18bd0 73 20 7b 48 31 32 37 39 30 7d 20 3c 48 31 32 37 s {H12790} <H127
18be0 36 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 60>.** KEYWORDS:
18bf0 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 {limit category
18c00 7d 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 } {limit categor
18c10 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ies}.**.** These
18c20 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e constants defin
18c30 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 e various perfor
18c40 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 mance limits.**
18c50 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 that can be lowe
18c60 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 red at run-time
18c70 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c using [sqlite3_l
18c80 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 imit()]..** The
18c90 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 synopsis of the
18ca0 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 meanings of the
18cb0 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 various limits i
18cc0 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a s shown below..*
18cd0 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 * Additional inf
18ce0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 ormation is avai
18cf0 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 lable at [limits
18d00 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c | Limits in SQL
18d10 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e ite]..**.** <dl>
18d20 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c .** <dt>SQLITE_L
18d30 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e IMIT_LENGTH</dt>
18d40 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
18d50 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 mum size of any
18d60 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f string or BLOB o
18d70 72 20 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e r table row.<dd>
18d80 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
18d90 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 E_LIMIT_SQL_LENG
18da0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 TH</dt>.** <dd>T
18db0 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 he maximum lengt
18dc0 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 h of an SQL stat
18dd0 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a ement.</dd>.**.*
18de0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d * <dt>SQLITE_LIM
18df0 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a IT_COLUMN</dt>.*
18e00 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
18e10 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 m number of colu
18e20 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 mns in a table d
18e30 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 efinition or in
18e40 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 the.** result se
18e50 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 t of a [SELECT]
18e60 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e or the maximum n
18e70 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
18e80 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 in an index.**
18e90 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 or in an ORDER B
18ea0 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c Y or GROUP BY cl
18eb0 61 75 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ause.</dd>.**.**
18ec0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 <dt>SQLITE_LIMI
18ed0 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 T_EXPR_DEPTH</dt
18ee0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
18ef0 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 imum depth of th
18f00 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 e parse tree on
18f10 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c any expression.<
18f20 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
18f30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 QLITE_LIMIT_COMP
18f40 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e OUND_SELECT</dt>
18f50 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
18f60 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 mum number of te
18f70 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e rms in a compoun
18f80 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 d SELECT stateme
18f90 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c nt.</dd>.**.** <
18fa0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
18fb0 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 VDBE_OP</dt>.**
18fc0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
18fd0 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 number of instru
18fe0 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 ctions in a virt
18ff0 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 ual machine prog
19000 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 ram.** used to i
19010 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 mplement an SQL
19020 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a statement.</dd>.
19030 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
19040 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f _LIMIT_FUNCTION_
19050 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ARG</dt>.** <dd>
19060 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
19070 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 er of arguments
19080 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f on a function.</
19090 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
190a0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 LITE_LIMIT_ATTAC
190b0 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e HED</dt>.** <dd>
190c0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
190d0 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 er of [ATTACH |
190e0 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 attached databas
190f0 65 73 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 es].</dd>.**.**
19100 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
19110 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 _LIKE_PATTERN_LE
19120 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 NGTH</dt>.** <dd
19130 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e >The maximum len
19140 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 gth of the patte
19150 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 rn argument to t
19160 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 he [LIKE] or.**
19170 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 [GLOB] operators
19180 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
19190 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 >SQLITE_LIMIT_VA
191a0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 RIABLE_NUMBER</d
191b0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
191c0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
191d0 76 61 72 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 variables in an
191e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 SQL statement th
191f0 61 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 at can.** be bou
19200 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c nd.</dd>.** </dl
19210 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c >.*/.#define SQL
19220 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 ITE_LIMIT_LENGTH
19230 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
19240 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 0.#define SQ
19250 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c LITE_LIMIT_SQL_L
19260 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 ENGTH
19270 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 1.#define S
19280 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 QLITE_LIMIT_COLU
19290 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 MN
192a0 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 2.#define
192b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 SQLITE_LIMIT_EXP
192c0 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 R_DEPTH
192d0 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 3.#define
192e0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f SQLITE_LIMIT_CO
192f0 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 MPOUND_SELECT
19300 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 4.#defin
19310 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 e SQLITE_LIMIT_V
19320 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 DBE_OP
19330 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 5.#defi
19340 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
19350 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 FUNCTION_ARG
19360 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 6.#def
19370 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
19380 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 _ATTACHED
19390 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 7.#de
193a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
193b0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c T_LIKE_PATTERN_L
193c0 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 ENGTH 8.#d
193d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
193e0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 IT_VARIABLE_NUMB
193f0 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 0a ER 9..
19400 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
19410 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c Compiling An SQL
19420 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 30 Statement {H130
19430 31 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 20 10} <S10000>.**
19440 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 KEYWORDS: {SQL s
19450 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 tatement compile
19460 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 r}.**.** To exec
19470 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 ute an SQL query
19480 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 , it must first
19490 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f be compiled into
194a0 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 a byte-code.**
194b0 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e program using on
194c0 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 e of these routi
194d0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 nes..**.** The f
194e0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 irst argument, "
194f0 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 db", is a [datab
19500 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
19510 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a obtained from a.
19520 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 ** prior success
19530 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ful call to [sql
19540 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 ite3_open()], [s
19550 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
19560 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ] or.** [sqlite3
19570 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 _open16()]. The
19580 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
19590 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 tion must not ha
195a0 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a ve been closed..
195b0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 **.** The second
195c0 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c argument, "zSql
195d0 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d ", is the statem
195e0 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c ent to be compil
195f0 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 ed, encoded.** a
19600 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f s either UTF-8 o
19610 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 r UTF-16. The s
19620 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
19630 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 and sqlite3_pre
19640 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 pare_v2().** int
19650 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d erfaces use UTF-
19660 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 8, and sqlite3_p
19670 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 repare16() and s
19680 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
19690 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 _v2().** use UTF
196a0 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 -16..**.** If th
196b0 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 e nByte argument
196c0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 is less than ze
196d0 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 ro, then zSql is
196e0 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a read up to the.
196f0 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 ** first zero te
19700 72 6d 69 6e 61 74 6f 72 2e 20 49 66 20 6e 42 79 rminator. If nBy
19710 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 te is non-negati
19720 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 ve, then it is t
19730 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 he maximum.** nu
19740 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 mber of bytes r
19750 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 ead from zSql.
19760 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f When nByte is no
19770 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a n-negative, the.
19780 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 ** zSql string e
19790 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68 nds at either th
197a0 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f e first '\000' o
197b0 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 r '\u0000' chara
197c0 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e cter or.** the n
197d0 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 Byte-th byte, wh
197e0 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 ichever comes fi
197f0 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c rst. If the call
19800 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 er knows.** that
19810 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 the supplied st
19820 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d ring is nul-term
19830 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 inated, then the
19840 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a re is a small.**
19850 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 performance adv
19860 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 antage to be gai
19870 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 ned by passing a
19880 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 n nByte paramete
19890 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 r that.** is equ
198a0 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 al to the number
198b0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 of bytes in the
198c0 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 input string <i
198d0 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a >including</i>.*
198e0 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e * the nul-termin
198f0 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a ator bytes..**.*
19900 2a 20 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e * If pzTail is n
19910 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a ot NULL then *pz
19920 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 Tail is made to
19930 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 point to the fir
19940 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 st byte.** past
19950 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 the end of the f
19960 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 irst SQL stateme
19970 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 nt in zSql. The
19980 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 se routines only
19990 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 .** compile the
199a0 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 first statement
199b0 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 in zSql, so *pzT
199c0 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e ail is left poin
199d0 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 ting to.** what
199e0 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c remains uncompil
199f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d ed..**.** *ppStm
19a00 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 t is left pointi
19a10 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 ng to a compiled
19a20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
19a30 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 ment] that can b
19a40 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 e.** executed us
19a50 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 ing [sqlite3_ste
19a60 70 28 29 5d 2e 20 20 49 66 20 74 68 65 72 65 20 p()]. If there
19a70 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 is an error, *pp
19a80 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 Stmt is set.** t
19a90 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 o NULL. If the
19aa0 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 input text conta
19ab0 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 ins no SQL (if t
19ac0 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 he input is an e
19ad0 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f mpty.** string o
19ae0 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 r a comment) the
19af0 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 n *ppStmt is set
19b00 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 to NULL..** The
19b10 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 calling procedu
19b20 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c re is responsibl
19b30 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 e for deleting t
19b40 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 he compiled.** S
19b50 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 QL statement usi
19b60 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 ng [sqlite3_fina
19b70 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 lize()] after it
19b80 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 has finished wi
19b90 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 th it..** ppStmt
19ba0 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c may not be NULL
19bb0 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 ..**.** On succe
19bc0 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 ss, [SQLITE_OK]
19bd0 69 73 20 72 65 74 75 72 6e 65 64 2c 20 6f 74 68 is returned, oth
19be0 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 erwise an [error
19bf0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e code] is return
19c00 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ed..**.** The sq
19c10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
19c20 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 () and sqlite3_p
19c30 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e repare16_v2() in
19c40 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 terfaces are.**
19c50 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 recommended for
19c60 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 all new programs
19c70 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 . The two older
19c80 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72 interfaces are r
19c90 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 etained.** for b
19ca0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 ackwards compati
19cb0 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 bility, but thei
19cc0 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 r use is discour
19cd0 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 aged..** In the
19ce0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c "v2" interfaces,
19cf0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 the prepared st
19d00 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 atement.** that
19d10 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 is returned (the
19d20 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 [sqlite3_stmt]
19d30 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 object) contains
19d40 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a a copy of the.*
19d50 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 * original SQL t
19d60 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 ext. This causes
19d70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 the [sqlite3_st
19d80 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 ep()] interface
19d90 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 64 to.** behave a d
19da0 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 77 ifferently in tw
19db0 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f o ways:.**.** <o
19dc0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 l>.** <li>.** If
19dd0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 the database sc
19de0 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e hema changes, in
19df0 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 stead of returni
19e00 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d ng [SQLITE_SCHEM
19e10 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 A] as it.** alwa
19e20 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b ys used to do, [
19e30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
19e40 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c will automatical
19e50 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 ly recompile the
19e60 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e SQL.** statemen
19e70 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e t and try to run
19e80 20 69 74 20 61 67 61 69 6e 2e 20 20 49 66 20 74 it again. If t
19e90 68 65 20 73 63 68 65 6d 61 20 68 61 73 20 63 68 he schema has ch
19ea0 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 anged in.** a wa
19eb0 79 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 y that makes the
19ec0 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f statement no lo
19ed0 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c nger valid, [sql
19ee0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c ite3_step()] wil
19ef0 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 l still.** retur
19f00 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 n [SQLITE_SCHEMA
19f10 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 ]. But unlike t
19f20 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 he legacy behavi
19f30 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 or, [SQLITE_SCHE
19f40 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 MA] is.** now a
19f50 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 fatal error. Ca
19f60 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 lling [sqlite3_p
19f70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61 repare_v2()] aga
19f80 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 in will not make
19f90 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f the.** error go
19fa0 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 away. Note: us
19fb0 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 e [sqlite3_errms
19fc0 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 g()] to find the
19fd0 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 text.** of the
19fe0 70 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68 parsing error th
19ff0 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e at results in an
1a000 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d [SQLITE_SCHEMA]
1a010 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 return..** </li
1a020 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 >.**.** <li>.**
1a030 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 When an error oc
1a040 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 curs, [sqlite3_s
1a050 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 tep()] will retu
1a060 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 rn one of the de
1a070 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 tailed.** [error
1a080 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 codes] or [exte
1a090 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 nded error codes
1a0a0 5d 2e 20 20 54 68 65 20 6c 65 67 61 63 79 20 62 ]. The legacy b
1a0b0 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 ehavior was that
1a0c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 .** [sqlite3_ste
1a0d0 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 p()] would only
1a0e0 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 return a generic
1a0f0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
1a100 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 result code.** a
1a110 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 nd you would hav
1a120 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f e to make a seco
1a130 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 nd call to [sqli
1a140 74 65 33 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 te3_reset()] in
1a150 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 66 69 6e 64 order.** to find
1a160 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 the underlying
1a170 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f cause of the pro
1a180 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 blem. With the "
1a190 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 v2" prepare.** i
1a1a0 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 nterfaces, the u
1a1b0 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e nderlying reason
1a1c0 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 for the error i
1a1d0 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 s returned immed
1a1e0 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e iately..** </li>
1a1f0 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ol>.**.**
1a200 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
1a210 20 5b 48 31 33 30 31 31 5d 20 5b 48 31 33 30 31 [H13011] [H1301
1a220 32 5d 20 5b 48 31 33 30 31 33 5d 20 5b 48 31 33 2] [H13013] [H13
1a230 30 31 34 5d 20 5b 48 31 33 30 31 35 5d 20 5b 48 014] [H13015] [H
1a240 31 33 30 31 36 5d 20 5b 48 31 33 30 31 39 5d 20 13016] [H13019]
1a250 5b 48 31 33 30 32 31 5d 0a 2a 2a 0a 2a 2f 0a 69 [H13021].**.*/.i
1a260 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nt sqlite3_prepa
1a270 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 re(. sqlite3 *d
1a280 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a b, /*
1a290 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 Database handle
1a2a0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
1a2b0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a *zSql, /*
1a2c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 SQL statement,
1a2d0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f UTF-8 encoded */
1a2e0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 . int nByte,
1a2f0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 /* Ma
1a300 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
1a310 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a zSql in bytes. *
1a320 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 /. sqlite3_stmt
1a330 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f **ppStmt, /* O
1a340 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 UT: Statement ha
1a350 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
1a360 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 char **pzTail
1a370 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 /* OUT: Pointe
1a380 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 r to unused port
1a390 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 ion of zSql */.)
1a3a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 ;.int sqlite3_pr
1a3b0 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 epare_v2(. sqli
1a3c0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
1a3d0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
1a3e0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
1a3f0 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 t char *zSql,
1a400 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 /* SQL state
1a410 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f ment, UTF-8 enco
1a420 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 ded */. int nBy
1a430 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 te,
1a440 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 /* Maximum leng
1a450 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 th of zSql in by
1a460 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 tes. */. sqlite
1a470 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 3_stmt **ppStmt,
1a480 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d /* OUT: Statem
1a490 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ent handle */.
1a4a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 const char **pzT
1a4b0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 ail /* OUT:
1a4c0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 Pointer to unuse
1a4d0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 d portion of zSq
1a4e0 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 l */.);.int sqli
1a4f0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 te3_prepare16(.
1a500 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
1a510 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
1a520 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 base handle */.
1a530 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 const void *zSq
1a540 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 l, /* SQL
1a550 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 statement, UTF-1
1a560 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6 encoded */. i
1a570 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 nt nByte,
1a580 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 /* Maximu
1a590 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c m length of zSql
1a5a0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 in bytes. */.
1a5b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 sqlite3_stmt **p
1a5c0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 pStmt, /* OUT:
1a5d0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 Statement handle
1a5e0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 */. const void
1a5f0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a **pzTail /*
1a600 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f OUT: Pointer to
1a610 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 unused portion
1a620 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e of zSql */.);.in
1a630 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 t sqlite3_prepar
1a640 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 e16_v2(. sqlite
1a650 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
1a660 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 /* Database ha
1a670 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
1a680 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 void *zSql,
1a690 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 /* SQL stateme
1a6a0 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 nt, UTF-16 encod
1a6b0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 ed */. int nByt
1a6c0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 e,
1a6d0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 /* Maximum lengt
1a6e0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 h of zSql in byt
1a6f0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 es. */. sqlite3
1a700 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 _stmt **ppStmt,
1a710 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 /* OUT: Stateme
1a720 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 nt handle */. c
1a730 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 onst void **pzTa
1a740 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 il /* OUT: P
1a750 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 ointer to unused
1a760 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c portion of zSql
1a770 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.);../*.** CA
1a780 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 PI3REF: Retrievi
1a790 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c ng Statement SQL
1a7a0 20 7b 48 31 33 31 30 30 7d 20 3c 48 31 33 30 30 {H13100} <H1300
1a7b0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 0>.**.** This in
1a7c0 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 terface can be u
1a7d0 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 sed to retrieve
1a7e0 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 a saved copy of
1a7f0 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 the original.**
1a800 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f SQL text used to
1a810 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 create a [prepa
1a820 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 red statement] i
1a830 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 f that statement
1a840 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 was.** compiled
1a850 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 using either [s
1a860 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1a870 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 2()] or [sqlite3
1a880 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
1a890 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
1a8a0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 31 30 31 ents:.** [H13101
1a8b0 5d 20 5b 48 31 33 31 30 32 5d 20 5b 48 31 33 31 ] [H13102] [H131
1a8c0 30 33 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 03].*/.const cha
1a8d0 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 r *sqlite3_sql(s
1a8e0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
1a8f0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
1a900 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 3REF: Dynamicall
1a910 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 y Typed Value Ob
1a920 6a 65 63 74 20 7b 48 31 35 30 30 30 7d 20 3c 53 ject {H15000} <S
1a930 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 20200>.** KEYWOR
1a940 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 DS: {protected s
1a950 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 qlite3_value} {u
1a960 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
1a970 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 e3_value}.**.**
1a980 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 SQLite uses the
1a990 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
1a9a0 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e ject to represen
1a9b0 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 t all values.**
1a9c0 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 that can be stor
1a9d0 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 ed in a database
1a9e0 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 table. SQLite u
1a9f0 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 ses dynamic typi
1aa00 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 ng.** for the va
1aa10 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 lues it stores.
1aa20 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e Values stored in
1aa30 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
1aa40 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 bjects.** can be
1aa50 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 integers, float
1aa60 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 ing point values
1aa70 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 , strings, BLOBs
1aa80 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a , or NULL..**.**
1aa90 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 An sqlite3_valu
1aaa0 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 e object may be
1aab0 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 either "protecte
1aac0 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 d" or "unprotect
1aad0 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 ed"..** Some int
1aae0 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 erfaces require
1aaf0 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 a protected sqli
1ab00 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 te3_value. Othe
1ab10 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 r interfaces.**
1ab20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 will accept eith
1ab30 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f er a protected o
1ab40 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 r an unprotected
1ab50 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a sqlite3_value..
1ab60 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 ** Every interfa
1ab70 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 ce that accepts
1ab80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 sqlite3_value ar
1ab90 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 guments specifie
1aba0 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 s.** whether or
1abb0 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 not it requires
1abc0 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 a protected sqli
1abd0 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a te3_value..**.**
1abe0 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 The terms "prot
1abf0 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 ected" and "unpr
1ac00 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74 otected" refer t
1ac10 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 o whether or not
1ac20 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 .** a mutex is h
1ac30 65 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c eld. A internal
1ac40 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 mutex is held f
1ac50 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a or a protected.*
1ac60 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 * sqlite3_value
1ac70 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 object but no mu
1ac80 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 tex is held for
1ac90 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a an unprotected.*
1aca0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 * sqlite3_value
1acb0 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 object. If SQLi
1acc0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 te is compiled t
1acd0 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 o be single-thre
1ace0 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 aded.** (with [S
1acf0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
1ad00 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 =0] and with [sq
1ad10 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 lite3_threadsafe
1ad20 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 ()] returning 0)
1ad30 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 .** or if SQLite
1ad40 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f is run in one o
1ad50 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 f reduced mutex
1ad60 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 modes .** [SQLIT
1ad70 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
1ad80 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 HREAD] or [SQLIT
1ad90 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 E_CONFIG_MULTITH
1ada0 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 READ].** then th
1adb0 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e ere is no distin
1adc0 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 ction between pr
1add0 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 otected and unpr
1ade0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 otected.** sqlit
1adf0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
1ae00 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 and they can be
1ae10 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 used interchang
1ae20 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c eably. However,
1ae30 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 .** for maximum
1ae40 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 code portability
1ae50 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 it is recommend
1ae60 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 ed that applicat
1ae70 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 ions.** still ma
1ae80 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 ke the distincti
1ae90 6f 6e 20 62 65 74 77 65 65 6e 20 62 65 74 77 65 on between betwe
1aea0 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 en protected and
1aeb0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 unprotected.**
1aec0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
1aed0 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 jects even when
1aee0 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 not strictly req
1aef0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 uired..**.** The
1af00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
1af10 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 bjects that are
1af20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 passed as parame
1af30 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a ters into the.**
1af40 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
1af50 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d of [application-
1af60 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
1af70 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 tions] are prote
1af80 63 74 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c cted..** The sql
1af90 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
1afa0 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a t returned by.**
1afb0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
1afc0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 _value()] is unp
1afd0 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 rotected..** Unp
1afe0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
1aff0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d _value objects m
1b000 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 ay only be used
1b010 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 with.** [sqlite3
1b020 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d _result_value()]
1b030 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 and [sqlite3_bi
1b040 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 nd_value()]..**
1b050 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c The [sqlite3_val
1b060 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 ue_blob | sqlite
1b070 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 3_value_type()]
1b080 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 family of.** int
1b090 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 erfaces require
1b0a0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
1b0b0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 3_value objects.
1b0c0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
1b0d0 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 ct Mem sqlite3_v
1b0e0 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 alue;../*.** CAP
1b0f0 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 I3REF: SQL Funct
1b100 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 ion Context Obje
1b110 63 74 20 7b 48 31 36 30 30 31 7d 20 3c 53 32 30 ct {H16001} <S20
1b120 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 200>.**.** The c
1b130 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 ontext in which
1b140 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 an SQL function
1b150 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 executes is stor
1b160 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 ed in an.** sqli
1b170 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 te3_context obje
1b180 63 74 2e 20 20 41 20 70 6f 69 6e 74 65 72 20 74 ct. A pointer t
1b190 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e o an sqlite3_con
1b1a0 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 text object.** i
1b1b0 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 s always first p
1b1c0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 arameter to [app
1b1d0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
1b1e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e SQL functions].
1b1f0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
1b200 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
1b210 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 function impleme
1b220 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 ntation will pas
1b230 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 s this.** pointe
1b240 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 r through into c
1b250 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
1b260 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 _result_int | sq
1b270 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c lite3_result()],
1b280 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 .** [sqlite3_agg
1b290 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 regate_context()
1b2a0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 ], [sqlite3_user
1b2b0 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 _data()],.** [sq
1b2c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 lite3_context_db
1b2d0 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c _handle()], [sql
1b2e0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 ite3_get_auxdata
1b2f0 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b ()],.** and/or [
1b300 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 sqlite3_set_auxd
1b310 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 ata()]..*/.typed
1b320 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
1b330 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 3_context sqlite
1b340 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 3_context;../*.*
1b350 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 * CAPI3REF: Bind
1b360 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 ing Values To Pr
1b370 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 epared Statement
1b380 73 20 7b 48 31 33 35 30 30 7d 20 3c 53 37 30 33 s {H13500} <S703
1b390 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 00>.** KEYWORDS:
1b3a0 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 {host parameter
1b3b0 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 } {host paramete
1b3c0 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 rs} {host parame
1b3d0 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 ter name}.** KEY
1b3e0 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 WORDS: {SQL para
1b3f0 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 meter} {SQL para
1b400 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 meters} {paramet
1b410 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a er binding}.**.*
1b420 2a 20 49 6e 20 74 68 65 20 53 51 4c 20 73 74 72 * In the SQL str
1b430 69 6e 67 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 ings input to [s
1b440 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1b450 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 2()] and its var
1b460 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 iants,.** litera
1b470 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 ls may be replac
1b480 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 ed by a [paramet
1b490 65 72 5d 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 er] in one of th
1b4a0 65 73 65 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a ese forms:.**.**
1b4b0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f <ul>.** <li> ?
1b4c0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a .** <li> ?NNN.*
1b4d0 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 * <li> :VVV.**
1b4e0 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c <li> @VVV.** <l
1b4f0 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c i> $VVV.** </ul
1b500 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70 >.**.** In the p
1b510 61 72 61 6d 65 74 65 72 20 66 6f 72 6d 73 20 73 arameter forms s
1b520 68 6f 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69 hown above NNN i
1b530 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 s an integer lit
1b540 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 eral,.** and VVV
1b550 20 69 73 20 61 6e 20 61 6c 70 68 61 2d 6e 75 6d is an alpha-num
1b560 65 72 69 63 20 70 61 72 61 6d 65 74 65 72 20 6e eric parameter n
1b570 61 6d 65 2e 20 54 68 65 20 76 61 6c 75 65 73 20 ame. The values
1b580 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 of these.** para
1b590 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c meters (also cal
1b5a0 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 led "host parame
1b5b0 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 ter names" or "S
1b5c0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a QL parameters").
1b5d0 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 ** can be set us
1b5e0 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f ing the sqlite3_
1b5f0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 bind_*() routine
1b600 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a s defined here..
1b610 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
1b620 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
1b630 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 sqlite3_bind_*()
1b640 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 routines is alw
1b650 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 ays.** a pointer
1b660 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
1b670 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 _stmt] object re
1b680 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b turned from.** [
1b690 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
1b6a0 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 v2()] or its var
1b6b0 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 iants..**.** The
1b6c0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
1b6d0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 is the index of
1b6e0 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 the SQL paramet
1b6f0 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a er to be set..**
1b700 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 The leftmost SQ
1b710 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 L parameter has
1b720 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 an index of 1.
1b730 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 When the same na
1b740 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d med.** SQL param
1b750 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 eter is used mor
1b760 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 e than once, sec
1b770 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 ond and subseque
1b780 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 nt.** occurrence
1b790 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 s have the same
1b7a0 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72 index as the fir
1b7b0 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a st occurrence..*
1b7c0 2a 20 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 * The index for
1b7d0 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 named parameters
1b7e0 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 can be looked u
1b7f0 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b p using the.** [
1b800 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
1b810 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 ameter_index()]
1b820 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 API if desired.
1b830 20 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f The index.** fo
1b840 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 r "?NNN" paramet
1b850 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 ers is the value
1b860 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20 of NNN..** The
1b870 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 NNN value must b
1b880 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 e between 1 and
1b890 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d the [sqlite3_lim
1b8a0 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 it()].** paramet
1b8b0 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 er [SQLITE_LIMIT
1b8c0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 _VARIABLE_NUMBER
1b8d0 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 ] (default value
1b8e0 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 : 999)..**.** Th
1b8f0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 e third argument
1b900 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f is the value to
1b910 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 bind to the par
1b920 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e ameter..**.** In
1b930 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 those routines
1b940 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 that have a four
1b950 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 th argument, its
1b960 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a value is the.**
1b970 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
1b980 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 in the paramete
1b990 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a r. To be clear:
1b9a0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 the value is th
1b9b0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c e.** number of <
1b9c0 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 u>bytes</u> in t
1b9d0 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 he value, not th
1b9e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 e number of char
1b9f0 61 63 74 65 72 73 2e 0a 2a 2a 20 49 66 20 74 68 acters..** If th
1ba00 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
1ba10 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 er is negative,
1ba20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 the length of th
1ba30 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 e string is.** t
1ba40 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
1ba50 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 es up to the fir
1ba60 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 st zero terminat
1ba70 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 or..**.** The fi
1ba80 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 fth argument to
1ba90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
1baa0 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e b(), sqlite3_bin
1bab0 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a d_text(), and.**
1bac0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
1bad0 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74 xt16() is a dest
1bae0 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 ructor used to d
1baf0 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c ispose of the BL
1bb00 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 OB or.** string
1bb10 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 after SQLite has
1bb20 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 finished with i
1bb30 74 2e 20 49 66 20 74 68 65 20 66 69 66 74 68 20 t. If the fifth
1bb40 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 argument is.** t
1bb50 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 he special value
1bb60 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d [SQLITE_STATIC]
1bb70 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 , then SQLite as
1bb80 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a sumes that the.*
1bb90 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 * information is
1bba0 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 in static, unma
1bbb0 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 naged space and
1bbc0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f does not need to
1bbd0 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 be freed..** If
1bbe0 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d the fifth argum
1bbf0 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 ent has the valu
1bc00 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 e [SQLITE_TRANSI
1bc10 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 ENT], then.** SQ
1bc20 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f Lite makes its o
1bc30 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 wn private copy
1bc40 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 of the data imme
1bc50 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a diately, before.
1bc60 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 ** the sqlite3_b
1bc70 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 ind_*() routine
1bc80 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 returns..**.** T
1bc90 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
1bca0 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 zeroblob() routi
1bcb0 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 ne binds a BLOB
1bcc0 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 of length N that
1bcd0 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 .** is filled wi
1bce0 74 68 20 7a 65 72 6f 65 73 2e 20 20 41 20 7a 65 th zeroes. A ze
1bcf0 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 roblob uses a fi
1bd00 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 xed amount of me
1bd10 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e mory.** (just an
1bd20 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 integer to hold
1bd30 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 its size) while
1bd40 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f it is being pro
1bd50 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 cessed..** Zerob
1bd60 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 lobs are intende
1bd70 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c d to serve as pl
1bd80 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 aceholders for B
1bd90 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f LOBs whose.** co
1bda0 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 ntent is later w
1bdb0 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 ritten using.**
1bdc0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 [sqlite3_blob_op
1bdd0 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c en | incremental
1bde0 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 BLOB I/O] routi
1bdf0 6e 65 73 2e 0a 2a 2a 20 41 20 6e 65 67 61 74 69 nes..** A negati
1be00 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 ve value for the
1be10 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 zeroblob result
1be20 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 s in a zero-leng
1be30 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 th BLOB..**.** T
1be40 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
1be50 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 *() routines mus
1be60 74 20 62 65 20 63 61 6c 6c 65 64 20 61 66 74 65 t be called afte
1be70 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 r.** [sqlite3_pr
1be80 65 70 61 72 65 5f 76 32 28 29 5d 20 28 61 6e 64 epare_v2()] (and
1be90 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 6f its variants) o
1bea0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 r [sqlite3_reset
1beb0 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72 ()] and.** befor
1bec0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 e [sqlite3_step(
1bed0 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20 )]..** Bindings
1bee0 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 are not cleared
1bef0 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f by the [sqlite3_
1bf00 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 reset()] routine
1bf10 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72 ..** Unbound par
1bf20 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 ameters are inte
1bf30 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e rpreted as NULL.
1bf40 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
1bf50 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 tines return [SQ
1bf60 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 LITE_OK] on succ
1bf70 65 73 73 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 ess or an error
1bf80 63 6f 64 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68 code if.** anyth
1bf90 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20 ing goes wrong.
1bfa0 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 [SQLITE_RANGE]
1bfb0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 is returned if t
1bfc0 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 he parameter.**
1bfd0 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 index is out of
1bfe0 72 61 6e 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f range. [SQLITE_
1bff0 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e NOMEM] is return
1c000 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 ed if malloc() f
1c010 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 ails..** [SQLITE
1c020 5f 4d 49 53 55 53 45 5d 20 6d 69 67 68 74 20 62 _MISUSE] might b
1c030 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 e returned if th
1c040 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
1c050 20 63 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20 called on a.**
1c060 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 virtual machine
1c070 74 68 61 74 20 69 73 20 74 68 65 20 77 72 6f 6e that is the wron
1c080 67 20 73 74 61 74 65 20 6f 72 20 77 68 69 63 68 g state or which
1c090 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 65 65 has already bee
1c0a0 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 n finalized..**
1c0b0 44 65 74 65 63 74 69 6f 6e 20 6f 66 20 6d 69 73 Detection of mis
1c0c0 75 73 65 20 69 73 20 75 6e 72 65 6c 69 61 62 6c use is unreliabl
1c0d0 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 e. Applications
1c0e0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 64 65 70 65 should not depe
1c0f0 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 5f nd.** on SQLITE_
1c100 4d 49 53 55 53 45 20 72 65 74 75 72 6e 73 2e 20 MISUSE returns.
1c110 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 69 SQLITE_MISUSE i
1c120 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 69 6e s intended to in
1c130 64 69 63 61 74 65 20 61 0a 2a 2a 20 61 20 6c 6f dicate a.** a lo
1c140 67 69 63 20 65 72 72 6f 72 20 69 6e 20 74 68 65 gic error in the
1c150 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 46 application. F
1c160 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f uture versions o
1c170 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a f SQLite might.*
1c180 2a 20 70 61 6e 69 63 20 72 61 74 68 65 72 20 74 * panic rather t
1c190 68 61 6e 20 72 65 74 75 72 6e 20 53 51 4c 49 54 han return SQLIT
1c1a0 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 E_MISUSE..**.**
1c1b0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
1c1c0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
1c1d0 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b r_count()],.** [
1c1e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
1c1f0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 ameter_name()],
1c200 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e and [sqlite3_bin
1c210 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 d_parameter_inde
1c220 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 x()]..**.** Requ
1c230 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
1c240 33 35 30 36 5d 20 5b 48 31 33 35 30 39 5d 20 5b 3506] [H13509] [
1c250 48 31 33 35 31 32 5d 20 5b 48 31 33 35 31 35 5d H13512] [H13515]
1c260 20 5b 48 31 33 35 31 38 5d 20 5b 48 31 33 35 32 [H13518] [H1352
1c270 31 5d 20 5b 48 31 33 35 32 34 5d 20 5b 48 31 33 1] [H13524] [H13
1c280 35 32 37 5d 0a 2a 2a 20 5b 48 31 33 35 33 30 5d 527].** [H13530]
1c290 20 5b 48 31 33 35 33 33 5d 20 5b 48 31 33 35 33 [H13533] [H1353
1c2a0 36 5d 20 5b 48 31 33 35 33 39 5d 20 5b 48 31 33 6] [H13539] [H13
1c2b0 35 34 32 5d 20 5b 48 31 33 35 34 35 5d 20 5b 48 542] [H13545] [H
1c2c0 31 33 35 34 38 5d 20 5b 48 31 33 35 35 31 5d 0a 13548] [H13551].
1c2d0 2a 2a 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 **.*/.int sqlite
1c2e0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 3_bind_blob(sqli
1c2f0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
1c300 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
1c310 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 n, void(*)(void
1c320 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 *));.int sqlite3
1c330 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c _bind_double(sql
1c340 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
1c350 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 double);.int sq
1c360 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 lite3_bind_int(s
1c370 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
1c380 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c t, int);.int sql
1c390 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 ite3_bind_int64(
1c3a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
1c3b0 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 nt, sqlite3_int6
1c3c0 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 4);.int sqlite3_
1c3d0 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 bind_null(sqlite
1c3e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 3_stmt*, int);.i
1c3f0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
1c400 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d text(sqlite3_stm
1c410 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 t*, int, const c
1c420 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 har*, int n, voi
1c430 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e d(*)(void*));.in
1c440 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 t sqlite3_bind_t
1c450 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ext16(sqlite3_st
1c460 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 mt*, int, const
1c470 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 void*, int, void
1c480 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 (*)(void*));.int
1c490 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 sqlite3_bind_va
1c4a0 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 lue(sqlite3_stmt
1c4b0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 *, int, const sq
1c4c0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 lite3_value*);.i
1c4d0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
1c4e0 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 zeroblob(sqlite3
1c4f0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 _stmt*, int, int
1c500 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 n);../*.** CAPI
1c510 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 3REF: Number Of
1c520 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 20 7b SQL Parameters {
1c530 48 31 33 36 30 30 7d 20 3c 53 37 30 33 30 30 3e H13600} <S70300>
1c540 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
1c550 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ine can be used
1c560 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 to find the numb
1c570 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d er of [SQL param
1c580 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b eters].** in a [
1c590 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1c5a0 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 nt]. SQL parame
1c5b0 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 ters are tokens
1c5c0 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 of the.** form "
1c5d0 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 ?", "?NNN", ":AA
1c5e0 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 A", "$AAA", or "
1c5f0 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 @AAA" that serve
1c600 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 as.** placehold
1c610 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 ers for values t
1c620 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 hat are [sqlite3
1c630 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 _bind_blob | bou
1c640 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 nd].** to the pa
1c650 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 rameters at a la
1c660 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 ter time..**.**
1c670 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 This routine act
1c680 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 ually returns th
1c690 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c e index of the l
1c6a0 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 argest (rightmos
1c6b0 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e t).** parameter.
1c6c0 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 For all forms e
1c6d0 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 xcept ?NNN, this
1c6e0 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 will correspond
1c6f0 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 to the.** numbe
1c700 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 r of unique para
1c710 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 meters. If para
1c720 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e meters of the ?N
1c730 4e 4e 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 NN are used,.**
1c740 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 there may be gap
1c750 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a s in the list..*
1c760 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
1c770 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
1c780 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 b|sqlite3_bind()
1c790 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 ],.** [sqlite3_b
1c7a0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 ind_parameter_na
1c7b0 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 me()], and.** [s
1c7c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
1c7d0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a meter_index()]..
1c7e0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
1c7f0 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 30 31 5d 0a ts:.** [H13601].
1c800 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 */.int sqlite3_b
1c810 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f ind_parameter_co
1c820 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 unt(sqlite3_stmt
1c830 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
1c840 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 REF: Name Of A H
1c850 6f 73 74 20 50 61 72 61 6d 65 74 65 72 20 7b 48 ost Parameter {H
1c860 31 33 36 32 30 7d 20 3c 53 37 30 33 30 30 3e 0a 13620} <S70300>.
1c870 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
1c880 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ne returns a poi
1c890 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 61 6d 65 nter to the name
1c8a0 20 6f 66 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20 of the n-th.**
1c8b0 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 [SQL parameter]
1c8c0 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 in a [prepared s
1c8d0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51 tatement]..** SQ
1c8e0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 L parameters of
1c8f0 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 the form "?NNN"
1c900 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 or ":AAA" or "@A
1c910 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a AA" or "$AAA".**
1c920 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 have a name whi
1c930 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 ch is the string
1c940 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 "?NNN" or ":AAA
1c950 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 " or "@AAA" or "
1c960 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 $AAA".** respect
1c970 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 ively..** In oth
1c980 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e er words, the in
1c990 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 itial ":" or "$"
1c9a0 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a or "@" or "?".*
1c9b0 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 * is included as
1c9c0 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d part of the nam
1c9d0 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 73 e..** Parameters
1c9e0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 of the form "?"
1c9f0 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f without a follo
1ca00 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 wing integer hav
1ca10 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 e no name.** and
1ca20 20 61 72 65 20 61 6c 73 6f 20 72 65 66 65 72 72 are also referr
1ca30 65 64 20 74 6f 20 61 73 20 22 61 6e 6f 6e 79 6d ed to as "anonym
1ca40 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e ous parameters".
1ca50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 .**.** The first
1ca60 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 host parameter
1ca70 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 has an index of
1ca80 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 1, not 0..**.**
1ca90 49 66 20 74 68 65 20 76 61 6c 75 65 20 6e 20 69 If the value n i
1caa0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f s out of range o
1cab0 72 20 69 66 20 74 68 65 20 6e 2d 74 68 20 70 61 r if the n-th pa
1cac0 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 rameter is.** na
1cad0 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c meless, then NUL
1cae0 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 L is returned.
1caf0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 The returned str
1cb00 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 ing is.** always
1cb10 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 in UTF-8 encodi
1cb20 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e ng even if the n
1cb30 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 amed parameter w
1cb40 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 as.** originally
1cb50 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 specified as UT
1cb60 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 F-16 in [sqlite3
1cb70 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 _prepare16()] or
1cb80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
1cb90 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a pare16_v2()]..**
1cba0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
1cbb0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
1cbc0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d |sqlite3_bind()]
1cbd0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 ,.** [sqlite3_bi
1cbe0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 nd_parameter_cou
1cbf0 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 nt()], and.** [s
1cc00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
1cc10 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a meter_index()]..
1cc20 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
1cc30 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 32 31 5d 0a ts:.** [H13621].
1cc40 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 */.const char *s
1cc50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
1cc60 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 meter_name(sqlit
1cc70 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a e3_stmt*, int);.
1cc80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1cc90 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 Index Of A Para
1cca0 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 meter With A Giv
1ccb0 65 6e 20 4e 61 6d 65 20 7b 48 31 33 36 34 30 7d en Name {H13640}
1ccc0 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S70300>.**.**
1ccd0 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 Return the index
1cce0 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d of an SQL param
1ccf0 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e eter given its n
1cd00 61 6d 65 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 64 ame. The.** ind
1cd10 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 ex value returne
1cd20 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f d is suitable fo
1cd30 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63 r use as the sec
1cd40 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ond.** parameter
1cd50 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e to [sqlite3_bin
1cd60 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 d_blob|sqlite3_b
1cd70 69 6e 64 28 29 5d 2e 20 20 41 20 7a 65 72 6f 0a ind()]. A zero.
1cd80 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 ** is returned i
1cd90 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 f no matching pa
1cda0 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 rameter is found
1cdb0 2e 20 20 54 68 65 20 70 61 72 61 6d 65 74 65 72 . The parameter
1cdc0 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 .** name must be
1cdd0 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 given in UTF-8
1cde0 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 even if the orig
1cdf0 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a inal statement.*
1ce00 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 * was prepared f
1ce10 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 rom UTF-16 text
1ce20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 using [sqlite3_p
1ce30 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a repare16_v2()]..
1ce40 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
1ce50 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
1ce60 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 ob|sqlite3_bind(
1ce70 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
1ce80 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 bind_parameter_c
1ce90 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 ount()], and.**
1cea0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
1ceb0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d rameter_index()]
1cec0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
1ced0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 34 31 ents:.** [H13641
1cee0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ].*/.int sqlite3
1cef0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
1cf00 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 index(sqlite3_st
1cf10 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 mt*, const char
1cf20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *zName);../*.**
1cf30 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 CAPI3REF: Reset
1cf40 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 All Bindings On
1cf50 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 A Prepared State
1cf60 6d 65 6e 74 20 7b 48 31 33 36 36 30 7d 20 3c 53 ment {H13660} <S
1cf70 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 70300>.**.** Con
1cf80 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 trary to the int
1cf90 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 uition of many,
1cfa0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
1cfb0 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 ] does not reset
1cfc0 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 .** the [sqlite3
1cfd0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e _bind_blob | bin
1cfe0 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 dings] on a [pre
1cff0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
1d000 2e 0a 2a 2a 20 55 73 65 20 74 68 69 73 20 72 6f ..** Use this ro
1d010 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 utine to reset a
1d020 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 ll host paramete
1d030 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a rs to NULL..**.*
1d040 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
1d050 2a 2a 20 5b 48 31 33 36 36 31 5d 0a 2a 2f 0a 69 ** [H13661].*/.i
1d060 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 nt sqlite3_clear
1d070 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 _bindings(sqlite
1d080 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 3_stmt*);../*.**
1d090 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 CAPI3REF: Numbe
1d0a0 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 r Of Columns In
1d0b0 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b 48 31 A Result Set {H1
1d0c0 33 37 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 3710} <S10700>.*
1d0d0 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 *.** Return the
1d0e0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e number of column
1d0f0 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 s in the result
1d100 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 set returned by
1d110 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 the.** [prepared
1d120 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54 68 69 statement]. Thi
1d130 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e s routine return
1d140 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 s 0 if pStmt is
1d150 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d an SQL.** statem
1d160 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f ent that does no
1d170 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 t return data (f
1d180 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 or example an [U
1d190 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 52 PDATE])..**.** R
1d1a0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
1d1b0 5b 48 31 33 37 31 31 5d 0a 2a 2f 0a 69 6e 74 20 [H13711].*/.int
1d1c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 sqlite3_column_c
1d1d0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d ount(sqlite3_stm
1d1e0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
1d1f0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 * CAPI3REF: Colu
1d200 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 mn Names In A Re
1d210 73 75 6c 74 20 53 65 74 20 7b 48 31 33 37 32 30 sult Set {H13720
1d220 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a } <S10700>.**.**
1d230 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
1d240 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 return the name
1d250 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 assigned to a pa
1d260 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a rticular column.
1d270 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 ** in the result
1d280 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 set of a [SELEC
1d290 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 T] statement. T
1d2a0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d he sqlite3_colum
1d2b0 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 n_name().** inte
1d2c0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
1d2d0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 pointer to a zer
1d2e0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 o-terminated UTF
1d2f0 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 -8 string.** and
1d300 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
1d310 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 name16() returns
1d320 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
1d330 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a zero-terminated.
1d340 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 ** UTF-16 string
1d350 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 . The first par
1d360 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 ameter is the [p
1d370 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
1d380 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 t].** that imple
1d390 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 ments the [SELEC
1d3a0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 54 68 T] statement. Th
1d3b0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
1d3c0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c er is the.** col
1d3d0 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 umn number. The
1d3e0 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e leftmost column
1d3f0 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a is number 0..**
1d400 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 .** The returned
1d410 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 string pointer
1d420 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 is valid until e
1d430 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 ither the [prepa
1d440 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a red statement].*
1d450 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 * is destroyed b
1d460 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c y [sqlite3_final
1d470 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 ize()] or until
1d480 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f the next call to
1d490 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 .** sqlite3_colu
1d4a0 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c mn_name() or sql
1d4b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
1d4c0 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 16() on the same
1d4d0 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 column..**.** I
1d4e0 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 f sqlite3_malloc
1d4f0 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 () fails during
1d500 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f the processing o
1d510 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 f either routine
1d520 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 .** (for example
1d530 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 during a conver
1d540 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 sion from UTF-8
1d550 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 to UTF-16) then
1d560 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 a.** NULL pointe
1d570 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a r is returned..*
1d580 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 *.** The name of
1d590 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e a result column
1d5a0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 is the value of
1d5b0 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 the "AS" clause
1d5c0 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c for.** that col
1d5d0 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 umn, if there is
1d5e0 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 an AS clause.
1d5f0 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 If there is no A
1d600 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e S clause.** then
1d610 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
1d620 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 column is unspe
1d630 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 cified and may c
1d640 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e hange from.** on
1d650 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c e release of SQL
1d660 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e ite to the next.
1d670 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
1d680 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 32 31 5d nts:.** [H13721]
1d690 20 5b 48 31 33 37 32 33 5d 20 5b 48 31 33 37 32 [H13723] [H1372
1d6a0 34 5d 20 5b 48 31 33 37 32 35 5d 20 5b 48 31 33 4] [H13725] [H13
1d6b0 37 32 36 5d 20 5b 48 31 33 37 32 37 5d 0a 2a 2f 726] [H13727].*/
1d6c0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
1d6d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
1d6e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
1d6f0 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f int N);.const vo
1d700 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 id *sqlite3_colu
1d710 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 mn_name16(sqlite
1d720 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 3_stmt*, int N);
1d730 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1d740 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 : Source Of Data
1d750 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 In A Query Resu
1d760 6c 74 20 7b 48 31 33 37 34 30 7d 20 3c 53 31 30 lt {H13740} <S10
1d770 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 700>.**.** These
1d780 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 routines provid
1d790 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 e a means to det
1d7a0 65 72 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c 75 ermine what colu
1d7b0 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61 mn of what.** ta
1d7c0 62 6c 65 20 69 6e 20 77 68 69 63 68 20 64 61 74 ble in which dat
1d7d0 61 62 61 73 65 20 61 20 72 65 73 75 6c 74 20 6f abase a result o
1d7e0 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 f a [SELECT] sta
1d7f0 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f tement comes fro
1d800 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f m..** The name o
1d810 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f f the database o
1d820 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d r table or colum
1d830 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 n can be returne
1d840 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 d as.** either a
1d850 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 UTF-8 or UTF-16
1d860 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 string. The _d
1d870 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 atabase_ routine
1d880 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 s return.** the
1d890 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 database name, t
1d8a0 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 he _table_ routi
1d8b0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 nes return the t
1d8c0 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a able name, and.*
1d8d0 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f * the origin_ ro
1d8e0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 utines return th
1d8f0 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a e column name..*
1d900 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 * The returned s
1d910 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 tring is valid u
1d920 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 ntil the [prepar
1d930 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 ed statement] is
1d940 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 destroyed.** us
1d950 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e ing [sqlite3_fin
1d960 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 alize()] or unti
1d970 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 l the same infor
1d980 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 mation is reques
1d990 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 ted.** again in
1d9a0 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f a different enco
1d9b0 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ding..**.** The
1d9c0 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 names returned a
1d9d0 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 re the original
1d9e0 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 un-aliased names
1d9f0 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 of the.** datab
1da00 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 ase, table, and
1da10 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 column..**.** Th
1da20 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
1da30 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e to the followin
1da40 67 20 63 61 6c 6c 73 20 69 73 20 61 20 5b 70 72 g calls is a [pr
1da50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1da60 5d 2e 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 ]..** These func
1da70 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 tions return inf
1da80 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 ormation about t
1da90 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 he Nth column re
1daa0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 turned by.** the
1dab0 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 statement, wher
1dac0 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e e N is the secon
1dad0 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d d function argum
1dae0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ent..**.** If th
1daf0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 e Nth column ret
1db00 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 urned by the sta
1db10 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 tement is an exp
1db20 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 ression or.** su
1db30 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f bquery and is no
1db40 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 t a column value
1db50 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 , then all of th
1db60 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 ese functions re
1db70 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 54 turn.** NULL. T
1db80 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 hese routine mig
1db90 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e ht also return N
1dba0 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 ULL if a memory
1dbb0 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 allocation error
1dbc0 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 4f 74 68 .** occurs. Oth
1dbd0 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 erwise, they ret
1dbe0 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 urn the name of
1dbf0 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 the attached dat
1dc00 61 62 61 73 65 2c 20 74 61 62 6c 65 0a 2a 2a 20 abase, table.**
1dc10 61 6e 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 and column that
1dc20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c query result col
1dc30 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 umn was extracte
1dc40 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 d from..**.** As
1dc50 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 with all other
1dc60 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f SQLite APIs, tho
1dc70 73 65 20 70 6f 73 74 66 69 78 65 64 20 77 69 74 se postfixed wit
1dc80 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a h "16" return.**
1dc90 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 UTF-16 encoded
1dca0 73 74 72 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 strings, the oth
1dcb0 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 er functions ret
1dcc0 75 72 6e 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d urn UTF-8. {END}
1dcd0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 .**.** These API
1dce0 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c s are only avail
1dcf0 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 able if the libr
1dd00 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 ary was compiled
1dd10 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 with the.** [SQ
1dd20 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 LITE_ENABLE_COLU
1dd30 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 MN_METADATA] C-p
1dd40 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 reprocessor symb
1dd50 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a ol defined..**.*
1dd60 2a 20 7b 41 31 33 37 35 31 7d 0a 2a 2a 20 49 66 * {A13751}.** If
1dd70 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 two or more thr
1dd80 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 eads call one or
1dd90 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 more of these r
1dda0 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 outines against
1ddb0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 the same.** prep
1ddc0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 ared statement a
1ddd0 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 nd column at the
1dde0 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 same time then
1ddf0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a the results are.
1de00 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a ** undefined..**
1de10 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
1de20 3a 0a 2a 2a 20 5b 48 31 33 37 34 31 5d 20 5b 48 :.** [H13741] [H
1de30 31 33 37 34 32 5d 20 5b 48 31 33 37 34 33 5d 20 13742] [H13743]
1de40 5b 48 31 33 37 34 34 5d 20 5b 48 31 33 37 34 35 [H13744] [H13745
1de50 5d 20 5b 48 31 33 37 34 36 5d 20 5b 48 31 33 37 ] [H13746] [H137
1de60 34 38 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 48].**.** If two
1de70 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 or more threads
1de80 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 call one or mor
1de90 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f e.** [sqlite3_co
1dea0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 lumn_database_na
1deb0 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 me | column meta
1dec0 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d data interfaces]
1ded0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 .** for the same
1dee0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
1def0 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 ment] and result
1df00 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 column.** at th
1df10 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e e same time then
1df20 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 the results are
1df30 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 undefined..*/.c
1df40 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
1df50 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 e3_column_databa
1df60 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f se_name(sqlite3_
1df70 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 stmt*,int);.cons
1df80 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
1df90 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f column_database_
1dfa0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 name16(sqlite3_s
1dfb0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 tmt*,int);.const
1dfc0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 char *sqlite3_c
1dfd0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 olumn_table_name
1dfe0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
1dff0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 nt);.const void
1e000 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
1e010 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c table_name16(sql
1e020 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
1e030 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
1e040 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 ite3_column_orig
1e050 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f in_name(sqlite3_
1e060 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 stmt*,int);.cons
1e070 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
1e080 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 column_origin_na
1e090 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d me16(sqlite3_stm
1e0a0 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 t*,int);../*.**
1e0b0 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 CAPI3REF: Declar
1e0c0 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 ed Datatype Of A
1e0d0 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48 Query Result {H
1e0e0 31 33 37 36 30 7d 20 3c 53 31 30 37 30 30 3e 0a 13760} <S10700>.
1e0f0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
1e100 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b parameter is a [
1e110 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1e120 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 nt]..** If this
1e130 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b statement is a [
1e140 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
1e150 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f t and the Nth co
1e160 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 lumn of the.** r
1e170 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 eturned result s
1e180 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 et of that [SELE
1e190 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 CT] is a table c
1e1a0 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a olumn (not an.**
1e1b0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 expression or s
1e1c0 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 ubquery) then th
1e1d0 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 e declared type
1e1e0 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 of the table.**
1e1f0 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e column is return
1e200 65 64 2e 20 20 49 66 20 74 68 65 20 4e 74 68 20 ed. If the Nth
1e210 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 column of the re
1e220 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a sult set is an.*
1e230 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 * expression or
1e240 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 subquery, then a
1e250 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 NULL pointer is
1e260 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 returned..** Th
1e270 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e e returned strin
1e280 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d g is always UTF-
1e290 38 20 65 6e 63 6f 64 65 64 2e 20 7b 45 4e 44 7d 8 encoded. {END}
1e2a0 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 .**.** For examp
1e2b0 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 le, given the da
1e2c0 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a tabase schema:.*
1e2d0 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c *.** CREATE TABL
1e2e0 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 E t1(c1 VARIANT)
1e2f0 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 ;.**.** and the
1e300 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d following statem
1e310 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c ent to be compil
1e320 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 ed:.**.** SELECT
1e330 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d c1 + 1, c1 FROM
1e340 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 t1;.**.** this
1e350 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 routine would re
1e360 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 turn the string
1e370 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 "VARIANT" for th
1e380 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a e second result.
1e390 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 ** column (i==1)
1e3a0 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 , and a NULL poi
1e3b0 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 nter for the fir
1e3c0 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e st result column
1e3d0 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 (i==0)..**.** S
1e3e0 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d QLite uses dynam
1e3f0 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 ic run-time typi
1e400 6e 67 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63 ng. So just bec
1e410 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a ause a column.**
1e420 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 is declared to
1e430 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 contain a partic
1e440 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e ular type does n
1e450 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 ot mean that the
1e460 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 .** data stored
1e470 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 in that column i
1e480 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 s of the declare
1e490 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 d type. SQLite
1e4a0 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 is.** strongly t
1e4b0 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 yped, but the ty
1e4c0 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 ping is dynamic
1e4d0 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 54 79 70 not static. Typ
1e4e0 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 e.** is associat
1e4f0 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 ed with individu
1e500 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 al values, not w
1e510 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 ith the containe
1e520 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f rs.** used to ho
1e530 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e ld those values.
1e540 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
1e550 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 36 31 5d nts:.** [H13761]
1e560 20 5b 48 31 33 37 36 32 5d 20 5b 48 31 33 37 36 [H13762] [H1376
1e570 33 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 3].*/.const char
1e580 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
1e590 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 _decltype(sqlite
1e5a0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 3_stmt*,int);.co
1e5b0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
1e5c0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 3_column_decltyp
1e5d0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 e16(sqlite3_stmt
1e5e0 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 *,int);../*.** C
1e5f0 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 API3REF: Evaluat
1e600 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 e An SQL Stateme
1e610 6e 74 20 7b 48 31 33 32 30 30 7d 20 3c 53 31 30 nt {H13200} <S10
1e620 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 000>.**.** After
1e630 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
1e640 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e tement] has been
1e650 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 prepared using
1e660 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 either.** [sqlit
1e670 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
1e680 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 or [sqlite3_pre
1e690 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 pare16_v2()] or
1e6a0 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 one of the legac
1e6b0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 y.** interfaces
1e6c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1e6d0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
1e6e0 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 prepare16()], th
1e6f0 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d is function.** m
1e700 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e ust be called on
1e710 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 e or more times
1e720 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 to evaluate the
1e730 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a statement..**.**
1e740 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 The details of
1e750 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 the behavior of
1e760 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 the sqlite3_step
1e770 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 () interface dep
1e780 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 end.** on whethe
1e790 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 r the statement
1e7a0 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69 was prepared usi
1e7b0 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 ng the newer "v2
1e7c0 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b " interface.** [
1e7d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
1e7e0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 v2()] and [sqlit
1e7f0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
1e800 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 )] or the older
1e810 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 legacy.** interf
1e820 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 ace [sqlite3_pre
1e830 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c pare()] and [sql
1e840 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
1e850 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 ]. The use of t
1e860 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 he.** new "v2" i
1e870 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f nterface is reco
1e880 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 mmended for new
1e890 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 applications but
1e8a0 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 the legacy.** i
1e8b0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f nterface will co
1e8c0 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 ntinue to be sup
1e8d0 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e ported..**.** In
1e8e0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 the legacy inte
1e8f0 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 rface, the retur
1e900 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 n value will be
1e910 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 either [SQLITE_B
1e920 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 USY],.** [SQLITE
1e930 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f _DONE], [SQLITE_
1e940 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 ROW], [SQLITE_ER
1e950 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 ROR], or [SQLITE
1e960 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 _MISUSE]..** Wit
1e970 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 h the "v2" inter
1e980 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 face, any of the
1e990 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 other [result c
1e9a0 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 odes] or.** [ext
1e9b0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
1e9c0 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 es] might be ret
1e9d0 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a urned as well..*
1e9e0 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 *.** [SQLITE_BUS
1e9f0 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 Y] means that th
1ea00 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e e database engin
1ea10 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 e was unable to
1ea20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 acquire the.** d
1ea30 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 atabase locks it
1ea40 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 needs to do its
1ea50 20 6a 6f 62 2e 20 20 49 66 20 74 68 65 20 73 74 job. If the st
1ea60 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f atement is a [CO
1ea70 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 MMIT].** or occu
1ea80 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e rs outside of an
1ea90 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 explicit transa
1eaa0 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 ction, then you
1eab0 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a can retry the.**
1eac0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 statement. If
1ead0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 the statement is
1eae0 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 not a [COMMIT]
1eaf0 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 and occurs withi
1eb00 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 n a.** explicit
1eb10 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e transaction then
1eb20 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c you should roll
1eb30 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 back the transac
1eb40 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 tion before.** c
1eb50 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a ontinuing..**.**
1eb60 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d [SQLITE_DONE] m
1eb70 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 eans that the st
1eb80 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 atement has fini
1eb90 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a shed executing.*
1eba0 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 * successfully.
1ebb0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
1ebc0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 should not be ca
1ebd0 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 lled again on th
1ebe0 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 is virtual.** ma
1ebf0 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 chine without fi
1ec00 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c rst calling [sql
1ec10 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f ite3_reset()] to
1ec20 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 reset the virtu
1ec30 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 al.** machine ba
1ec40 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 ck to its initia
1ec50 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 l state..**.** I
1ec60 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d f the SQL statem
1ec70 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 ent being execut
1ec80 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 ed returns any d
1ec90 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 ata, then [SQLIT
1eca0 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 E_ROW].** is ret
1ecb0 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 urned each time
1ecc0 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 a new row of dat
1ecd0 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 a is ready for p
1ece0 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 rocessing by the
1ecf0 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 .** caller. The
1ed00 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 values may be ac
1ed10 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 cessed using the
1ed20 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 [column access
1ed30 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 functions]..** s
1ed40 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 qlite3_step() is
1ed50 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f called again to
1ed60 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 retrieve the ne
1ed70 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a xt row of data..
1ed80 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 **.** [SQLITE_ER
1ed90 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 ROR] means that
1eda0 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 a run-time error
1edb0 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 (such as a cons
1edc0 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 traint.** violat
1edd0 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 ion) has occurre
1ede0 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 d. sqlite3_step
1edf0 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 () should not be
1ee00 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e called again on
1ee10 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 .** the VM. More
1ee20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 information may
1ee30 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c be found by cal
1ee40 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 ling [sqlite3_er
1ee50 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 rmsg()]..** With
1ee60 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 the legacy inte
1ee70 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 rface, a more sp
1ee80 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 ecific error cod
1ee90 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a e (for example,.
1eea0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 ** [SQLITE_INTER
1eeb0 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 RUPT], [SQLITE_S
1eec0 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f CHEMA], [SQLITE_
1eed0 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f CORRUPT], and so
1eee0 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 forth).** can b
1eef0 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 e obtained by ca
1ef00 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 lling [sqlite3_r
1ef10 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a eset()] on the.*
1ef20 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 * [prepared stat
1ef30 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20 ement]. In the
1ef40 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a "v2" interface,.
1ef50 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 ** the more spec
1ef60 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 ific error code
1ef70 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 is returned dire
1ef80 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f ctly by sqlite3_
1ef90 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 step()..**.** [S
1efa0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 QLITE_MISUSE] me
1efb0 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69 ans that the thi
1efc0 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 s routine was ca
1efd0 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 lled inappropria
1efe0 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 tely..** Perhaps
1eff0 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f it was called o
1f000 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 n a [prepared st
1f010 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 atement] that ha
1f020 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 s.** already bee
1f030 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c n [sqlite3_final
1f040 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d ize | finalized]
1f050 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 or on one that
1f060 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c had.** previousl
1f070 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 y returned [SQLI
1f080 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 TE_ERROR] or [SQ
1f090 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 LITE_DONE]. Or
1f0a0 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 it could.** be t
1f0b0 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 he case that the
1f0c0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 same database c
1f0d0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 onnection is bei
1f0e0 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f ng used by two o
1f0f0 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 r.** more thread
1f100 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f s at the same mo
1f110 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a ment in time..**
1f120 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 .** <b>Goofy Int
1f130 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 erface Alert:</b
1f140 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 > In the legacy
1f150 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 interface, the s
1f160 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a qlite3_step().**
1f170 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 API always retu
1f180 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 rns a generic er
1f190 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 ror code, [SQLIT
1f1a0 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 E_ERROR], follow
1f1b0 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 ing any.** error
1f1c0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c other than [SQL
1f1d0 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 ITE_BUSY] and [S
1f1e0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 QLITE_MISUSE].
1f1f0 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a You must call.**
1f200 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
1f210 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 )] or [sqlite3_f
1f220 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 inalize()] in or
1f230 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 der to find one
1f240 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 of the.** specif
1f250 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d ic [error codes]
1f260 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 that better des
1f270 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 cribes the error
1f280 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 ..** We admit th
1f290 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f at this is a goo
1f2a0 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 fy design. The
1f2b0 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e problem has been
1f2c0 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 fixed.** with t
1f2d0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 he "v2" interfac
1f2e0 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 e. If you prepa
1f2f0 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 re all of your S
1f300 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a QL statements.**
1f310 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 using either [s
1f320 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1f330 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 2()] or [sqlite3
1f340 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
1f350 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 instead.** of t
1f360 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 he legacy [sqlit
1f370 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e e3_prepare()] an
1f380 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 d [sqlite3_prepa
1f390 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 re16()] interfac
1f3a0 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 es,.** then the
1f3b0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 more specific [e
1f3c0 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 rror codes] are
1f3d0 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c returned directl
1f3e0 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f y.** by sqlite3_
1f3f0 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 step(). The use
1f400 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 of the "v2" int
1f410 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d erface is recomm
1f420 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 ended..**.** Req
1f430 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
1f440 31 33 32 30 32 5d 20 5b 48 31 35 33 30 34 5d 20 13202] [H15304]
1f450 5b 48 31 35 33 30 36 5d 20 5b 48 31 35 33 30 38 [H15306] [H15308
1f460 5d 20 5b 48 31 35 33 31 30 5d 0a 2a 2f 0a 69 6e ] [H15310].*/.in
1f470 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 t sqlite3_step(s
1f480 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a qlite3_stmt*);..
1f490 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1f4a0 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e Number of column
1f4b0 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 s in a result se
1f4c0 74 20 7b 48 31 33 37 37 30 7d 20 3c 53 31 30 37 t {H13770} <S107
1f4d0 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 00>.**.** Return
1f4e0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
1f4f0 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20 63 75 values in the cu
1f500 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 rrent row of the
1f510 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a result set..**.
1f520 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
1f530 0a 2a 2a 20 5b 48 31 33 37 37 31 5d 20 5b 48 31 .** [H13771] [H1
1f540 33 37 37 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 3772].*/.int sql
1f550 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 ite3_data_count(
1f560 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
1f570 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tmt);../*.** CAP
1f580 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 I3REF: Fundament
1f590 61 6c 20 44 61 74 61 74 79 70 65 73 20 7b 48 31 al Datatypes {H1
1f5a0 30 32 36 35 7d 20 3c 53 31 30 31 31 30 3e 3c 53 0265} <S10110><S
1f5b0 31 30 31 32 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 10120>.** KEYWOR
1f5c0 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a DS: SQLITE_TEXT.
1f5d0 2a 2a 0a 2a 2a 20 7b 48 31 30 32 36 36 7d 20 45 **.** {H10266} E
1f5e0 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 very value in SQ
1f5f0 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 Lite has one of
1f600 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c five fundamental
1f610 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a datatypes:.**.*
1f620 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 * <ul>.** <li> 6
1f630 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 4-bit signed int
1f640 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d eger.** <li> 64-
1f650 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e bit IEEE floatin
1f660 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a g point number.*
1f670 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a * <li> string.**
1f680 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c <li> BLOB.** <l
1f690 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e i> NULL.** </ul>
1f6a0 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 {END}.**.** The
1f6b0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 se constants are
1f6c0 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 codes for each
1f6d0 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a of those types..
1f6e0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 **.** Note that
1f6f0 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 the SQLITE_TEXT
1f700 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 constant was als
1f710 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 o used in SQLite
1f720 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f version 2.** fo
1f730 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 r a completely d
1f740 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 ifferent meaning
1f750 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 . Software that
1f760 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 links against b
1f770 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 oth.** SQLite ve
1f780 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 rsion 2 and SQLi
1f790 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f te version 3 sho
1f7a0 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f uld use SQLITE3_
1f7b0 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c TEXT, not.** SQL
1f7c0 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 ITE_TEXT..*/.#de
1f7d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 fine SQLITE_INTE
1f7e0 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 GER 1.#define S
1f7f0 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 QLITE_FLOAT 2
1f800 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1f810 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 BLOB 4.#defi
1f820 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 ne SQLITE_NULL
1f830 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 5.#ifdef SQLI
1f840 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 TE_TEXT.# undef
1f850 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 SQLITE_TEXT.#els
1f860 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 e.# define SQLIT
1f870 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e E_TEXT 3.#en
1f880 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 dif.#define SQLI
1f890 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a TE3_TEXT 3..
1f8a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1f8b0 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 Result Values Fr
1f8c0 6f 6d 20 41 20 51 75 65 72 79 20 7b 48 31 33 38 om A Query {H138
1f8d0 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 00} <S10700>.**
1f8e0 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d KEYWORDS: {colum
1f8f0 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f n access functio
1f900 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ns}.**.** These
1f910 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 routines form th
1f920 65 20 22 72 65 73 75 6c 74 20 73 65 74 20 71 75 e "result set qu
1f930 65 72 79 22 20 69 6e 74 65 72 66 61 63 65 2e 0a ery" interface..
1f940 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
1f950 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f ines return info
1f960 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 rmation about a
1f970 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 single column of
1f980 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 the current.**
1f990 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 result row of a
1f9a0 71 75 65 72 79 2e 20 20 49 6e 20 65 76 65 72 79 query. In every
1f9b0 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 case the first
1f9c0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f argument is a po
1f9d0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 inter.** to the
1f9e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
1f9f0 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 ent] that is bei
1fa00 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 ng evaluated (th
1fa10 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a e [sqlite3_stmt*
1fa20 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 ].** that was re
1fa30 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c turned from [sql
1fa40 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
1fa50 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 )] or one of its
1fa60 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e variants).** an
1fa70 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 d the second arg
1fa80 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 ument is the ind
1fa90 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e ex of the column
1faa0 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 for which infor
1fab0 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 mation.** should
1fac0 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20 54 be returned. T
1fad0 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 he leftmost colu
1fae0 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 mn of the result
1faf0 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 set has the ind
1fb00 65 78 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 ex 0..**.** If t
1fb10 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
1fb20 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e does not curren
1fb30 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 tly point to a v
1fb40 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 alid row, or if
1fb50 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e the.** column in
1fb60 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 dex is out of ra
1fb70 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 nge, the result
1fb80 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a is undefined..**
1fb90 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
1fba0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c may only be call
1fbb0 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 ed when the most
1fbc0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a recent call to.
1fbd0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ** [sqlite3_step
1fbe0 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 ()] has returned
1fbf0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e [SQLITE_ROW] an
1fc00 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 d neither.** [sq
1fc10 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e lite3_reset()] n
1fc20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 or [sqlite3_fina
1fc30 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 lize()] have bee
1fc40 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 n called subsequ
1fc50 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 ently..** If any
1fc60 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e of these routin
1fc70 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 es are called af
1fc80 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ter [sqlite3_res
1fc90 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c et()] or.** [sql
1fca0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
1fcb0 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 or after [sqlit
1fcc0 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 e3_step()] has r
1fcd0 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 eturned.** somet
1fce0 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 hing other than
1fcf0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 [SQLITE_ROW], th
1fd00 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e e results are un
1fd10 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b defined..** If [
1fd20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
1fd30 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 or [sqlite3_rese
1fd40 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 t()] or [sqlite3
1fd50 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 _finalize()].**
1fd60 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 are called from
1fd70 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 a different thre
1fd80 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 ad while any of
1fd90 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a these routines.*
1fda0 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 * are pending, t
1fdb0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 hen the results
1fdc0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a are undefined..*
1fdd0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
1fde0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 _column_type() r
1fdf0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 outine returns t
1fe00 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e he.** [SQLITE_IN
1fe10 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 TEGER | datatype
1fe20 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 code] for the i
1fe30 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 nitial data type
1fe40 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c .** of the resul
1fe50 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72 t column. The r
1fe60 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 eturned value is
1fe70 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f one of [SQLITE_
1fe80 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 INTEGER],.** [SQ
1fe90 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 LITE_FLOAT], [SQ
1fea0 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c LITE_TEXT], [SQL
1feb0 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 ITE_BLOB], or [S
1fec0 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 QLITE_NULL]. Th
1fed0 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 e value.** retur
1fee0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 ned by sqlite3_c
1fef0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 olumn_type() is
1ff00 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 only meaningful
1ff10 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f if no type.** co
1ff20 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f nversions have o
1ff30 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72 ccurred as descr
1ff40 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 ibed below. Aft
1ff50 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 er a type conver
1ff60 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c sion,.** the val
1ff70 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ue returned by s
1ff80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 qlite3_column_ty
1ff90 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 pe() is undefine
1ffa0 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 d. Future.** ve
1ffb0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
1ffc0 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 may change the
1ffd0 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 behavior of sqli
1ffe0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 te3_column_type(
1fff0 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 ).** following a
20000 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e type conversion
20010 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 ..**.** If the r
20020 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 esult is a BLOB
20030 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 or UTF-8 string
20040 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 then the sqlite3
20050 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a _column_bytes().
20060 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 ** routine retur
20070 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
20080 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 bytes in that B
20090 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a LOB or string..*
200a0 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 * If the result
200b0 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 is a UTF-16 stri
200c0 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ng, then sqlite3
200d0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 _column_bytes()
200e0 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 converts.** the
200f0 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 string to UTF-8
20100 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 and then returns
20110 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
20120 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 ytes..** If the
20130 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 result is a nume
20140 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 ric value then s
20150 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
20160 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 tes() uses.** [s
20170 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
20180 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 )] to convert th
20190 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 at value to a UT
201a0 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 F-8 string and r
201b0 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 eturns.** the nu
201c0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e mber of bytes in
201d0 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a that string..**
201e0 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 The value retur
201f0 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 ned does not inc
20200 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 lude the zero te
20210 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20 rminator at the
20220 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 end.** of the st
20230 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72 69 ring. For clari
20240 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72 65 ty: the value re
20250 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e 75 turned is the nu
20260 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 mber of.** bytes
20270 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 in the string,
20280 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f not the number o
20290 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a f characters..**
202a0 0a 2a 2a 20 53 74 72 69 6e 67 73 20 72 65 74 75 .** Strings retu
202b0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
202c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e column_text() an
202d0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e d sqlite3_column
202e0 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 _text16(),.** ev
202f0 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 en empty strings
20300 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 , are always zer
20310 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 o terminated. T
20320 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c he return.** val
20330 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ue from sqlite3_
20340 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f column_blob() fo
20350 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 r a zero-length
20360 42 4c 4f 42 20 69 73 20 61 6e 20 61 72 62 69 74 BLOB is an arbit
20370 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c rary.** pointer,
20380 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 61 possibly even a
20390 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a NULL pointer..*
203a0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
203b0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
203c0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d ) routine is sim
203d0 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f ilar to sqlite3_
203e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a column_bytes().*
203f0 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74 68 65 * but leaves the
20400 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 result in UTF-1
20410 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 6 in native byte
20420 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f order instead o
20430 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 54 68 65 20 f UTF-8..** The
20440 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 zero terminator
20450 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 is not included
20460 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a in this count..*
20470 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a 65 63 74 20 *.** The object
20480 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c returned by [sql
20490 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 ite3_column_valu
204a0 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 e()] is an.** [u
204b0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
204c0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
204d0 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 . An unprotecte
204e0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 d sqlite3_value
204f0 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e object.** may on
20500 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20 ly be used with
20510 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 [sqlite3_bind_va
20520 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 lue()] and [sqli
20530 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 te3_result_value
20540 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b ()]..** If the [
20550 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
20560 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
20570 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a t returned by.**
20580 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
20590 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 _value()] is use
205a0 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 d in any other w
205b0 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 ay, including ca
205c0 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e lls.** to routin
205d0 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 es like [sqlite3
205e0 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b _value_int()], [
205f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
20600 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 xt()],.** or [sq
20610 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 lite3_value_byte
20620 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 s()], then the b
20630 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 ehavior is undef
20640 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ined..**.** Thes
20650 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d e routines attem
20660 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 pt to convert th
20670 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 e value where ap
20680 70 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a propriate. For.
20690 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 ** example, if t
206a0 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 he internal repr
206b0 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c esentation is FL
206c0 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 OAT and a text r
206d0 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 esult.** is requ
206e0 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f ested, [sqlite3_
206f0 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 snprintf()] is u
20700 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 sed internally t
20710 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a o perform the.**
20720 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f conversion auto
20730 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 matically. The
20740 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 following table
20750 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 details the conv
20760 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 ersions.** that
20770 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a are applied:.**.
20780 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a ** <blockquote>.
20790 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 ** <table border
207a0 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 ="1">.** <tr><th
207b0 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 > Internal<br>Ty
207c0 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 pe <th> Requeste
207d0 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 d<br>Type <th>
207e0 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a Conversion.**.**
207f0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 <tr><td> NULL
20800 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 <td> INTEGER
20810 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 <td> Result is
20820 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 0.** <tr><td>
20830 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c NULL <td> FL
20840 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 OAT <td> Resu
20850 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 lt is 0.0.** <tr
20860 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c ><td> NULL <
20870 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 td> TEXT <t
20880 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c d> Result is NUL
20890 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 L pointer.** <tr
208a0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c ><td> NULL <
208b0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 td> BLOB <t
208c0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c d> Result is NUL
208d0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 L pointer.** <tr
208e0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c ><td> INTEGER <
208f0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 td> FLOAT <t
20900 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 d> Convert from
20910 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 integer to float
20920 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 .** <tr><td> INT
20930 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 EGER <td> TEX
20940 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 T <td> ASCII
20950 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 rendering of the
20960 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e integer.** <tr>
20970 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 <td> INTEGER <t
20980 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 d> BLOB <td
20990 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 > Same as INTEGE
209a0 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c R->TEXT.** <tr><
209b0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 td> FLOAT <td
209c0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e > INTEGER <td>
209d0 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c Convert from fl
209e0 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a oat to integer.*
209f0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 * <tr><td> FLOA
20a00 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 T <td> TEXT
20a10 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 <td> ASCII re
20a20 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 ndering of the f
20a30 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e loat.** <tr><td>
20a40 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 FLOAT <td>
20a50 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 BLOB <td> Sa
20a60 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 me as FLOAT->TEX
20a70 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 T.** <tr><td> T
20a80 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 EXT <td> INTE
20a90 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 GER <td> Use a
20aa0 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 toi().** <tr><td
20ab0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 > TEXT <td>
20ac0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 FLOAT <td> U
20ad0 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 se atof().** <tr
20ae0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c ><td> TEXT <
20af0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 td> BLOB <t
20b00 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 d> No change.**
20b10 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 <tr><td> BLOB
20b20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 <td> INTEGER
20b30 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f <td> Convert to
20b40 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 TEXT then use a
20b50 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 toi().** <tr><td
20b60 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 > BLOB <td>
20b70 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 FLOAT <td> C
20b80 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 onvert to TEXT t
20b90 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a hen use atof().*
20ba0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 * <tr><td> BLOB
20bb0 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 <td> TEXT
20bc0 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 <td> Add a ze
20bd0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 ro terminator if
20be0 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 needed.** </tab
20bf0 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 le>.** </blockqu
20c00 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 ote>.**.** The t
20c10 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 able above makes
20c20 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 reference to st
20c30 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 andard C library
20c40 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 functions atoi(
20c50 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e ).** and atof().
20c60 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f SQLite does no
20c70 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 t really use the
20c80 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 se functions. I
20c90 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e t has its.** own
20ca0 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 equivalent inte
20cb0 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 rnal routines.
20cc0 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 The atoi() and a
20cd0 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a tof() names are.
20ce0 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 ** used in the t
20cf0 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 able for brevity
20d00 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 and because the
20d10 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 y are familiar t
20d20 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 o most.** C prog
20d30 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e rammers..**.** N
20d40 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 ote that when ty
20d50 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f pe conversions o
20d60 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 ccur, pointers r
20d70 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 eturned by prior
20d80 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c .** calls to sql
20d90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 ite3_column_blob
20da0 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 (), sqlite3_colu
20db0 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f mn_text(), and/o
20dc0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c r.** sqlite3_col
20dd0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 umn_text16() may
20de0 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e be invalidated.
20df0 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 .** Type convers
20e00 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 ions and pointer
20e10 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d invalidations m
20e20 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e ight occur.** in
20e30 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 the following c
20e40 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e ases:.**.** <ul>
20e50 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 .** <li> The ini
20e60 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 tial content is
20e70 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 a BLOB and sqlit
20e80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
20e90 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 or.** sqli
20ea0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
20eb0 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 6() is called.
20ec0 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f A zero-terminato
20ed0 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 r might.**
20ee0 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 need to be added
20ef0 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c to the string.<
20f00 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 /li>.** <li> The
20f10 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 initial content
20f20 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 is UTF-8 text a
20f30 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nd sqlite3_colum
20f40 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a n_bytes16() or.*
20f50 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 * sqlite3_c
20f60 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 olumn_text16() i
20f70 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 s called. The c
20f80 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 ontent must be c
20f90 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 onverted.**
20fa0 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e to UTF-16.</li>
20fb0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 .** <li> The ini
20fc0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 tial content is
20fd0 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 UTF-16 text and
20fe0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
20ff0 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 ytes() or.**
21000 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e sqlite3_column
21010 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 _text() is calle
21020 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 d. The content
21030 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 must be converte
21040 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 d.** to UTF
21050 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c -8.</li>.** </ul
21060 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 >.**.** Conversi
21070 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d ons between UTF-
21080 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 16be and UTF-16l
21090 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e e are always don
210a0 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 e in place and d
210b0 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 o.** not invalid
210c0 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e ate a prior poin
210d0 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 ter, though of c
210e0 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e ourse the conten
210f0 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a t of the buffer.
21100 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f ** that the prio
21110 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 r pointer points
21120 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65 to will have be
21130 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 en modified. Ot
21140 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 her kinds.** of
21150 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 conversion are d
21160 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 one in place whe
21170 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 n it is possible
21180 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 , but sometimes
21190 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 they.** are not
211a0 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 possible and in
211b0 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f those cases prio
211c0 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 r pointers are i
211d0 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a nvalidated..**.*
211e0 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 * The safest and
211f0 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 easiest to reme
21200 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 mber policy is t
21210 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 o invoke these r
21220 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e outines.** in on
21230 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 e of the followi
21240 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c ng ways:.**.** <
21250 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 ul>.** <li>sqli
21260 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
21270 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 ) followed by sq
21280 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
21290 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c es()</li>.** <l
212a0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e i>sqlite3_column
212b0 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 _blob() followed
212c0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by sqlite3_colu
212d0 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a mn_bytes()</li>.
212e0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f ** <li>sqlite3_
212f0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 column_text16()
21300 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 followed by sqli
21310 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
21320 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 16()</li>.** </u
21330 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 l>.**.** In othe
21340 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f r words, you sho
21350 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 uld call sqlite3
21360 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a _column_text(),.
21370 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d ** sqlite3_colum
21380 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c n_blob(), or sql
21390 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
213a0 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 16() first to fo
213b0 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a rce the result.*
213c0 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 * into the desir
213d0 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 ed format, then
213e0 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 invoke sqlite3_c
213f0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 olumn_bytes() or
21400 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 .** sqlite3_colu
21410 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 mn_bytes16() to
21420 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 find the size of
21430 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f the result. Do
21440 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a not mix calls.*
21450 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c * to sqlite3_col
21460 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 umn_text() or sq
21470 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
21480 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 b() with calls t
21490 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c o.** sqlite3_col
214a0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 umn_bytes16(), a
214b0 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 nd do not mix ca
214c0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 lls to sqlite3_c
214d0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a olumn_text16().*
214e0 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 * with calls to
214f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
21500 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 ytes()..**.** Th
21510 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 e pointers retur
21520 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e ned are valid un
21530 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 til a type conve
21540 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a rsion occurs as.
21550 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f ** described abo
21560 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 ve, or until [sq
21570 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 lite3_step()] or
21580 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
21590 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 )] or.** [sqlite
215a0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 3_finalize()] is
215b0 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65 called. The me
215c0 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 mory space used
215d0 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a to hold strings.
215e0 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 ** and BLOBs is
215f0 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 freed automatica
21600 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c lly. Do <b>not<
21610 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 /b> pass the poi
21620 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a nters returned.*
21630 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
21640 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 n_blob()], [sqli
21650 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
21660 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a )], etc. into.**
21670 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
21680 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 ]..**.** If a me
21690 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
216a0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 error occurs dur
216b0 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 ing the evaluati
216c0 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 on of any.** of
216d0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 these routines,
216e0 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 a default value
216f0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 is returned. Th
21700 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a e default value.
21710 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 ** is either the
21720 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 integer 0, the
21730 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e floating point n
21740 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 umber 0.0, or a
21750 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e NULL.** pointer.
21760 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c Subsequent cal
21770 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 ls to [sqlite3_e
21780 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 rrcode()] will r
21790 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 eturn.** [SQLITE
217a0 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 52 _NOMEM]..**.** R
217b0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
217c0 5b 48 31 33 38 30 33 5d 20 5b 48 31 33 38 30 36 [H13803] [H13806
217d0 5d 20 5b 48 31 33 38 30 39 5d 20 5b 48 31 33 38 ] [H13809] [H138
217e0 31 32 5d 20 5b 48 31 33 38 31 35 5d 20 5b 48 31 12] [H13815] [H1
217f0 33 38 31 38 5d 20 5b 48 31 33 38 32 31 5d 20 5b 3818] [H13821] [
21800 48 31 33 38 32 34 5d 0a 2a 2a 20 5b 48 31 33 38 H13824].** [H138
21810 32 37 5d 20 5b 48 31 33 38 33 30 5d 0a 2a 2f 0a 27] [H13830].*/.
21820 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
21830 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
21840 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
21850 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 nt iCol);.int sq
21860 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
21870 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a es(sqlite3_stmt*
21880 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 , int iCol);.int
21890 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
218a0 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f bytes16(sqlite3_
218b0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
218c0 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 ;.double sqlite3
218d0 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 _column_double(s
218e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
218f0 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c t iCol);.int sql
21900 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 ite3_column_int(
21910 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
21920 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 nt iCol);.sqlite
21930 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 3_int64 sqlite3_
21940 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c column_int64(sql
21950 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
21960 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 iCol);.const uns
21970 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 igned char *sqli
21980 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
21990 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
219a0 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 nt iCol);.const
219b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
219c0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 lumn_text16(sqli
219d0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
219e0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 Col);.int sqlite
219f0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 3_column_type(sq
21a00 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
21a10 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f iCol);.sqlite3_
21a20 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 value *sqlite3_c
21a30 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 olumn_value(sqli
21a40 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
21a50 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 Col);../*.** CAP
21a60 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 I3REF: Destroy A
21a70 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d Prepared Statem
21a80 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 ent Object {H133
21a90 30 30 7d 20 3c 53 37 30 33 30 30 3e 3c 53 33 30 00} <S70300><S30
21aa0 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 100>.**.** The s
21ab0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
21ac0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 ) function is ca
21ad0 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 lled to delete a
21ae0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
21af0 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 ment]..** If the
21b00 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 65 statement was e
21b10 78 65 63 75 74 65 64 20 73 75 63 63 65 73 73 66 xecuted successf
21b20 75 6c 6c 79 20 6f 72 20 6e 6f 74 20 65 78 65 63 ully or not exec
21b30 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 uted at all, the
21b40 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 69 n.** SQLITE_OK i
21b50 73 20 72 65 74 75 72 6e 65 64 2e 20 49 66 20 65 s returned. If e
21b60 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 xecution of the
21b70 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 statement failed
21b80 20 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72 then an.** [err
21b90 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 or code] or [ext
21ba0 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 ended error code
21bb0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a ] is returned..*
21bc0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
21bd0 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 e can be called
21be0 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 at any point dur
21bf0 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f ing the executio
21c00 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 n of the.** [pre
21c10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
21c20 2e 20 20 49 66 20 74 68 65 20 76 69 72 74 75 61 . If the virtua
21c30 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e 6f l machine has no
21c40 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 t.** completed e
21c50 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20 74 68 xecution when th
21c60 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 is routine is ca
21c70 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20 6c 69 lled, that is li
21c80 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69 ke.** encounteri
21c90 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 ng an error or a
21ca0 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 n [sqlite3_inter
21cb0 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 rupt | interrupt
21cc0 5d 2e 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 ]..** Incomplete
21cd0 20 75 70 64 61 74 65 73 20 6d 61 79 20 62 65 20 updates may be
21ce0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 rolled back and
21cf0 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e transactions can
21d00 63 65 6c 65 64 2c 0a 2a 2a 20 64 65 70 65 6e 64 celed,.** depend
21d10 69 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75 ing on the circu
21d20 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 mstances, and th
21d30 65 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 e.** [error code
21d40 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 ] returned will
21d50 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 be [SQLITE_ABORT
21d60 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 ]..**.** Require
21d70 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 31 33 30 ments:.** [H1130
21d80 32 5d 20 5b 48 31 31 33 30 34 5d 0a 2a 2f 0a 69 2] [H11304].*/.i
21d90 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c nt sqlite3_final
21da0 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ize(sqlite3_stmt
21db0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
21dc0 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 CAPI3REF: Reset
21dd0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 A Prepared Stat
21de0 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 ement Object {H1
21df0 33 33 33 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 3330} <S70300>.*
21e00 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
21e10 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f _reset() functio
21e20 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 n is called to r
21e30 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 eset a [prepared
21e40 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f statement].** o
21e50 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 bject back to it
21e60 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c s initial state,
21e70 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d ready to be re-
21e80 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 executed..** Any
21e90 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 SQL statement v
21ea0 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 ariables that ha
21eb0 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 d values bound t
21ec0 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 o them using.**
21ed0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e the [sqlite3_bin
21ee0 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 d_blob | sqlite3
21ef0 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 _bind_*() API] r
21f00 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 etain their valu
21f10 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 es..** Use [sqli
21f20 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e te3_clear_bindin
21f30 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 gs()] to reset t
21f40 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a he bindings..**.
21f50 2a 2a 20 7b 48 31 31 33 33 32 7d 20 54 68 65 20 ** {H11332} The
21f60 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 [sqlite3_reset(S
21f70 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 )] interface res
21f80 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 ets the [prepare
21f90 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a d statement] S.*
21fa0 2a 20 20 20 20 20 20 20 20 20 20 62 61 63 6b 20 * back
21fb0 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 to the beginning
21fc0 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e of its program.
21fd0 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 34 7d 20 .**.** {H11334}
21fe0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 If the most rece
21ff0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 nt call to [sqli
22000 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 te3_step(S)] for
22010 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
22020 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
22030 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 ment] S returned
22040 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 [SQLITE_ROW] or
22050 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a [SQLITE_DONE],.
22060 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 ** or i
22070 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 f [sqlite3_step(
22080 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 S)] has never be
22090 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 fore been called
220a0 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 on S,.**
220b0 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 then [sqlite3
220c0 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 _reset(S)] retur
220d0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a ns [SQLITE_OK]..
220e0 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 36 7d 20 49 **.** {H11336} I
220f0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e f the most recen
22100 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 t call to [sqlit
22110 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 e3_step(S)] for
22120 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
22130 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
22140 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 ent] S indicated
22150 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a an error, then.
22160 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
22170 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 ite3_reset(S)] r
22180 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 eturns an approp
22190 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 riate [error cod
221a0 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 e]..**.** {H1133
221b0 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 8} The [sqlite3_
221c0 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 reset(S)] interf
221d0 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 ace does not cha
221e0 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a nge the values.*
221f0 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 61 6e * of an
22200 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f y [sqlite3_bind_
22210 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f blob|bindings] o
22220 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 n the [prepared
22230 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f statement] S..*/
22240 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 .int sqlite3_res
22250 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 et(sqlite3_stmt
22260 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *pStmt);../*.**
22270 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 CAPI3REF: Create
22280 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c Or Redefine SQL
22290 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 31 Functions {H161
222a0 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 00} <S20200>.**
222b0 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 KEYWORDS: {funct
222c0 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 ion creation rou
222d0 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 tines}.** KEYWOR
222e0 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e DS: {application
222f0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
22300 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 ction}.** KEYWOR
22310 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e DS: {application
22320 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
22330 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 ctions}.**.** Th
22340 65 73 65 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e ese two function
22350 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 s (collectively
22360 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 known as "functi
22370 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 on creation rout
22380 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 ines").** are us
22390 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 ed to add SQL fu
223a0 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 nctions or aggre
223b0 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 gates or to rede
223c0 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f fine the behavio
223d0 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 r.** of existing
223e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f SQL functions o
223f0 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 r aggregates. T
22400 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e he only differen
22410 63 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a 2a ce between the.*
22420 2a 20 74 77 6f 20 69 73 20 74 68 61 74 20 74 68 * two is that th
22430 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
22440 65 72 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 er, the name of
22450 74 68 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e the (scalar) fun
22460 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 ction or.** aggr
22470 65 67 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 egate, is encode
22480 64 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 20 73 d in UTF-8 for s
22490 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
224a0 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 nction() and UTF
224b0 2d 31 36 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 -16.** for sqlit
224c0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
224d0 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 on16()..**.** Th
224e0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
224f0 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 r is the [databa
22500 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 se connection] t
22510 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a o which the SQL.
22520 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 ** function is t
22530 6f 20 62 65 20 61 64 64 65 64 2e 20 20 49 66 20 o be added. If
22540 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 61 6d a single program
22550 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 uses more than
22560 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 one database.**
22570 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 6e 74 65 72 connection inter
22580 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c 20 nally, then SQL
22590 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 functions must b
225a0 65 20 61 64 64 65 64 20 69 6e 64 69 76 69 64 75 e added individu
225b0 61 6c 6c 79 20 74 6f 0a 2a 2a 20 65 61 63 68 20 ally to.** each
225c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
225d0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ion..**.** The s
225e0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
225f0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 is the name of t
22600 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 he SQL function
22610 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 to be created or
22620 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 .** redefined.
22630 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 The length of th
22640 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 e name is limite
22650 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20 d to 255 bytes,
22660 65 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a 20 exclusive of.**
22670 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 the zero-termina
22680 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 tor. Note that
22690 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 the name length
226a0 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65 limit is in byte
226b0 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 s, not.** charac
226c0 74 65 72 73 2e 20 20 41 6e 79 20 61 74 74 65 6d ters. Any attem
226d0 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 pt to create a f
226e0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c unction with a l
226f0 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 onger name.** wi
22700 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 ll result in [SQ
22710 4c 49 54 45 5f 45 52 52 4f 52 5d 20 62 65 69 6e LITE_ERROR] bein
22720 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a g returned..**.*
22730 2a 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 * The third para
22740 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 meter (nArg).**
22750 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 is the number of
22760 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 arguments that
22770 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
22780 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 or.** aggregate
22790 20 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20 takes. If this
227a0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 parameter is neg
227b0 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 ative, then the
227c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a SQL function or.
227d0 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 ** aggregate may
227e0 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 take any number
227f0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a of arguments..*
22800 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 *.** The fourth
22810 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 parameter, eText
22820 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 Rep, specifies w
22830 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 hat.** [SQLITE_U
22840 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 TF8 | text encod
22850 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 ing] this SQL fu
22860 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 nction prefers f
22870 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 or.** its parame
22880 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 ters. Any SQL f
22890 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e unction implemen
228a0 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 tation should be
228b0 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a able to work.**
228c0 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38 work with UTF-8
228d0 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 , UTF-16le, or U
228e0 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f TF-16be. But so
228f0 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f me implementatio
22900 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 ns may be.** mor
22910 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 e efficient with
22920 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 one encoding th
22930 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49 74 20 an another. It
22940 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a is allowed to.**
22950 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f invoke sqlite3_
22960 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
22970 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 ) or sqlite3_cre
22980 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 ate_function16()
22990 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d multiple.** tim
229a0 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 es with the same
229b0 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 function but wi
229c0 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c th different val
229d0 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e ues of eTextRep.
229e0 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c .** When multipl
229f0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
22a00 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 s of the same fu
22a10 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c nction are avail
22a20 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 able, SQLite.**
22a30 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e will pick the on
22a40 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 e that involves
22a50 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 the least amount
22a60 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 of data convers
22a70 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 ion..** If there
22a80 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c is only a singl
22a90 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
22aa0 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 which does not
22ab0 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a care what text.*
22ac0 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 * encoding is us
22ad0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 ed, then the fou
22ae0 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f rth argument sho
22af0 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 uld be [SQLITE_A
22b00 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 NY]..**.** The f
22b10 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 ifth parameter i
22b20 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 s an arbitrary p
22b30 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 ointer. The imp
22b40 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 lementation of t
22b50 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 he.** function c
22b60 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 an gain access t
22b70 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 o this pointer u
22b80 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 sing [sqlite3_us
22b90 65 72 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a er_data()]..**.*
22ba0 2a 20 54 68 65 20 73 65 76 65 6e 74 68 2c 20 65 * The seventh, e
22bb0 69 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 20 ighth and ninth
22bc0 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e parameters, xFun
22bd0 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 c, xStep and xFi
22be0 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e nal, are.** poin
22bf0 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 ters to C-langua
22c00 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 ge functions tha
22c10 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 t implement the
22c20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a SQL function or.
22c30 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 41 20 ** aggregate. A
22c40 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 scalar SQL funct
22c50 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 ion requires an
22c60 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
22c70 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 f the xFunc.** c
22c80 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 allback only, NU
22c90 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73 68 6f 75 LL pointers shou
22ca0 6c 64 20 62 65 20 70 61 73 73 65 64 20 61 73 20 ld be passed as
22cb0 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 the xStep and xF
22cc0 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 inal.** paramete
22cd0 72 73 2e 20 41 6e 20 61 67 67 72 65 67 61 74 65 rs. An aggregate
22ce0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 SQL function re
22cf0 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d quires an implem
22d00 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 entation of xSte
22d10 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 p.** and xFinal
22d20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 and NULL should
22d30 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 be passed for xF
22d40 75 6e 63 2e 20 54 6f 20 64 65 6c 65 74 65 20 61 unc. To delete a
22d50 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 n existing.** SQ
22d60 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 L function or ag
22d70 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 gregate, pass NU
22d80 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 LL for all three
22d90 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 function callba
22da0 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 cks..**.** It is
22db0 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 permitted to re
22dc0 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 gister multiple
22dd0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
22de0 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 of the same.** f
22df0 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 unctions with th
22e00 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 e same name but
22e10 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 with either diff
22e20 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 ering numbers of
22e30 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 .** arguments or
22e40 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 differing prefe
22e50 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 rred text encodi
22e60 6e 67 73 2e 20 20 53 51 4c 69 74 65 20 77 69 6c ngs. SQLite wil
22e70 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 l use.** the imp
22e80 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 lementation most
22e90 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 closely matches
22ea0 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 the way in whic
22eb0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e h the.** SQL fun
22ec0 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 ction is used.
22ed0 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 A function imple
22ee0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 mentation with a
22ef0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a non-negative.**
22f00 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 nArg parameter
22f10 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 is a better matc
22f20 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f h than a functio
22f30 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e n implementation
22f40 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 with.** a negat
22f50 69 76 65 20 6e 41 72 67 2e 20 20 41 20 66 75 6e ive nArg. A fun
22f60 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 ction where the
22f70 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 preferred text e
22f80 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 ncoding.** match
22f90 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 es the database
22fa0 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 encoding is a be
22fb0 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 tter.** match th
22fc0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 an a function wh
22fd0 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 ere the encoding
22fe0 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 is different.
22ff0 0a 2a 2a 20 41 20 66 75 6e 63 74 69 6f 6e 20 77 .** A function w
23000 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e here the encodin
23010 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 g difference is
23020 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 between UTF16le
23030 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 and UTF16be.** i
23040 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 s a closer match
23050 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e than a function
23060 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 where the encod
23070 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 ing difference i
23080 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 s.** between UTF
23090 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 8 and UTF16..**.
230a0 2a 2a 20 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 ** Built-in func
230b0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 tions may be ove
230c0 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 rloaded by new a
230d0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
230e0 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a ed functions..**
230f0 20 54 68 65 20 66 69 72 73 74 20 61 70 70 6c 69 The first appli
23100 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
23110 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 67 unction with a g
23120 69 76 65 6e 20 6e 61 6d 65 20 6f 76 65 72 72 69 iven name overri
23130 64 65 73 20 61 6c 6c 0a 2a 2a 20 62 75 69 6c 74 des all.** built
23140 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e -in functions in
23150 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 the same [datab
23160 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
23170 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 with the same na
23180 6d 65 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e me..** Subsequen
23190 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 t application-de
231a0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 fined functions
231b0 6f 66 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 of the same name
231c0 20 6f 6e 6c 79 20 6f 76 65 72 72 69 64 65 20 0a only override .
231d0 2a 2a 20 70 72 69 6f 72 20 61 70 70 6c 69 63 61 ** prior applica
231e0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
231f0 63 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 ctions that are
23200 61 6e 20 65 78 61 63 74 20 6d 61 74 63 68 20 66 an exact match f
23210 6f 72 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 or the.** number
23220 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20 61 of parameters a
23230 6e 64 20 70 72 65 66 65 72 72 65 64 20 65 6e 63 nd preferred enc
23240 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 oding..**.** An
23250 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
23260 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 ned function is
23270 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c permitted to cal
23280 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 l other.** SQLit
23290 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 e interfaces. H
232a0 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c owever, such cal
232b0 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 ls must not.** c
232c0 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 lose the databas
232d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 e connection nor
232e0 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 finalize or res
232f0 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a et the prepared.
23300 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 ** statement in
23310 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 which the functi
23320 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a on is running..*
23330 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
23340 73 3a 0a 2a 2a 20 5b 48 31 36 31 30 33 5d 20 5b s:.** [H16103] [
23350 48 31 36 31 30 36 5d 20 5b 48 31 36 31 30 39 5d H16106] [H16109]
23360 20 5b 48 31 36 31 31 32 5d 20 5b 48 31 36 31 31 [H16112] [H1611
23370 38 5d 20 5b 48 31 36 31 32 31 5d 20 5b 48 31 36 8] [H16121] [H16
23380 31 32 34 5d 20 5b 48 31 36 31 32 37 5d 0a 2a 2a 124] [H16127].**
23390 20 5b 48 31 36 31 33 30 5d 20 5b 48 31 36 31 33 [H16130] [H1613
233a0 33 5d 20 5b 48 31 36 31 33 36 5d 20 5b 48 31 36 3] [H16136] [H16
233b0 31 33 39 5d 20 5b 48 31 36 31 34 32 5d 0a 2a 2f 139] [H16142].*/
233c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 .int sqlite3_cre
233d0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 ate_function(.
233e0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 sqlite3 *db,. c
233f0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 onst char *zFunc
23400 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 tionName,. int
23410 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 nArg,. int eTex
23420 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 tRep,. void *pA
23430 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 pp,. void (*xFu
23440 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 nc)(sqlite3_cont
23450 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
23460 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
23470 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 d (*xStep)(sqlit
23480 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c e3_context*,int,
23490 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 sqlite3_value**)
234a0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 ,. void (*xFina
234b0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 l)(sqlite3_conte
234c0 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 xt*).);.int sqli
234d0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
234e0 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 ion16(. sqlite3
234f0 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f *db,. const vo
23500 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d id *zFunctionNam
23510 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 e,. int nArg,.
23520 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 int eTextRep,.
23530 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 void *pApp,. v
23540 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c oid (*xFunc)(sql
23550 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e ite3_context*,in
23560 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t,sqlite3_value*
23570 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 *),. void (*xSt
23580 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ep)(sqlite3_cont
23590 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
235a0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
235b0 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 d (*xFinal)(sqli
235c0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b te3_context*).);
235d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
235e0 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 : Text Encodings
235f0 20 7b 48 31 30 32 36 37 7d 20 3c 53 35 30 32 30 {H10267} <S5020
23600 30 3e 20 3c 48 31 36 31 30 30 3e 0a 2a 2a 0a 2a 0> <H16100>.**.*
23610 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 * These constant
23620 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 define integer
23630 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 codes that repre
23640 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 sent the various
23650 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e .** text encodin
23660 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 gs supported by
23670 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 SQLite..*/.#defi
23680 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 ne SQLITE_UTF8
23690 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 1.#defi
236a0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c ne SQLITE_UTF16L
236b0 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 E 2.#defi
236c0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 ne SQLITE_UTF16B
236d0 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 E 3.#defi
236e0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 ne SQLITE_UTF16
236f0 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 4 /*
23700 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 Use native byte
23710 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e order */.#defin
23720 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 e SQLITE_ANY
23730 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 5 /*
23740 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
23750 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a unction only */.
23760 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 #define SQLITE_U
23770 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 TF16_ALIGNED 8
23780 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 /* sqlite3_cr
23790 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f eate_collation o
237a0 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 nly */../*.** CA
237b0 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 PI3REF: Deprecat
237c0 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 ed Functions.**
237d0 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a DEPRECATED.**.**
237e0 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 These functions
237f0 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 are [deprecated
23800 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 ]. In order to
23810 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b maintain.** back
23820 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c wards compatibil
23830 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 ity with older c
23840 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 ode, these funct
23850 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a ions continue .*
23860 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 * to be supporte
23870 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 d. However, new
23880 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 applications sh
23890 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 ould avoid.** th
238a0 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 e use of these f
238b0 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 unctions. To he
238c0 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f lp encourage peo
238d0 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 ple to avoid.**
238e0 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 using these func
238f0 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f tions, we are no
23900 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 t going to tell
23910 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f you what they do
23920 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c ..*/.#ifndef SQL
23930 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 ITE_OMIT_DEPRECA
23940 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 TED.SQLITE_DEPRE
23950 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 CATED int sqlite
23960 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 3_aggregate_coun
23970 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 t(sqlite3_contex
23980 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 t*);.SQLITE_DEPR
23990 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 ECATED int sqlit
239a0 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 e3_expired(sqlit
239b0 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 e3_stmt*);.SQLIT
239c0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 E_DEPRECATED int
239d0 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 sqlite3_transfe
239e0 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 r_bindings(sqlit
239f0 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 e3_stmt*, sqlite
23a00 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 3_stmt*);.SQLITE
23a10 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 _DEPRECATED int
23a20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 sqlite3_global_r
23a30 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 ecover(void);.SQ
23a40 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 LITE_DEPRECATED
23a50 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 void sqlite3_thr
23a60 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 ead_cleanup(void
23a70 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 );.SQLITE_DEPREC
23a80 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 ATED int sqlite3
23a90 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f _memory_alarm(vo
23aa0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 id(*)(void*,sqli
23ab0 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 te3_int64,int),v
23ac0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 oid*,sqlite3_int
23ad0 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 64);.#endif../*.
23ae0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 ** CAPI3REF: Obt
23af0 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 aining SQL Funct
23b00 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 ion Parameter Va
23b10 6c 75 65 73 20 7b 48 31 35 31 30 30 7d 20 3c 53 lues {H15100} <S
23b20 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20200>.**.** The
23b30 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c C-language impl
23b40 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 ementation of SQ
23b50 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 L functions and
23b60 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a aggregates uses.
23b70 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 ** this set of i
23b80 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 nterface routine
23b90 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 s to access the
23ba0 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 parameter values
23bb0 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 on.** the funct
23bc0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 ion or aggregate
23bd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e ..**.** The xFun
23be0 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 c (for scalar fu
23bf0 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 nctions) or xSte
23c00 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 p (for aggregate
23c10 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a s) parameters.**
23c20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 to [sqlite3_cre
23c30 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 ate_function()]
23c40 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 and [sqlite3_cre
23c50 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 ate_function16()
23c60 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c ].** define call
23c70 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 backs that imple
23c80 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e ment the SQL fun
23c90 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 ctions and aggre
23ca0 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 gates..** The 4t
23cb0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
23cc0 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 hese callbacks i
23cd0 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f s an array of po
23ce0 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 inters to.** [pr
23cf0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
23d00 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 value] objects.
23d10 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 There is one [s
23d20 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
23d30 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 ject for.** each
23d40 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
23d50 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 e SQL function.
23d60 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
23d70 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 are used to.** e
23d80 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 xtract values fr
23d90 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f om the [sqlite3_
23da0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a value] objects..
23db0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
23dc0 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 ines work only w
23dd0 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 ith [protected s
23de0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
23df0 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 jects..** Any at
23e00 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 tempt to use the
23e10 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 se routines on a
23e20 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 n [unprotected s
23e30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a qlite3_value].**
23e40 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 object results
23e50 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 in undefined beh
23e60 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 avior..**.** The
23e70 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b se routines work
23e80 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 just like the c
23e90 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f orresponding [co
23ea0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 lumn access func
23eb0 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 tions].** except
23ec0 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 that these rou
23ed0 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e tines take a sin
23ee0 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 gle [protected s
23ef0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
23f00 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 ject.** pointer
23f10 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 instead of a [sq
23f20 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 lite3_stmt*] poi
23f30 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 nter and an inte
23f40 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 ger column numbe
23f50 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c r..**.** The sql
23f60 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
23f70 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 6() interface ex
23f80 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 tracts a UTF-16
23f90 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 string.** in the
23fa0 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 native byte-ord
23fb0 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d er of the host m
23fc0 61 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 achine. The.**
23fd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
23fe0 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c xt16be() and sql
23ff0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
24000 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 6le() interfaces
24010 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d .** extract UTF-
24020 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 16 strings as bi
24030 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 g-endian and lit
24040 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 tle-endian respe
24050 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 ctively..**.** T
24060 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 he sqlite3_value
24070 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 _numeric_type()
24080 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 interface attemp
24090 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e ts to apply.** n
240a0 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 umeric affinity
240b0 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 to the value. T
240c0 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 his means that a
240d0 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 n attempt is.**
240e0 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 made to convert
240f0 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 the value to an
24100 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 integer or float
24110 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a ing point. If.*
24120 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 * such a convers
24130 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 ion is possible
24140 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 without loss of
24150 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 information (in
24160 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 other.** words,
24170 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 if the value is
24180 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f a string that lo
24190 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 oks like a numbe
241a0 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 r).** then the c
241b0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 onversion is per
241c0 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 formed. Otherwi
241d0 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e se no conversion
241e0 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 occurs..** The
241f0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 [SQLITE_INTEGER
24200 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 | datatype] afte
24210 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 r conversion is
24220 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
24230 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69 Please pay parti
24240 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 cular attention
24250 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74 to the fact that
24260 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 the pointer ret
24270 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 urned.** from [s
24280 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f qlite3_value_blo
24290 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 b()], [sqlite3_v
242a0 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 alue_text()], or
242b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c .** [sqlite3_val
242c0 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e ue_text16()] can
242d0 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 be invalidated
242e0 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 by a subsequent
242f0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 call to.** [sqli
24300 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 te3_value_bytes(
24310 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c )], [sqlite3_val
24320 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b ue_bytes16()], [
24330 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
24340 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 xt()],.** or [sq
24350 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
24360 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 16()]..**.** The
24370 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 se routines must
24380 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 be called from
24390 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 the same thread
243a0 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 as.** the SQL fu
243b0 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 nction that supp
243c0 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 lied the [sqlite
243d0 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 3_value*] parame
243e0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 ters..**.** Requ
243f0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
24400 35 31 30 33 5d 20 5b 48 31 35 31 30 36 5d 20 5b 5103] [H15106] [
24410 48 31 35 31 30 39 5d 20 5b 48 31 35 31 31 32 5d H15109] [H15112]
24420 20 5b 48 31 35 31 31 35 5d 20 5b 48 31 35 31 31 [H15115] [H1511
24430 38 5d 20 5b 48 31 35 31 32 31 5d 20 5b 48 31 35 8] [H15121] [H15
24440 31 32 34 5d 0a 2a 2a 20 5b 48 31 35 31 32 37 5d 124].** [H15127]
24450 20 5b 48 31 35 31 33 30 5d 20 5b 48 31 35 31 33 [H15130] [H1513
24460 33 5d 20 5b 48 31 35 31 33 36 5d 0a 2a 2f 0a 63 3] [H15136].*/.c
24470 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
24480 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 e3_value_blob(sq
24490 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 lite3_value*);.i
244a0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt sqlite3_value
244b0 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 _bytes(sqlite3_v
244c0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 alue*);.int sqli
244d0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 te3_value_bytes1
244e0 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 6(sqlite3_value*
244f0 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 );.double sqlite
24500 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 3_value_double(s
24510 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
24520 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 int sqlite3_valu
24530 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 e_int(sqlite3_va
24540 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 lue*);.sqlite3_i
24550 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c nt64 sqlite3_val
24560 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 ue_int64(sqlite3
24570 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 _value*);.const
24580 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 unsigned char *s
24590 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
245a0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t(sqlite3_value*
245b0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
245c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
245d0 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 t16(sqlite3_valu
245e0 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 e*);.const void
245f0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 *sqlite3_value_t
24600 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f ext16le(sqlite3_
24610 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 value*);.const v
24620 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c oid *sqlite3_val
24630 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 ue_text16be(sqli
24640 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 te3_value*);.int
24650 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
24660 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 ype(sqlite3_valu
24670 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 e*);.int sqlite3
24680 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 _value_numeric_t
24690 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 ype(sqlite3_valu
246a0 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 e*);../*.** CAPI
246b0 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 3REF: Obtain Agg
246c0 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 regate Function
246d0 43 6f 6e 74 65 78 74 20 7b 48 31 36 32 31 30 7d Context {H16210}
246e0 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S20200>.**.**
246f0 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 The implementati
24700 6f 6e 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 on of aggregate
24710 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 SQL functions us
24720 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 e this routine t
24730 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61 20 o allocate.** a
24740 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 73 74 structure for st
24750 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 oring their stat
24760 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 e..**.** The fir
24770 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 st time the sqli
24780 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
24790 6e 74 65 78 74 28 29 20 72 6f 75 74 69 6e 65 20 ntext() routine
247a0 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 0a is called for a.
247b0 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 ** particular ag
247c0 67 72 65 67 61 74 65 2c 20 53 51 4c 69 74 65 20 gregate, SQLite
247d0 61 6c 6c 6f 63 61 74 65 73 20 6e 42 79 74 65 73 allocates nBytes
247e0 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f of memory, zero
247f0 65 73 20 6f 75 74 20 74 68 61 74 0a 2a 2a 20 6d es out that.** m
24800 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 emory, and retur
24810 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
24820 69 74 2e 20 4f 6e 20 73 65 63 6f 6e 64 20 61 6e it. On second an
24830 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c d subsequent cal
24840 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 ls to.** sqlite3
24850 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
24860 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d xt() for the sam
24870 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 e aggregate func
24880 74 69 6f 6e 20 69 6e 64 65 78 2c 0a 2a 2a 20 74 tion index,.** t
24890 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 he same buffer i
248a0 73 20 72 65 74 75 72 6e 65 64 2e 20 54 68 65 20 s returned. The
248b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
248c0 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 f the aggregate
248d0 63 61 6e 20 75 73 65 0a 2a 2a 20 74 68 65 20 72 can use.** the r
248e0 65 74 75 72 6e 65 64 20 62 75 66 66 65 72 20 74 eturned buffer t
248f0 6f 20 61 63 63 75 6d 75 6c 61 74 65 20 64 61 74 o accumulate dat
24900 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 a..**.** SQLite
24910 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 automatically fr
24920 65 65 73 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 ees the allocate
24930 64 20 62 75 66 66 65 72 20 77 68 65 6e 20 74 68 d buffer when th
24940 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 71 e aggregate.** q
24950 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a uery concludes..
24960 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
24970 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 parameter should
24980 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 be a copy of th
24990 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f e.** [sqlite3_co
249a0 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 ntext | SQL func
249b0 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 tion context] th
249c0 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 at is the first
249d0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 parameter.** to
249e0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 the callback rou
249f0 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d tine that implem
24a00 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 ents the aggrega
24a10 74 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a te function..**.
24a20 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
24a30 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 must be called f
24a40 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 rom the same thr
24a50 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 ead in which.**
24a60 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51 the aggregate SQ
24a70 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 L function is ru
24a80 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 nning..**.** Req
24a90 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
24aa0 31 36 32 31 31 5d 20 5b 48 31 36 32 31 33 5d 20 16211] [H16213]
24ab0 5b 48 31 36 32 31 35 5d 20 5b 48 31 36 32 31 37 [H16215] [H16217
24ac0 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 ].*/.void *sqlit
24ad0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
24ae0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e text(sqlite3_con
24af0 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 text*, int nByte
24b00 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 s);../*.** CAPI3
24b10 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 REF: User Data F
24b20 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 or Functions {H1
24b30 36 32 34 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 6240} <S20200>.*
24b40 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
24b50 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 _user_data() int
24b60 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
24b70 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 copy of.** the
24b80 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 pointer that was
24b90 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70 the pUserData p
24ba0 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 arameter (the 5t
24bb0 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 h parameter).**
24bc0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
24bd0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
24be0 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 )].** and [sqlit
24bf0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
24c00 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 on16()] routines
24c10 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 that originally
24c20 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 .** registered t
24c30 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 he application d
24c40 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e efined function.
24c50 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 {END}.**.** Thi
24c60 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 s routine must b
24c70 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 e called from th
24c80 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e e same thread in
24c90 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 which.** the ap
24ca0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
24cb0 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 d function is ru
24cc0 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 nning..**.** Req
24cd0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
24ce0 31 36 32 34 33 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 16243].*/.void *
24cf0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 sqlite3_user_dat
24d00 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 a(sqlite3_contex
24d10 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
24d20 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 3REF: Database C
24d30 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 onnection For Fu
24d40 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32 35 30 7d nctions {H16250}
24d50 20 3c 53 36 30 36 30 30 3e 3c 53 32 30 32 30 30 <S60600><S20200
24d60 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 >.**.** The sqli
24d70 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 te3_context_db_h
24d80 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 andle() interfac
24d90 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 e returns a copy
24da0 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 of.** the point
24db0 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 er to the [datab
24dc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
24dd0 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 (the 1st paramet
24de0 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 er).** of the [s
24df0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
24e00 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 nction()].** and
24e10 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
24e20 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 _function16()] r
24e30 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 outines that ori
24e40 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 ginally.** regis
24e50 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 tered the applic
24e60 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 ation defined fu
24e70 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 nction..**.** Re
24e80 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
24e90 48 31 36 32 35 33 5d 0a 2a 2f 0a 73 71 6c 69 74 H16253].*/.sqlit
24ea0 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 e3 *sqlite3_cont
24eb0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 ext_db_handle(sq
24ec0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b lite3_context*);
24ed0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
24ee0 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c : Function Auxil
24ef0 69 61 72 79 20 44 61 74 61 20 7b 48 31 36 32 37 iary Data {H1627
24f00 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 0} <S20200>.**.*
24f10 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 * The following
24f20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 two functions ma
24f30 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61 y be used by sca
24f40 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e lar SQL function
24f50 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 s to.** associat
24f60 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 e metadata with
24f70 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e argument values.
24f80 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c If the same val
24f90 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a ue is passed to.
24fa0 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f ** multiple invo
24fb0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 cations of the s
24fc0 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ame SQL function
24fd0 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 during query ex
24fe0 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a ecution, under.*
24ff0 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 * some circumsta
25000 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 nces the associa
25010 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 ted metadata may
25020 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 be preserved. T
25030 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 his may.** be us
25040 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c ed, for example,
25050 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 to add a regula
25060 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 r-expression mat
25070 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 ching scalar.**
25080 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f function. The co
25090 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f mpiled version o
250a0 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 f the regular ex
250b0 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 pression is stor
250c0 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 ed as.** metadat
250d0 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 a associated wit
250e0 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 h the SQL value
250f0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65 passed as the re
25100 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e gular expression
25110 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 .** pattern. Th
25120 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c e compiled regul
25130 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 ar expression ca
25140 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d n be reused on m
25150 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 ultiple.** invoc
25160 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 ations of the sa
25170 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 me function so t
25180 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c hat the original
25190 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a pattern string.
251a0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 ** does not need
251b0 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 to be recompile
251c0 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 d on each invoca
251d0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 tion..**.** The
251e0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 sqlite3_get_auxd
251f0 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 ata() interface
25200 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
25210 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 r to the metadat
25220 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 a.** associated
25230 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 by the sqlite3_s
25240 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e et_auxdata() fun
25250 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e ction with the N
25260 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 th argument.** v
25270 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c alue to the appl
25280 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
25290 66 75 6e 63 74 69 6f 6e 2e 20 49 66 20 6e 6f 20 function. If no
252a0 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65 metadata has bee
252b0 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 n ever.** been s
252c0 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 et for the Nth a
252d0 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 rgument of the f
252e0 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 unction, or if t
252f0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
25300 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 .** function par
25310 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 ameter has chang
25320 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 ed since the met
25330 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a a-data was set,.
25340 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f ** then sqlite3_
25350 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 get_auxdata() re
25360 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 turns a NULL poi
25370 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 nter..**.** The
25380 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 sqlite3_set_auxd
25390 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 ata() interface
253a0 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64 61 saves the metada
253b0 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f ta.** pointed to
253c0 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61 by its 3rd para
253d0 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 meter as the met
253e0 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d adata for the N-
253f0 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f th.** argument o
25400 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
25410 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
25420 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a on. Subsequent.
25430 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 ** calls to sqli
25440 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 te3_get_auxdata(
25450 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 ) might return t
25460 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 his data, if it
25470 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 has.** not been
25480 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 49 66 destroyed..** If
25490 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c it is not NULL,
254a0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 SQLite will inv
254b0 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 oke the destruct
254c0 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 or.** function g
254d0 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 iven by the 4th
254e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
254f0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 ite3_set_auxdata
25500 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 () on.** the met
25510 61 64 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 adata when the c
25520 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e orresponding fun
25530 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 ction parameter
25540 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 changes.** or wh
25550 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 en the SQL state
25560 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 ment completes,
25570 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 whichever comes
25580 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c first..**.** SQL
25590 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 ite is free to c
255a0 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 all the destruct
255b0 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 or and drop meta
255c0 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 data on any.** p
255d0 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 arameter of any
255e0 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 function at any
255f0 74 69 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20 time. The only
25600 67 75 61 72 61 6e 74 65 65 20 69 73 20 74 68 61 guarantee is tha
25610 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63 t.** the destruc
25620 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c tor will be call
25630 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 ed before the me
25640 74 61 64 61 74 61 20 69 73 20 64 72 6f 70 70 65 tadata is droppe
25650 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 d..**.** In prac
25660 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 tice, metadata i
25670 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 s preserved betw
25680 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c een function cal
25690 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 ls for.** expres
256a0 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 sions that are c
256b0 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 onstant at compi
256c0 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e le time. This in
256d0 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a cludes literal.*
256e0 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 53 51 4c * values and SQL
256f0 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a variables..**.*
25700 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
25710 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 must be called
25720 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 from the same th
25730 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a read in which.**
25740 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
25750 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a n is running..**
25760 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
25770 3a 0a 2a 2a 20 5b 48 31 36 32 37 32 5d 20 5b 48 :.** [H16272] [H
25780 31 36 32 37 34 5d 20 5b 48 31 36 32 37 36 5d 20 16274] [H16276]
25790 5b 48 31 36 32 37 37 5d 20 5b 48 31 36 32 37 38 [H16277] [H16278
257a0 5d 20 5b 48 31 36 32 37 39 5d 0a 2a 2f 0a 76 6f ] [H16279].*/.vo
257b0 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f id *sqlite3_get_
257c0 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f auxdata(sqlite3_
257d0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 context*, int N)
257e0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 ;.void sqlite3_s
257f0 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 et_auxdata(sqlit
25800 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 e3_context*, int
25810 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 N, void*, void
25820 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f (*)(void*));.../
25830 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
25840 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e onstants Definin
25850 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 g Special Destru
25860 63 74 6f 72 20 42 65 68 61 76 69 6f 72 20 7b 48 ctor Behavior {H
25870 31 30 32 38 30 7d 20 3c 53 33 30 31 30 30 3e 0a 10280} <S30100>.
25880 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 **.** These are
25890 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 special values f
258a0 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f or the destructo
258b0 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 r that is passed
258c0 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 in as the.** fi
258d0 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 nal argument to
258e0 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 routines like [s
258f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
25900 6f 62 28 29 5d 2e 20 20 49 66 20 74 68 65 20 64 ob()]. If the d
25910 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 estructor.** arg
25920 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f ument is SQLITE_
25930 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 STATIC, it means
25940 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e that the conten
25950 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e t pointer is con
25960 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c stant.** and wil
25970 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 l never change.
25980 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 It does not nee
25990 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 d to be destroye
259a0 64 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 d. The.** SQLIT
259b0 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 E_TRANSIENT valu
259c0 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 e means that the
259d0 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 content will li
259e0 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a kely change in.*
259f0 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 * the near futur
25a00 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 e and that SQLit
25a10 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 e should make it
25a20 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f s own private co
25a30 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e py of.** the con
25a40 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 tent before retu
25a50 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 rning..**.** The
25a60 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 typedef is nece
25a70 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 ssary to work ar
25a80 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e ound problems in
25a90 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 certain.** C++
25aa0 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 compilers. See
25ab0 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f ticket #2191..*/
25ac0 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a .typedef void (*
25ad0 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 sqlite3_destruct
25ae0 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b or_type)(void*);
25af0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
25b00 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 STATIC ((sq
25b10 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 lite3_destructor
25b20 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 _type)0).#define
25b30 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e SQLITE_TRANSIEN
25b40 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 T ((sqlite3_de
25b50 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 structor_type)-1
25b60 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 )../*.** CAPI3RE
25b70 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 F: Setting The R
25b80 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 esult Of An SQL
25b90 46 75 6e 63 74 69 6f 6e 20 7b 48 31 36 34 30 30 Function {H16400
25ba0 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a } <S20200>.**.**
25bb0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
25bc0 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 are used by the
25bd0 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 xFunc or xFinal
25be0 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a callbacks that.*
25bf0 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 * implement SQL
25c00 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 functions and ag
25c10 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a gregates. See.*
25c20 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 * [sqlite3_creat
25c30 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e e_function()] an
25c40 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 d [sqlite3_creat
25c50 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a e_function16()].
25c60 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 ** for additiona
25c70 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a l information..*
25c80 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 *.** These funct
25c90 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d ions work very m
25ca0 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 uch like the [pa
25cb0 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d rameter binding]
25cc0 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 family of.** fu
25cd0 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 nctions used to
25ce0 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 bind values to h
25cf0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 ost parameters i
25d00 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 n prepared state
25d10 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 ments..** Refer
25d20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 to the [SQL para
25d30 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 meter] documenta
25d40 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f tion for additio
25d50 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e nal information.
25d60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
25d70 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 e3_result_blob()
25d80 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 interface sets
25d90 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a the result from.
25da0 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f ** an applicatio
25db0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
25dc0 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f on to be the BLO
25dd0 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 B whose content
25de0 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f is pointed.** to
25df0 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 by the second p
25e00 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 arameter and whi
25e10 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f ch is N bytes lo
25e20 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 ng where N is th
25e30 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d e.** third param
25e40 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 eter..**.** The
25e50 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a sqlite3_result_z
25e60 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 eroblob() interf
25e70 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 aces set the res
25e80 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 ult of.** the ap
25e90 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
25ea0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 d function to be
25eb0 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 a BLOB containi
25ec0 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 ng all zero.** b
25ed0 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 ytes and N bytes
25ee0 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 in size, where
25ef0 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f N is the value o
25f00 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 f the 2nd parame
25f10 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ter..**.** The s
25f20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f qlite3_result_do
25f30 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 uble() interface
25f40 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 sets the result
25f50 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c from.** an appl
25f60 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
25f70 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 function to be a
25f80 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 floating point
25f90 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a value specified.
25fa0 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 ** by its 2nd ar
25fb0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 gument..**.** Th
25fc0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
25fd0 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c _error() and sql
25fe0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
25ff0 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a r16() functions.
26000 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 ** cause the imp
26010 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e lemented SQL fun
26020 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 ction to throw a
26030 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 n exception..**
26040 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 SQLite uses the
26050 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 string pointed t
26060 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 o by the.** 2nd
26070 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c parameter of sql
26080 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
26090 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 r() or sqlite3_r
260a0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a esult_error16().
260b0 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f ** as the text o
260c0 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 f an error messa
260d0 67 65 2e 20 20 53 51 4c 69 74 65 20 69 6e 74 65 ge. SQLite inte
260e0 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 rprets the error
260f0 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 .** message stri
26100 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ng from sqlite3_
26110 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 result_error() a
26120 73 20 55 54 46 2d 38 2e 20 53 51 4c 69 74 65 0a s UTF-8. SQLite.
26130 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 ** interprets th
26140 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 e string from sq
26150 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
26160 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 or16() as UTF-16
26170 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 in native.** by
26180 74 65 20 6f 72 64 65 72 2e 20 20 49 66 20 74 68 te order. If th
26190 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
261a0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 r to sqlite3_res
261b0 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f ult_error().** o
261c0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 r sqlite3_result
261d0 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 _error16() is ne
261e0 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 gative then SQLi
261f0 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 te takes as the
26200 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 error.** message
26210 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 all text up thr
26220 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a ough the first z
26230 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a ero character..*
26240 2a 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70 * If the third p
26250 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
26260 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
26270 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 () or.** sqlite3
26280 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
26290 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 ) is non-negativ
262a0 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 e then SQLite ta
262b0 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a kes that many.**
262c0 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 bytes (not char
262d0 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 acters) from the
262e0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 2nd parameter a
262f0 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 s the error mess
26300 61 67 65 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 age..** The sqli
26310 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
26320 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 () and sqlite3_r
26330 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a esult_error16().
26340 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 ** routines make
26350 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 a private copy
26360 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 of the error mes
26370 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 sage text before
26380 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e .** they return.
26390 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c Hence, the cal
263a0 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 ling function ca
263b0 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a n deallocate or.
263c0 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 ** modify the te
263d0 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65 xt after they re
263e0 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 turn without har
263f0 6d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 m..** The sqlite
26400 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 3_result_error_c
26410 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 ode() function c
26420 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 hanges the error
26430 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 code.** returne
26440 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 d by SQLite as a
26450 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 result of an er
26460 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f ror in a functio
26470 6e 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 0a n. By default,.
26480 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 ** the error cod
26490 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f e is SQLITE_ERRO
264a0 52 2e 20 20 41 20 73 75 62 73 65 71 75 65 6e 74 R. A subsequent
264b0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
264c0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a _result_error().
264d0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 ** or sqlite3_re
264e0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 sult_error16() r
264f0 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 esets the error
26500 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 code to SQLITE_E
26510 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 RROR..**.** The
26520 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
26530 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 oobig() interfac
26540 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 e causes SQLite
26550 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f to throw an erro
26560 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 r.** indicating
26570 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 that a string or
26580 20 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67 BLOB is to long
26590 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a to represent..*
265a0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
265b0 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 _result_nomem()
265c0 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 interface causes
265d0 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 SQLite to throw
265e0 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 an error.** ind
265f0 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d icating that a m
26600 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
26610 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 failed..**.** T
26620 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
26630 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 t_int() interfac
26640 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 e sets the retur
26650 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 n value.** of th
26660 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
26670 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 fined function t
26680 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 o be the 32-bit
26690 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a signed integer.*
266a0 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e * value given in
266b0 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e the 2nd argumen
266c0 74 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 t..** The sqlite
266d0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 3_result_int64()
266e0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 interface sets
266f0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
26700 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 .** of the appli
26710 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
26720 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 unction to be th
26730 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 e 64-bit signed
26740 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 integer.** value
26750 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e given in the 2n
26760 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a d argument..**.*
26770 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 * The sqlite3_re
26780 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 sult_null() inte
26790 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 rface sets the r
267a0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f eturn value.** o
267b0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
267c0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
267d0 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a on to be NULL..*
267e0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
267f0 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 _result_text(),
26800 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
26810 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 ext16(),.** sqli
26820 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 te3_result_text1
26830 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 6le(), and sqlit
26840 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
26850 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a be() interfaces.
26860 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72 ** set the retur
26870 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 n value of the a
26880 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
26890 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ed function to b
268a0 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 e.** a text stri
268b0 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72 ng which is repr
268c0 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 esented as UTF-8
268d0 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 , UTF-16 native
268e0 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 byte order,.** U
268f0 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 TF-16 little end
26900 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 ian, or UTF-16 b
26910 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 ig endian, respe
26920 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69 ctively..** SQLi
26930 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 te takes the tex
26940 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 t result from th
26950 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 e application fr
26960 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 om.** the 2nd pa
26970 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 rameter of the s
26980 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
26990 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a xt* interfaces..
269a0 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 ** If the 3rd pa
269b0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 rameter to the s
269c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
269d0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a xt* interfaces.*
269e0 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 * is negative, t
269f0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 hen SQLite takes
26a00 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f result text fro
26a10 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 m the 2nd parame
26a20 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 ter.** through t
26a30 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 he first zero ch
26a40 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 aracter..** If t
26a50 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 he 3rd parameter
26a60 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
26a70 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 result_text* int
26a80 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f erfaces.** is no
26a90 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e n-negative, then
26aa0 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 as many bytes (
26ab0 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 not characters)
26ac0 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 of the text.** p
26ad0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 ointed to by the
26ae0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 2nd parameter a
26af0 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 re taken as the
26b00 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
26b10 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ned.** function
26b20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 result..** If th
26b30 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 4th parameter
26b40 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 to the sqlite3_r
26b50 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 esult_text* inte
26b60 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c rfaces.** or sql
26b70 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 ite3_result_blob
26b80 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 is a non-NULL p
26b90 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c ointer, then SQL
26ba0 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a ite calls that.*
26bb0 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 * function as th
26bc0 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 e destructor on
26bd0 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 the text or BLOB
26be0 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 result when it
26bf0 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 has.** finished
26c00 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c using that resul
26c10 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 t..** If the 4th
26c20 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
26c30 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
26c40 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 _text* interface
26c50 73 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f s or.** sqlite3_
26c60 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 result_blob is t
26c70 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 he special const
26c80 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 ant SQLITE_STATI
26c90 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a C, then SQLite.*
26ca0 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 * assumes that t
26cb0 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 he text or BLOB
26cc0 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e result is in con
26cd0 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 stant space and
26ce0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 does not.** copy
26cf0 20 74 68 65 20 69 74 20 6f 72 20 63 61 6c 6c 20 the it or call
26d00 61 20 64 65 73 74 72 75 63 74 6f 72 20 77 68 65 a destructor whe
26d10 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 n it has finishe
26d20 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 d using that res
26d30 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 ult..** If the 4
26d40 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
26d50 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 the sqlite3_resu
26d60 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 lt_text* interfa
26d70 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 ces.** or sqlite
26d80 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 3_result_blob is
26d90 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e the special con
26da0 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 stant SQLITE_TRA
26db0 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 NSIENT.** then S
26dc0 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f QLite makes a co
26dd0 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 py of the result
26de0 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 into space obta
26df0 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f ined from.** fro
26e00 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f m [sqlite3_mallo
26e10 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 c()] before it r
26e20 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 eturns..**.** Th
26e30 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
26e40 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 _value() interfa
26e50 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 ce sets the resu
26e60 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 lt of.** the app
26e70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
26e80 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
26e90 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 a copy the.** [u
26ea0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
26eb0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
26ec0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 specified by th
26ed0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e e 2nd parameter.
26ee0 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 The.** sqlite3
26ef0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 _result_value()
26f00 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 interface makes
26f10 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 a copy of the [s
26f20 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a qlite3_value].**
26f30 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 so that the [sq
26f40 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 lite3_value] spe
26f50 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 cified in the pa
26f60 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e rameter may chan
26f70 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c ge or.** be deal
26f80 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 located after sq
26f90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c lite3_result_val
26fa0 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 ue() returns wit
26fb0 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 41 20 hout harm..** A
26fc0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 [protected sqlit
26fd0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
26fe0 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 may always be u
26ff0 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 sed where an.**
27000 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c [unprotected sql
27010 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
27020 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 ct is required,
27030 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e so either.** kin
27040 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 d of [sqlite3_va
27050 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 lue] object can
27060 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 be used with thi
27070 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a s interface..**.
27080 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 ** If these rout
27090 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 ines are called
270a0 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 from within the
270b0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 different thread
270c0 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 .** than the one
270d0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 containing the
270e0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
270f0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 ned function tha
27100 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 t received.** th
27110 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 e [sqlite3_conte
27120 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 xt] pointer, the
27130 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 results are und
27140 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 efined..**.** Re
27150 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
27160 48 31 36 34 30 33 5d 20 5b 48 31 36 34 30 36 5d H16403] [H16406]
27170 20 5b 48 31 36 34 30 39 5d 20 5b 48 31 36 34 31 [H16409] [H1641
27180 32 5d 20 5b 48 31 36 34 31 35 5d 20 5b 48 31 36 2] [H16415] [H16
27190 34 31 38 5d 20 5b 48 31 36 34 32 31 5d 20 5b 48 418] [H16421] [H
271a0 31 36 34 32 34 5d 0a 2a 2a 20 5b 48 31 36 34 32 16424].** [H1642
271b0 37 5d 20 5b 48 31 36 34 33 30 5d 20 5b 48 31 36 7] [H16430] [H16
271c0 34 33 33 5d 20 5b 48 31 36 34 33 36 5d 20 5b 48 433] [H16436] [H
271d0 31 36 34 33 39 5d 20 5b 48 31 36 34 34 32 5d 20 16439] [H16442]
271e0 5b 48 31 36 34 34 35 5d 20 5b 48 31 36 34 34 38 [H16445] [H16448
271f0 5d 0a 2a 2a 20 5b 48 31 36 34 35 31 5d 20 5b 48 ].** [H16451] [H
27200 31 36 34 35 34 5d 20 5b 48 31 36 34 35 37 5d 20 16454] [H16457]
27210 5b 48 31 36 34 36 30 5d 20 5b 48 31 36 34 36 33 [H16460] [H16463
27220 5d 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 ].*/.void sqlite
27230 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 3_result_blob(sq
27240 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
27250 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
27260 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 , void(*)(void*)
27270 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
27280 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 result_double(sq
27290 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
272a0 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 double);.void sq
272b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
272c0 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 or(sqlite3_conte
272d0 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a xt*, const char*
272e0 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c , int);.void sql
272f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
27300 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 r16(sqlite3_cont
27310 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 ext*, const void
27320 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 *, int);.void sq
27330 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
27340 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 or_toobig(sqlite
27350 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 3_context*);.voi
27360 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
27370 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c _error_nomem(sql
27380 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a ite3_context*);.
27390 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
273a0 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 ult_error_code(s
273b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
273c0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 int);.void sqli
273d0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 te3_result_int(s
273e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
273f0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 int);.void sqli
27400 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 te3_result_int64
27410 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
27420 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 *, sqlite3_int64
27430 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
27440 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 result_null(sqli
27450 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 te3_context*);.v
27460 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
27470 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f lt_text(sqlite3_
27480 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
27490 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 char*, int, void
274a0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 (*)(void*));.voi
274b0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
274c0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f _text16(sqlite3_
274d0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
274e0 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 void*, int, void
274f0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 (*)(void*));.voi
27500 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
27510 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 _text16le(sqlite
27520 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 3_context*, cons
27530 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 t void*, int,voi
27540 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f d(*)(void*));.vo
27550 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
27560 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 t_text16be(sqlit
27570 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e e3_context*, con
27580 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f st void*, int,vo
27590 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 id(*)(void*));.v
275a0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
275b0 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 lt_value(sqlite3
275c0 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 _context*, sqlit
275d0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 e3_value*);.void
275e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
275f0 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 zeroblob(sqlite3
27600 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e _context*, int n
27610 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
27620 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 EF: Define New C
27630 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 ollating Sequenc
27640 65 73 20 7b 48 31 36 36 30 30 7d 20 3c 53 32 30 es {H16600} <S20
27650 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 300>.**.** These
27660 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 functions are u
27670 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77 20 63 sed to add new c
27680 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 ollation sequenc
27690 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 61 es to the.** [da
276a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
276b0 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20 n] specified as
276c0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
276d0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 nt..**.** The na
276e0 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63 6f me of the new co
276f0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 llation sequence
27700 20 69 73 20 73 70 65 63 69 66 69 65 64 20 61 73 is specified as
27710 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a a UTF-8 string.
27720 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 ** for sqlite3_c
27730 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 reate_collation(
27740 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 ) and sqlite3_cr
27750 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 eate_collation_v
27760 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2().** and a UTF
27770 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20 73 -16 string for s
27780 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
27790 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20 llation16(). In
277a0 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 all cases.** the
277b0 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65 64 20 name is passed
277c0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 as the second fu
277d0 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e nction argument.
277e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 .**.** The third
277f0 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 argument may be
27800 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 one of the cons
27810 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 tants [SQLITE_UT
27820 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f F8],.** [SQLITE_
27830 55 54 46 31 36 4c 45 5d 2c 20 6f 72 20 5b 53 51 UTF16LE], or [SQ
27840 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 LITE_UTF16BE], i
27850 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 74 ndicating that t
27860 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 he user-supplied
27870 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65 .** routine expe
27880 63 74 73 20 74 6f 20 62 65 20 70 61 73 73 65 64 cts to be passed
27890 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 pointers to str
278a0 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69 ings encoded usi
278b0 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 ng UTF-8,.** UTF
278c0 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 -16 little-endia
278d0 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 n, or UTF-16 big
278e0 2d 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 -endian, respect
278f0 69 76 65 6c 79 2e 20 54 68 65 0a 2a 2a 20 74 68 ively. The.** th
27900 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 69 67 ird argument mig
27910 68 74 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49 ht also be [SQLI
27920 54 45 5f 55 54 46 31 36 5d 20 74 6f 20 69 6e 64 TE_UTF16] to ind
27930 69 63 61 74 65 20 74 68 61 74 20 74 68 65 20 72 icate that the r
27940 6f 75 74 69 6e 65 0a 2a 2a 20 65 78 70 65 63 74 outine.** expect
27950 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 62 65 s pointers to be
27960 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 UTF-16 strings
27970 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 in the native by
27980 74 65 20 6f 72 64 65 72 2c 20 6f 72 20 74 68 65 te order, or the
27990 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 63 61 6e .** argument can
279a0 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 be [SQLITE_UTF1
279b0 36 5f 41 4c 49 47 4e 45 44 5d 20 69 66 20 74 68 6_ALIGNED] if th
279c0 65 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 e.** the routine
279d0 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72 expects pointer
279e0 73 20 74 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 s to 16-bit word
279f0 20 61 6c 69 67 6e 65 64 20 73 74 72 69 6e 67 73 aligned strings
27a00 0a 2a 2a 20 6f 66 20 55 54 46 2d 31 36 20 69 6e .** of UTF-16 in
27a10 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 the native byte
27a20 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 order..**.** A
27a30 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75 pointer to the u
27a40 73 65 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75 ser supplied rou
27a50 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73 tine must be pas
27a60 73 65 64 20 61 73 20 74 68 65 20 66 69 66 74 68 sed as the fifth
27a70 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 .** argument. I
27a80 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 f it is NULL, th
27a90 69 73 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 is is the same a
27aa0 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 s deleting the c
27ab0 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 ollation.** sequ
27ac0 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20 53 51 ence (so that SQ
27ad0 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c Lite cannot call
27ae0 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a it anymore)..**
27af0 20 45 61 63 68 20 74 69 6d 65 20 74 68 65 20 61 Each time the a
27b00 70 70 6c 69 63 61 74 69 6f 6e 20 73 75 70 70 6c pplication suppl
27b10 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 ied function is
27b20 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 invoked, it is p
27b30 61 73 73 65 64 0a 2a 2a 20 61 73 20 69 74 73 20 assed.** as its
27b40 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
27b50 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f a copy of the vo
27b60 69 64 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 id* passed as th
27b70 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e e fourth argumen
27b80 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f t.** to sqlite3_
27b90 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
27ba0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 () or sqlite3_cr
27bb0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 eate_collation16
27bc0 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 ()..**.** The re
27bd0 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 maining argument
27be0 73 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 s to the applica
27bf0 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f tion-supplied ro
27c00 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74 utine are two st
27c10 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 rings,.** each r
27c20 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 epresented by a
27c30 28 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 20 70 (length, data) p
27c40 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 air and encoded
27c50 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a in the encoding.
27c60 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61 73 73 ** that was pass
27c70 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 ed as the third
27c80 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 argument when th
27c90 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 e collation sequ
27ca0 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 ence was.** regi
27cb0 73 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20 20 54 stered. {END} T
27cc0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 he application d
27cd0 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e efined collation
27ce0 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a routine should.
27cf0 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67 61 74 69 ** return negati
27d00 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69 ve, zero or posi
27d10 74 69 76 65 20 69 66 20 74 68 65 20 66 69 72 73 tive if the firs
27d20 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 t string is less
27d30 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61 6c 20 than,.** equal
27d40 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 to, or greater t
27d50 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 20 73 han the second s
27d60 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52 tring. i.e. (STR
27d70 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29 2e ING1 - STRING2).
27d80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
27d90 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
27da0 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c ion_v2() works l
27db0 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 ike sqlite3_crea
27dc0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a te_collation().*
27dd0 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 * except that it
27de0 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61 20 takes an extra
27df0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 argument which i
27e00 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 s a destructor f
27e10 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 or.** the collat
27e20 69 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 72 75 ion. The destru
27e30 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77 ctor is called w
27e40 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f hen the collatio
27e50 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 n is.** destroye
27e60 64 20 61 6e 64 20 69 73 20 70 61 73 73 65 64 20 d and is passed
27e70 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f a copy of the fo
27e80 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 76 urth parameter v
27e90 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 oid* pointer.**
27ea0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 of the sqlite3_c
27eb0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f reate_collation_
27ec0 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74 69 v2()..** Collati
27ed0 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f 79 65 ons are destroye
27ee0 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 d when they are
27ef0 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 overridden by la
27f00 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 ter calls to the
27f10 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 .** collation cr
27f20 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 eation functions
27f30 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 64 61 or when the [da
27f40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
27f50 6e 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20 n] is closed.**
27f60 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 using [sqlite3_c
27f70 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 lose()]..**.** S
27f80 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 ee also: [sqlit
27f90 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 e3_collation_nee
27fa0 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 ded()] and [sqli
27fb0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 te3_collation_ne
27fc0 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a eded16()]..**.**
27fd0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
27fe0 2a 20 5b 48 31 36 36 30 33 5d 20 5b 48 31 36 36 * [H16603] [H166
27ff0 30 34 5d 20 5b 48 31 36 36 30 36 5d 20 5b 48 31 04] [H16606] [H1
28000 36 36 30 39 5d 20 5b 48 31 36 36 31 32 5d 20 5b 6609] [H16612] [
28010 48 31 36 36 31 35 5d 20 5b 48 31 36 36 31 38 5d H16615] [H16618]
28020 20 5b 48 31 36 36 32 31 5d 0a 2a 2a 20 5b 48 31 [H16621].** [H1
28030 36 36 32 34 5d 20 5b 48 31 36 36 32 37 5d 20 5b 6624] [H16627] [
28040 48 31 36 36 33 30 5d 0a 2a 2f 0a 69 6e 74 20 73 H16630].*/.int s
28050 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
28060 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 llation(. sqlit
28070 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 e3*, . const ch
28080 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e ar *zName, . in
28090 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 t eTextRep, . v
280a0 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f oid*,. int(*xCo
280b0 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 mpare)(void*,int
280c0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 ,const void*,int
280d0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b ,const void*).);
280e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 .int sqlite3_cre
280f0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 ate_collation_v2
28100 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 (. sqlite3*, .
28110 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
28120 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 me, . int eText
28130 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 Rep, . void*,.
28140 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 int(*xCompare)(
28150 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 void*,int,const
28160 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 void*,int,const
28170 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a void*),. void(*
28180 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 xDestroy)(void*)
28190 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .);.int sqlite3_
281a0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
281b0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 16(. sqlite3*,
281c0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a . const void *z
281d0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 Name,. int eTex
281e0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a tRep, . void*,.
281f0 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 int(*xCompare)
28200 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 (void*,int,const
28210 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 void*,int,const
28220 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a void*).);../*.*
28230 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c * CAPI3REF: Coll
28240 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c ation Needed Cal
28250 6c 62 61 63 6b 73 20 7b 48 31 36 37 30 30 7d 20 lbacks {H16700}
28260 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S20300>.**.** T
28270 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 o avoid having t
28280 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 o register all c
28290 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 ollation sequenc
282a0 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 es before a data
282b0 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 base.** can be u
282c0 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 sed, a single ca
282d0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
282e0 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 may be registere
282f0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 d with the.** [d
28300 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
28310 6f 6e 5d 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 on] to be called
28320 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 whenever an und
28330 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e efined collation
28340 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 .** sequence is
28350 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 required..**.**
28360 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 If the function
28370 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 is registered us
28380 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f ing the sqlite3_
28390 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 collation_needed
283a0 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 () API,.** then
283b0 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65 it is passed the
283c0 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 names of undefi
283d0 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 ned collation se
283e0 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e quences as strin
283f0 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e gs.** encoded in
28400 20 55 54 46 2d 38 2e 20 7b 48 31 36 37 30 33 7d UTF-8. {H16703}
28410 20 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c If sqlite3_coll
28420 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 ation_needed16()
28430 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 is used,.** the
28440 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 names are passe
28450 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d d as UTF-16 in m
28460 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 achine native by
28470 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 41 20 63 te order..** A c
28480 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 all to either fu
28490 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 nction replaces
284a0 61 6e 79 20 65 78 69 73 74 69 6e 67 20 63 61 6c any existing cal
284b0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 lback..**.** Whe
284c0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 n the callback i
284d0 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 s invoked, the f
284e0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 irst argument pa
284f0 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a ssed is a copy.*
28500 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 * of the second
28510 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
28520 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 te3_collation_ne
28530 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c eded() or.** sql
28540 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
28550 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 eeded16(). The
28560 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
28570 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a is the database.
28580 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 ** connection.
28590 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 The third argume
285a0 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 nt is one of [SQ
285b0 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c LITE_UTF8], [SQL
285c0 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a ITE_UTF16BE],.**
285d0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 or [SQLITE_UTF1
285e0 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 6LE], indicating
285f0 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 the most desira
28600 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 ble form of the
28610 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 collation.** seq
28620 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 uence function r
28630 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f equired. The fo
28640 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 urth parameter i
28650 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
28660 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f e.** required co
28670 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 llation sequence
28680 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c ..**.** The call
28690 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 back function sh
286a0 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 ould register th
286b0 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 e desired collat
286c0 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 ion using.** [sq
286d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
286e0 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 lation()], [sqli
286f0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
28700 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a tion16()], or.**
28710 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
28720 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d _collation_v2()]
28730 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
28740 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 37 30 32 ents:.** [H16702
28750 5d 20 5b 48 31 36 37 30 34 5d 20 5b 48 31 36 37 ] [H16704] [H167
28760 30 36 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 06].*/.int sqlit
28770 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 e3_collation_nee
28780 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c ded(. sqlite3*,
28790 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f . void*, . vo
287a0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 id(*)(void*,sqli
287b0 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 te3*,int eTextRe
287c0 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 p,const char*).)
287d0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f ;.int sqlite3_co
287e0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 llation_needed16
287f0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 (. sqlite3*, .
28800 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a void*,. void(*
28810 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a )(void*,sqlite3*
28820 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f ,int eTextRep,co
28830 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f nst void*).);../
28840 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 *.** Specify the
28850 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 key for an encr
28860 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 ypted database.
28870 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 This routine sh
28880 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 ould be.** calle
28890 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71 d right after sq
288a0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a lite3_open()..**
288b0 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 .** The code to
288c0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 implement this A
288d0 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 PI is not availa
288e0 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 ble in the publi
288f0 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 c release.** of
28900 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 SQLite..*/.int s
28910 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 qlite3_key(. sq
28920 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
28930 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
28940 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 Database to be r
28950 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 ekeyed */. cons
28960 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e t void *pKey, in
28970 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 t nKey /* Th
28980 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a e key */.);../*.
28990 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 ** Change the ke
289a0 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 y on an open dat
289b0 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 abase. If the c
289c0 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 urrent database
289d0 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 is not.** encryp
289e0 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e ted, this routin
289f0 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 e will encrypt i
28a00 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f t. If pNew==0 o
28a10 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a r nNew==0, the.*
28a20 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65 * database is de
28a30 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 crypted..**.** T
28a40 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 he code to imple
28a50 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 ment this API is
28a60 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 not available i
28a70 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c n the public rel
28a80 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 ease.** of SQLit
28a90 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 e..*/.int sqlite
28aa0 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 3_rekey(. sqlit
28ab0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
28ac0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
28ad0 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 abase to be reke
28ae0 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 yed */. const v
28af0 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e oid *pKey, int n
28b00 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e Key /* The n
28b10 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a ew key */.);../*
28b20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 .** CAPI3REF: Su
28b30 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 spend Execution
28b40 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 For A Short Time
28b50 20 7b 48 31 30 35 33 30 7d 20 3c 53 34 30 34 31 {H10530} <S4041
28b60 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 0>.**.** The sql
28b70 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e ite3_sleep() fun
28b80 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 ction causes the
28b90 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 current thread
28ba0 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 to suspend execu
28bb0 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c tion.** for at l
28bc0 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 east a number of
28bd0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 milliseconds sp
28be0 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 ecified in its p
28bf0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 arameter..**.**
28c00 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 If the operating
28c10 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 system does not
28c20 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 support sleep r
28c30 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 equests with.**
28c40 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 millisecond time
28c50 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 resolution, the
28c60 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 n the time will
28c70 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f be rounded up to
28c80 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 .** the nearest
28c90 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 second. The numb
28ca0 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e er of millisecon
28cb0 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 ds of sleep actu
28cc0 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 ally.** requeste
28cd0 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 d from the opera
28ce0 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 ting system is r
28cf0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 eturned..**.** S
28d00 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 QLite implements
28d10 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 this interface
28d20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 by calling the x
28d30 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f Sleep().** metho
28d40 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 d of the default
28d50 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f [sqlite3_vfs] o
28d60 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 bject..**.** Req
28d70 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 35 uirements: [H105
28d80 33 33 5d 20 5b 48 31 30 35 33 36 5d 0a 2a 2f 0a 33] [H10536].*/.
28d90 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 int sqlite3_slee
28da0 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 p(int);../*.** C
28db0 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 API3REF: Name Of
28dc0 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 The Folder Hold
28dd0 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 ing Temporary Fi
28de0 6c 65 73 20 7b 48 31 30 33 31 30 7d 20 3c 53 32 les {H10310} <S2
28df0 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 0000>.**.** If t
28e00 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 his global varia
28e10 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 ble is made to p
28e20 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 oint to a string
28e30 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 which is.** the
28e40 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 name of a folde
28e50 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 r (a.k.a. direct
28e60 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 ory), then all t
28e70 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a emporary files.*
28e80 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c * created by SQL
28e90 69 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 ite will be plac
28ea0 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 ed in that direc
28eb0 74 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20 76 tory. If this v
28ec0 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 ariable.** is a
28ed0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 NULL pointer, th
28ee0 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72 en SQLite perfor
28ef0 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 ms a search for
28f00 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a an appropriate.*
28f10 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 * temporary file
28f20 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a directory..**.*
28f30 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 * It is not safe
28f40 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 to read or modi
28f50 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 fy this variable
28f60 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e in more than on
28f70 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61 e.** thread at a
28f80 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f time. It is no
28f90 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f t safe to read o
28fa0 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 r modify this va
28fb0 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b riable.** if a [
28fc0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
28fd0 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73 ion] is being us
28fe0 65 64 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 ed at the same t
28ff0 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61 74 ime in a separat
29000 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 e.** thread..**
29010 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 It is intended t
29020 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c hat this variabl
29030 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a e be set once.**
29040 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 as part of proc
29050 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 ess initializati
29060 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e on and before an
29070 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 y SQLite interfa
29080 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 ce.** routines h
29090 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 ave been called
290a0 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 76 61 and that this va
290b0 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e riable remain un
290c0 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 changed.** there
290d0 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 after..**.** The
290e0 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 [temp_store_dir
290f0 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d ectory pragma] m
29100 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 ay modify this v
29110 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 ariable and caus
29120 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 e.** it to point
29130 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 to memory obtai
29140 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ned from [sqlite
29150 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 46 75 72 74 3_malloc]. Furt
29160 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 hermore,.** the
29170 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 [temp_store_dire
29180 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c ctory pragma] al
29190 77 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 ways assumes tha
291a0 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 t any string.**
291b0 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 that this variab
291c0 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 le points to is
291d0 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f held in memory o
291e0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a btained from .**
291f0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
29200 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 ] and the pragma
29210 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 may attempt to
29220 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 free that memory
29230 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 .** using [sqlit
29240 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e e3_free]..** Hen
29250 63 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 ce, if this vari
29260 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 able is modified
29270 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 directly, eithe
29280 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a r it should be.*
29290 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d * made NULL or m
292a0 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 ade to point to
292b0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 memory obtained
292c0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 from [sqlite3_ma
292d0 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 lloc].** or else
292e0 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 the use of the
292f0 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 [temp_store_dire
29300 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 ctory pragma] sh
29310 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e ould be avoided.
29320 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 .*/.SQLITE_EXTER
29330 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f N char *sqlite3_
29340 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a temp_directory;.
29350 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
29360 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 Test For Auto-C
29370 6f 6d 6d 69 74 20 4d 6f 64 65 20 7b 48 31 32 39 ommit Mode {H129
29380 33 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 30} <S60200>.**
29390 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 KEYWORDS: {autoc
293a0 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a ommit mode}.**.*
293b0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 * The sqlite3_ge
293c0 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 t_autocommit() i
293d0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
293e0 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 non-zero or.**
293f0 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 zero if the give
29400 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 n database conne
29410 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e ction is or is n
29420 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 ot in autocommit
29430 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 mode,.** respec
29440 74 69 76 65 6c 79 2e 20 20 41 75 74 6f 63 6f 6d tively. Autocom
29450 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 mit mode is on b
29460 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 41 75 y default..** Au
29470 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 tocommit mode is
29480 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b disabled by a [
29490 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 BEGIN] statement
294a0 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 ..** Autocommit
294b0 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c mode is re-enabl
294c0 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d ed by a [COMMIT]
294d0 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a or [ROLLBACK]..
294e0 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e **.** If certain
294f0 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 kinds of errors
29500 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74 occur on a stat
29510 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d ement within a m
29520 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a ulti-statement.*
29530 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 * transaction (e
29540 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 rrors including
29550 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b [SQLITE_FULL], [
29560 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a SQLITE_IOERR],.*
29570 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d * [SQLITE_NOMEM]
29580 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c , [SQLITE_BUSY],
29590 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 and [SQLITE_INT
295a0 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68 ERRUPT]) then th
295b0 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e e.** transaction
295c0 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 might be rolled
295d0 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 back automatica
295e0 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 lly. The only w
295f0 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 ay to.** find ou
29600 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 74 65 t whether SQLite
29610 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 automatically r
29620 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74 olled back the t
29630 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72 ransaction after
29640 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20 .** an error is
29650 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63 to use this func
29660 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 tion..**.** If a
29670 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 68 nother thread ch
29680 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f anges the autoco
29690 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 74 mmit status of t
296a0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 he database.** c
296b0 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 onnection while
296c0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 this routine is
296d0 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 running, then th
296e0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a e return value.*
296f0 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a * is undefined..
29700 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
29710 74 73 3a 20 5b 48 31 32 39 33 31 5d 20 5b 48 31 ts: [H12931] [H1
29720 32 39 33 32 5d 20 5b 48 31 32 39 33 33 5d 20 5b 2932] [H12933] [
29730 48 31 32 39 33 34 5d 0a 2a 2f 0a 69 6e 74 20 73 H12934].*/.int s
29740 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 qlite3_get_autoc
29750 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b ommit(sqlite3*);
29760 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
29770 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 : Find The Datab
29780 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 ase Handle Of A
29790 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 Prepared Stateme
297a0 6e 74 20 7b 48 31 33 31 32 30 7d 20 3c 53 36 30 nt {H13120} <S60
297b0 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 600>.**.** The s
297c0 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 qlite3_db_handle
297d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
297e0 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 ns the [database
297f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e connection] han
29800 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 dle.** to which
29810 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
29820 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 ement] belongs.
29830 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 The [database c
29840 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 onnection].** re
29850 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 turned by sqlite
29860 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 3_db_handle is t
29870 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 he same [databas
29880 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 e connection] th
29890 61 74 20 77 61 73 20 74 68 65 20 66 69 72 73 74 at was the first
298a0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 argument.** to
298b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 the [sqlite3_pre
298c0 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 pare_v2()] call
298d0 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 (or its variants
298e0 29 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20 ) that was used
298f0 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 65 to.** create the
29900 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 statement in th
29910 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a e first place..*
29920 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
29930 73 3a 20 5b 48 31 33 31 32 33 5d 0a 2a 2f 0a 73 s: [H13123].*/.s
29940 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f qlite3 *sqlite3_
29950 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 db_handle(sqlite
29960 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 3_stmt*);../*.**
29970 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 CAPI3REF: Find
29980 74 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65 the next prepare
29990 64 20 73 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 d statement {H13
299a0 31 34 30 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a 140} <S60600>.**
299b0 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 .** This interfa
299c0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ce returns a poi
299d0 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74 nter to the next
299e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
299f0 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 ment] after.** p
29a00 53 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20 Stmt associated
29a10 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 with the [databa
29a20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 se connection] p
29a30 44 62 2e 20 20 49 66 20 70 53 74 6d 74 20 69 73 Db. If pStmt is
29a40 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 NULL.** then th
29a50 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 is interface ret
29a60 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
29a70 6f 20 74 68 65 20 66 69 72 73 74 20 70 72 65 70 o the first prep
29a80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a ared statement.*
29a90 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 * associated wit
29aa0 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 h the database c
29ab0 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 onnection pDb.
29ac0 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20 73 If no prepared s
29ad0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 tatement.** sati
29ae0 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74 sfies the condit
29af0 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75 ions of this rou
29b00 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e 73 tine, it returns
29b10 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 NULL..**.** The
29b20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
29b30 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44 ction] pointer D
29b40 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a in a call to.**
29b50 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 [sqlite3_next_s
29b60 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 72 tmt(D,S)] must r
29b70 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20 efer to an open
29b80 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
29b90 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61 ection and in pa
29ba0 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f rticular must no
29bb0 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e t be a NULL poin
29bc0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 ter..**.** Requi
29bd0 72 65 6d 65 6e 74 73 3a 20 5b 48 31 33 31 34 33 rements: [H13143
29be0 5d 20 5b 48 31 33 31 34 36 5d 20 5b 48 31 33 31 ] [H13146] [H131
29bf0 34 39 5d 20 5b 48 31 33 31 35 32 5d 0a 2a 2f 0a 49] [H13152].*/.
29c00 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 sqlite3_stmt *sq
29c10 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 lite3_next_stmt(
29c20 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 sqlite3 *pDb, sq
29c30 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d lite3_stmt *pStm
29c40 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
29c50 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 REF: Commit And
29c60 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 Rollback Notific
29c70 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 ation Callbacks
29c80 7b 48 31 32 39 35 30 7d 20 3c 53 36 30 34 30 30 {H12950} <S60400
29c90 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 >.**.** The sqli
29ca0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 te3_commit_hook(
29cb0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 ) interface regi
29cc0 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b sters a callback
29cd0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 .** function to
29ce0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 be invoked whene
29cf0 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f ver a transactio
29d00 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a n is committed..
29d10 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 ** Any callback
29d20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 set by a previou
29d30 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 s call to sqlite
29d40 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 3_commit_hook().
29d50 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 ** for the same
29d60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
29d70 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 ion is overridde
29d80 6e 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 n..** The sqlite
29d90 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 3_rollback_hook(
29da0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 ) interface regi
29db0 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b sters a callback
29dc0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 .** function to
29dd0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 be invoked whene
29de0 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f ver a transactio
29df0 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a n is committed..
29e00 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 ** Any callback
29e10 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 set by a previou
29e20 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 s call to sqlite
29e30 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 3_commit_hook().
29e40 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 ** for the same
29e50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
29e60 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 ion is overridde
29e70 6e 2e 0a 2a 2a 20 54 68 65 20 70 41 72 67 20 61 n..** The pArg a
29e80 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 rgument is passe
29e90 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 d through to the
29ea0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 49 66 callback..** If
29eb0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e the callback on
29ec0 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 a commit hook f
29ed0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
29ee0 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 non-zero,.** the
29ef0 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 n the commit is
29f00 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 converted into a
29f10 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a rollback..**.**
29f20 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 If another func
29f30 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 tion was previou
29f40 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 sly registered,
29f50 69 74 73 0a 2a 2a 20 70 41 72 67 20 76 61 6c 75 its.** pArg valu
29f60 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 e is returned.
29f70 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 Otherwise NULL i
29f80 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
29f90 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 * The callback i
29fa0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 mplementation mu
29fb0 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 st not do anythi
29fc0 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 ng that will mod
29fd0 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 ify.** the datab
29fe0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 ase connection t
29ff0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 hat invoked the
2a000 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 callback. Any a
2a010 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 ctions.** to mod
2a020 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 ify the database
2a030 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 connection must
2a040 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 be deferred unt
2a050 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 il after the.**
2a060 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 completion of th
2a070 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 e [sqlite3_step(
2a080 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 )] call that tri
2a090 67 67 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 ggered the commi
2a0a0 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b t.** or rollback
2a0b0 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 hook in the fir
2a0c0 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 st place..** Not
2a0d0 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f e that [sqlite3_
2a0e0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e prepare_v2()] an
2a0f0 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 d [sqlite3_step(
2a100 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 )] both modify t
2a110 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 heir.** database
2a120 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 connections for
2a130 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 the meaning of
2a140 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 "modify" in this
2a150 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a paragraph..**.*
2a160 2a 20 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 * Registering a
2a170 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 NULL function di
2a180 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 sables the callb
2a190 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 ack..**.** For t
2a1a0 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 he purposes of t
2a1b0 68 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 his API, a trans
2a1c0 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 action is said t
2a1d0 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72 o have been.** r
2a1e0 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e olled back if an
2a1f0 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 explicit "ROLLB
2a200 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 ACK" statement i
2a210 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a s executed, or.*
2a220 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f * an error or co
2a230 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 nstraint causes
2a240 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c an implicit roll
2a250 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a back to occur..*
2a260 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 * The rollback c
2a270 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 allback is not i
2a280 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e nvoked if a tran
2a290 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 saction is.** au
2a2a0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c tomatically roll
2a2b0 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 ed back because
2a2c0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
2a2d0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 nection is close
2a2e0 64 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 d..** The rollba
2a2f0 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e ck callback is n
2a300 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 ot invoked if a
2a310 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a transaction is.*
2a320 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 * rolled back be
2a330 63 61 75 73 65 20 61 20 63 6f 6d 6d 69 74 20 63 cause a commit c
2a340 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 65 64 allback returned
2a350 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c 74 non-zero..** <t
2a360 6f 64 6f 3e 20 43 68 65 63 6b 20 6f 6e 20 74 68 odo> Check on th
2a370 69 73 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a is </todo>.**.**
2a380 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
2a390 2a 20 5b 48 31 32 39 35 31 5d 20 5b 48 31 32 39 * [H12951] [H129
2a3a0 35 32 5d 20 5b 48 31 32 39 35 33 5d 20 5b 48 31 52] [H12953] [H1
2a3b0 32 39 35 34 5d 20 5b 48 31 32 39 35 35 5d 0a 2a 2954] [H12955].*
2a3c0 2a 20 5b 48 31 32 39 36 31 5d 20 5b 48 31 32 39 * [H12961] [H129
2a3d0 36 32 5d 20 5b 48 31 32 39 36 33 5d 20 5b 48 31 62] [H12963] [H1
2a3e0 32 39 36 34 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 2964].*/.void *s
2a3f0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f qlite3_commit_ho
2a400 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 ok(sqlite3*, int
2a410 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 (*)(void*), void
2a420 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 *);.void *sqlite
2a430 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 3_rollback_hook(
2a440 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a sqlite3*, void(*
2a450 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a )(void *), void*
2a460 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2a470 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 EF: Data Change
2a480 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c Notification Cal
2a490 6c 62 61 63 6b 73 20 7b 48 31 32 39 37 30 7d 20 lbacks {H12970}
2a4a0 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S60400>.**.** T
2a4b0 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 he sqlite3_updat
2a4c0 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 e_hook() interfa
2a4d0 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 ce registers a c
2a4e0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
2a4f0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 .** with the [da
2a500 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2a510 6e 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 n] identified by
2a520 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
2a530 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 ent.** to be inv
2a540 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 oked whenever a
2a550 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 row is updated,
2a560 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 inserted or dele
2a570 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c ted..** Any call
2a580 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 back set by a pr
2a590 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 evious call to t
2a5a0 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 his function.**
2a5b0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 for the same dat
2a5c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2a5d0 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a is overridden..
2a5e0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 **.** The second
2a5f0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 argument is a p
2a600 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75 ointer to the fu
2a610 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 nction to invoke
2a620 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 when a.** row i
2a630 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 s updated, inser
2a640 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a ted or deleted..
2a650 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 ** The first arg
2a660 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c ument to the cal
2a670 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 lback is a copy
2a680 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72 67 of the third arg
2a690 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 ument.** to sqli
2a6a0 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 te3_update_hook(
2a6b0 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 )..** The second
2a6c0 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 callback argume
2a6d0 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 nt is one of [SQ
2a6e0 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 LITE_INSERT], [S
2a6f0 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a QLITE_DELETE],.*
2a700 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 * or [SQLITE_UPD
2a710 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20 ATE], depending
2a720 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e on the operation
2a730 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65 that caused the
2a740 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 callback.** to
2a750 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 54 be invoked..** T
2a760 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 he third and fou
2a770 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f rth arguments to
2a780 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f the callback co
2a790 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 ntain pointers t
2a7a0 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 o the.** databas
2a7b0 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65 e and table name
2a7c0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 containing the
2a7d0 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a affected row..**
2a7e0 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 The final callb
2a7f0 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 ack parameter is
2a800 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 the [rowid] of
2a810 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 49 6e 20 74 the row..** In t
2a820 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70 he case of an up
2a830 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 74 68 date, this is th
2a840 65 20 5b 72 6f 77 69 64 5d 20 61 66 74 65 72 20 e [rowid] after
2a850 74 68 65 20 75 70 64 61 74 65 20 74 61 6b 65 73 the update takes
2a860 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 place..**.** Th
2a870 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 e update hook is
2a880 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 not invoked whe
2a890 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 n internal syste
2a8a0 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 m tables are.**
2a8b0 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73 modified (i.e. s
2a8c0 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 qlite_master and
2a8d0 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 sqlite_sequence
2a8e0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 )..**.** The upd
2a8f0 61 74 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65 ate hook impleme
2a900 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 ntation must not
2a910 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 do anything tha
2a920 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a t will modify.**
2a930 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
2a940 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e nnection that in
2a950 76 6f 6b 65 64 20 74 68 65 20 75 70 64 61 74 65 voked the update
2a960 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 74 69 hook. Any acti
2a970 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 ons.** to modify
2a980 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
2a990 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 nnection must be
2a9a0 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 deferred until
2a9b0 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d after the.** com
2a9c0 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b pletion of the [
2a9d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
2a9e0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 call that trigge
2a9f0 72 65 64 20 74 68 65 20 75 70 64 61 74 65 20 68 red the update h
2aa00 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ook..** Note tha
2aa10 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 t [sqlite3_prepa
2aa20 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 re_v2()] and [sq
2aa30 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f lite3_step()] bo
2aa40 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a th modify their.
2aa50 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ** database conn
2aa60 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 ections for the
2aa70 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 meaning of "modi
2aa80 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 fy" in this para
2aa90 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 graph..**.** If
2aaa0 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e another function
2aab0 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 was previously
2aac0 72 65 67 69 73 74 65 72 65 64 2c 20 69 74 73 20 registered, its
2aad0 70 41 72 67 20 76 61 6c 75 65 0a 2a 2a 20 69 73 pArg value.** is
2aae0 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 returned. Othe
2aaf0 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 rwise NULL is re
2ab00 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 turned..**.** Re
2ab10 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
2ab20 48 31 32 39 37 31 5d 20 5b 48 31 32 39 37 33 5d H12971] [H12973]
2ab30 20 5b 48 31 32 39 37 35 5d 20 5b 48 31 32 39 37 [H12975] [H1297
2ab40 37 5d 20 5b 48 31 32 39 37 39 5d 20 5b 48 31 32 7] [H12979] [H12
2ab50 39 38 31 5d 20 5b 48 31 32 39 38 33 5d 20 5b 48 981] [H12983] [H
2ab60 31 32 39 38 36 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 12986].*/.void *
2ab70 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 sqlite3_update_h
2ab80 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c ook(. sqlite3*,
2ab90 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 . void(*)(void
2aba0 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e *,int ,char con
2abb0 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 st *,char const
2abc0 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 *,sqlite3_int64)
2abd0 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a ,. void*.);../*
2abe0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e .** CAPI3REF: En
2abf0 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 able Or Disable
2ac00 53 68 61 72 65 64 20 50 61 67 65 72 20 43 61 63 Shared Pager Cac
2ac10 68 65 20 7b 48 31 30 33 33 30 7d 20 3c 53 33 30 he {H10330} <S30
2ac20 39 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 900>.** KEYWORDS
2ac30 3a 20 7b 73 68 61 72 65 64 20 63 61 63 68 65 7d : {shared cache}
2ac40 20 7b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d {shared cache m
2ac50 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ode}.**.** This
2ac60 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 routine enables
2ac70 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 or disables the
2ac80 73 68 61 72 69 6e 67 20 6f 66 20 74 68 65 20 64 sharing of the d
2ac90 61 74 61 62 61 73 65 20 63 61 63 68 65 0a 2a 2a atabase cache.**
2aca0 20 61 6e 64 20 73 63 68 65 6d 61 20 64 61 74 61 and schema data
2acb0 20 73 74 72 75 63 74 75 72 65 73 20 62 65 74 77 structures betw
2acc0 65 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f een [database co
2acd0 6e 6e 65 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65 nnection | conne
2ace0 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68 ctions].** to th
2acf0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e e same database.
2ad00 20 53 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 Sharing is enab
2ad10 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d led if the argum
2ad20 65 6e 74 20 69 73 20 74 72 75 65 0a 2a 2a 20 61 ent is true.** a
2ad30 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66 20 74 nd disabled if t
2ad40 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 66 he argument is f
2ad50 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 43 61 63 68 alse..**.** Cach
2ad60 65 20 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61 e sharing is ena
2ad70 62 6c 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65 bled and disable
2ad80 64 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20 d for an entire
2ad90 70 72 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 69 73 process..** This
2ada0 20 69 73 20 61 20 63 68 61 6e 67 65 20 61 73 20 is a change as
2adb0 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f of SQLite versio
2adc0 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69 6f n 3.5.0. In prio
2add0 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 r versions of SQ
2ade0 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 Lite,.** sharing
2adf0 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 was enabled or
2ae00 64 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63 disabled for eac
2ae10 68 20 74 68 72 65 61 64 20 73 65 70 61 72 61 74 h thread separat
2ae20 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 ely..**.** The c
2ae30 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 ache sharing mod
2ae40 65 20 73 65 74 20 62 79 20 74 68 69 73 20 69 6e e set by this in
2ae50 74 65 72 66 61 63 65 20 65 66 66 65 63 74 73 20 terface effects
2ae60 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a all subsequent.*
2ae70 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 * calls to [sqli
2ae80 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 te3_open()], [sq
2ae90 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d lite3_open_v2()]
2aea0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f , and [sqlite3_o
2aeb0 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 pen16()]..** Exi
2aec0 73 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 63 sting database c
2aed0 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 onnections conti
2aee0 6e 75 65 20 75 73 65 20 74 68 65 20 73 68 61 72 nue use the shar
2aef0 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 ing mode.** that
2af00 20 77 61 73 20 69 6e 20 65 66 66 65 63 74 20 61 was in effect a
2af10 74 20 74 68 65 20 74 69 6d 65 20 74 68 65 79 20 t the time they
2af20 77 65 72 65 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a were opened..**.
2af30 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 ** Virtual table
2af40 73 20 63 61 6e 6e 6f 74 20 62 65 20 75 73 65 64 s cannot be used
2af50 20 77 69 74 68 20 61 20 73 68 61 72 65 64 20 63 with a shared c
2af60 61 63 68 65 2e 20 20 57 68 65 6e 20 73 68 61 72 ache. When shar
2af70 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 ed.** cache is e
2af80 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c nabled, the [sql
2af90 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 ite3_create_modu
2afa0 6c 65 28 29 5d 20 41 50 49 20 75 73 65 64 20 74 le()] API used t
2afb0 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 76 69 o register.** vi
2afc0 72 74 75 61 6c 20 74 61 62 6c 65 73 20 77 69 6c rtual tables wil
2afd0 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 l always return
2afe0 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 an error..**.**
2aff0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 This routine ret
2b000 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d urns [SQLITE_OK]
2b010 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65 if shared cache
2b020 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 was enabled or
2b030 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63 disabled.** succ
2b040 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 essfully. An [e
2b050 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 rror code] is re
2b060 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65 turned otherwise
2b070 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65 64 20 63 ..**.** Shared c
2b080 61 63 68 65 20 69 73 20 64 69 73 61 62 6c 65 64 ache is disabled
2b090 20 62 79 20 64 65 66 61 75 6c 74 2e 20 42 75 74 by default. But
2b0a0 20 74 68 69 73 20 6d 69 67 68 74 20 63 68 61 6e this might chan
2b0b0 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 ge in.** future
2b0c0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 releases of SQLi
2b0d0 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e te. Application
2b0e0 73 20 74 68 61 74 20 63 61 72 65 20 61 62 6f 75 s that care abou
2b0f0 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 t shared.** cach
2b100 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75 6c 64 e setting should
2b110 20 73 65 74 20 69 74 20 65 78 70 6c 69 63 69 74 set it explicit
2b120 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c ly..**.** See Al
2b130 73 6f 3a 20 20 5b 53 51 4c 69 74 65 20 53 68 61 so: [SQLite Sha
2b140 72 65 64 2d 43 61 63 68 65 20 4d 6f 64 65 5d 0a red-Cache Mode].
2b150 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
2b160 74 73 3a 20 5b 48 31 30 33 33 31 5d 20 5b 48 31 ts: [H10331] [H1
2b170 30 33 33 36 5d 20 5b 48 31 30 33 33 37 5d 20 5b 0336] [H10337] [
2b180 48 31 30 33 33 39 5d 0a 2a 2f 0a 69 6e 74 20 73 H10339].*/.int s
2b190 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 qlite3_enable_sh
2b1a0 61 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b ared_cache(int);
2b1b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2b1c0 3a 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65 : Attempt To Fre
2b1d0 65 20 48 65 61 70 20 4d 65 6d 6f 72 79 20 7b 48 e Heap Memory {H
2b1e0 31 37 33 34 30 7d 20 3c 53 33 30 32 32 30 3e 0a 17340} <S30220>.
2b1f0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
2b200 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 3_release_memory
2b210 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 () interface att
2b220 65 6d 70 74 73 20 74 6f 20 66 72 65 65 20 4e 20 empts to free N
2b230 62 79 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 bytes.** of heap
2b240 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c memory by deall
2b250 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 ocating non-esse
2b260 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c ntial memory all
2b270 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 ocations.** held
2b280 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65 by the database
2b290 20 6c 69 62 72 61 72 79 2e 20 7b 45 4e 44 7d 20 library. {END}
2b2a0 20 4d 65 6d 6f 72 79 20 75 73 65 64 20 74 6f 20 Memory used to
2b2b0 63 61 63 68 65 20 64 61 74 61 62 61 73 65 0a 2a cache database.*
2b2c0 2a 20 70 61 67 65 73 20 74 6f 20 69 6d 70 72 6f * pages to impro
2b2d0 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 69 ve performance i
2b2e0 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 s an example of
2b2f0 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 non-essential me
2b300 6d 6f 72 79 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 mory..** sqlite3
2b310 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 _release_memory(
2b320 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 ) returns the nu
2b330 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 61 63 mber of bytes ac
2b340 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 0a 2a 2a tually freed,.**
2b350 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 which might be
2b360 6d 6f 72 65 20 6f 72 20 6c 65 73 73 20 74 68 61 more or less tha
2b370 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 n the amount req
2b380 75 65 73 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 uested..**.** Re
2b390 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 37 quirements: [H17
2b3a0 33 34 31 5d 20 5b 48 31 37 33 34 32 5d 0a 2a 2f 341] [H17342].*/
2b3b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c .int sqlite3_rel
2b3c0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 ease_memory(int)
2b3d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2b3e0 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 F: Impose A Limi
2b3f0 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 20 7b t On Heap Size {
2b400 48 31 37 33 35 30 7d 20 3c 53 33 30 32 32 30 3e H17350} <S30220>
2b410 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
2b420 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d e3_soft_heap_lim
2b430 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 70 it() interface p
2b440 6c 61 63 65 73 20 61 20 22 73 6f 66 74 22 20 6c laces a "soft" l
2b450 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 61 imit.** on the a
2b460 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 mount of heap me
2b470 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 mory that may be
2b480 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 allocated by SQ
2b490 4c 69 74 65 2e 0a 2a 2a 20 49 66 20 61 6e 20 69 Lite..** If an i
2b4a0 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 nternal allocati
2b4b0 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 20 on is requested
2b4c0 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65 65 that would excee
2b4d0 64 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 68 65 d the.** soft he
2b4e0 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74 ap limit, [sqlit
2b4f0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 e3_release_memor
2b500 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20 y()] is invoked
2b510 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 one or.** more t
2b520 69 6d 65 73 20 74 6f 20 66 72 65 65 20 75 70 20 imes to free up
2b530 73 6f 6d 65 20 73 70 61 63 65 20 62 65 66 6f 72 some space befor
2b540 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e e the allocation
2b550 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a is performed..*
2b560 2a 0a 2a 2a 20 54 68 65 20 6c 69 6d 69 74 20 69 *.** The limit i
2b570 73 20 63 61 6c 6c 65 64 20 22 73 6f 66 74 22 2c s called "soft",
2b580 20 62 65 63 61 75 73 65 20 69 66 20 5b 73 71 6c because if [sql
2b590 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d ite3_release_mem
2b5a0 6f 72 79 28 29 5d 0a 2a 2a 20 63 61 6e 6e 6f 74 ory()].** cannot
2b5b0 20 66 72 65 65 20 73 75 66 66 69 63 69 65 6e 74 free sufficient
2b5c0 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65 76 65 memory to preve
2b5d0 6e 74 20 74 68 65 20 6c 69 6d 69 74 20 66 72 6f nt the limit fro
2b5e0 6d 20 62 65 69 6e 67 20 65 78 63 65 65 64 65 64 m being exceeded
2b5f0 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 ,.** the memory
2b600 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 79 is allocated any
2b610 77 61 79 20 61 6e 64 20 74 68 65 20 63 75 72 72 way and the curr
2b620 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 ent operation pr
2b630 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 oceeds..**.** A
2b640 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f negative or zero
2b650 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61 value for N mea
2b660 6e 73 20 74 68 61 74 20 74 68 65 72 65 20 69 73 ns that there is
2b670 20 6e 6f 20 73 6f 66 74 20 68 65 61 70 20 6c 69 no soft heap li
2b680 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 mit and.** [sqli
2b690 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f te3_release_memo
2b6a0 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 ry()] will only
2b6b0 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d be called when m
2b6c0 65 6d 6f 72 79 20 69 73 20 65 78 68 61 75 73 74 emory is exhaust
2b6d0 65 64 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 ed..** The defau
2b6e0 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 lt value for the
2b6f0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 soft heap limit
2b700 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 is zero..**.**
2b710 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 62 SQLite makes a b
2b720 65 73 74 20 65 66 66 6f 72 74 20 74 6f 20 68 6f est effort to ho
2b730 6e 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 nor the soft hea
2b740 70 20 6c 69 6d 69 74 2e 0a 2a 2a 20 42 75 74 20 p limit..** But
2b750 69 66 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 if the soft heap
2b760 20 6c 69 6d 69 74 20 63 61 6e 6e 6f 74 20 62 65 limit cannot be
2b770 20 68 6f 6e 6f 72 65 64 2c 20 65 78 65 63 75 74 honored, execut
2b780 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 ion will.** cont
2b790 69 6e 75 65 20 77 69 74 68 6f 75 74 20 65 72 72 inue without err
2b7a0 6f 72 20 6f 72 20 6e 6f 74 69 66 69 63 61 74 69 or or notificati
2b7b0 6f 6e 2e 20 20 54 68 69 73 20 69 73 20 77 68 79 on. This is why
2b7c0 20 74 68 65 20 6c 69 6d 69 74 20 69 73 0a 2a 2a the limit is.**
2b7d0 20 63 61 6c 6c 65 64 20 61 20 22 73 6f 66 74 22 called a "soft"
2b7e0 20 6c 69 6d 69 74 2e 20 20 49 74 20 69 73 20 61 limit. It is a
2b7f0 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a dvisory only..**
2b800 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c .** Prior to SQL
2b810 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e ite version 3.5.
2b820 30 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 0, this routine
2b830 6f 6e 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65 64 only constrained
2b840 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 the memory.** a
2b850 6c 6c 6f 63 61 74 65 64 20 62 79 20 61 20 73 69 llocated by a si
2b860 6e 67 6c 65 20 74 68 72 65 61 64 20 2d 20 74 68 ngle thread - th
2b870 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e e same thread in
2b880 20 77 68 69 63 68 20 74 68 69 73 20 72 6f 75 74 which this rout
2b890 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42 65 ine.** runs. Be
2b8a0 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c ginning with SQL
2b8b0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e ite version 3.5.
2b8c0 30 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 0, the soft heap
2b8d0 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70 70 limit is.** app
2b8e0 6c 69 65 64 20 74 6f 20 61 6c 6c 20 74 68 72 65 lied to all thre
2b8f0 61 64 73 2e 20 54 68 65 20 76 61 6c 75 65 20 73 ads. The value s
2b900 70 65 63 69 66 69 65 64 20 66 6f 72 20 74 68 65 pecified for the
2b910 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 soft heap limit
2b920 0a 2a 2a 20 69 73 20 61 6e 20 75 70 70 65 72 20 .** is an upper
2b930 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 74 6f 74 bound on the tot
2b940 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 al memory alloca
2b950 74 69 6f 6e 20 66 6f 72 20 61 6c 6c 20 74 68 72 tion for all thr
2b960 65 61 64 73 2e 20 49 6e 0a 2a 2a 20 76 65 72 73 eads. In.** vers
2b970 69 6f 6e 20 33 2e 35 2e 30 20 74 68 65 72 65 20 ion 3.5.0 there
2b980 69 73 20 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20 is no mechanism
2b990 66 6f 72 20 6c 69 6d 69 74 69 6e 67 20 74 68 65 for limiting the
2b9a0 20 68 65 61 70 20 75 73 61 67 65 20 66 6f 72 0a heap usage for.
2b9b0 2a 2a 20 69 6e 64 69 76 69 64 75 61 6c 20 74 68 ** individual th
2b9c0 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 reads..**.** Req
2b9d0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
2b9e0 31 36 33 35 31 5d 20 5b 48 31 36 33 35 32 5d 20 16351] [H16352]
2b9f0 5b 48 31 36 33 35 33 5d 20 5b 48 31 36 33 35 34 [H16353] [H16354
2ba00 5d 20 5b 48 31 36 33 35 35 5d 20 5b 48 31 36 33 ] [H16355] [H163
2ba10 35 38 5d 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 58].*/.void sqli
2ba20 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 te3_soft_heap_li
2ba30 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a mit(int);../*.**
2ba40 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 72 61 CAPI3REF: Extra
2ba50 63 74 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75 ct Metadata Abou
2ba60 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 t A Column Of A
2ba70 54 61 62 6c 65 20 7b 48 31 32 38 35 30 7d 20 3c Table {H12850} <
2ba80 53 36 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S60300>.**.** Th
2ba90 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 is routine retur
2baa0 6e 73 20 6d 65 74 61 64 61 74 61 20 61 62 6f 75 ns metadata abou
2bab0 74 20 61 20 73 70 65 63 69 66 69 63 20 63 6f 6c t a specific col
2bac0 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 69 66 69 umn of a specifi
2bad0 63 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 74 61 c.** database ta
2bae0 62 6c 65 20 61 63 63 65 73 73 69 62 6c 65 20 75 ble accessible u
2baf0 73 69 6e 67 20 74 68 65 20 5b 64 61 74 61 62 61 sing the [databa
2bb00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 se connection] h
2bb10 61 6e 64 6c 65 0a 2a 2a 20 70 61 73 73 65 64 20 andle.** passed
2bb20 61 73 20 74 68 65 20 66 69 72 73 74 20 66 75 6e as the first fun
2bb30 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a ction argument..
2bb40 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6c 75 6d 6e **.** The column
2bb50 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 is identified b
2bb60 79 20 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 y the second, th
2bb70 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 ird and fourth p
2bb80 61 72 61 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20 arameters to.**
2bb90 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54 this function. T
2bba0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
2bbb0 74 65 72 20 69 73 20 65 69 74 68 65 72 20 74 68 ter is either th
2bbc0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 e name of the da
2bbd0 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 tabase.** (i.e.
2bbe0 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 20 6f "main", "temp" o
2bbf0 72 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 r an attached da
2bc00 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 tabase) containi
2bc10 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 65 64 ng the specified
2bc20 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c .** table or NUL
2bc30 4c 2e 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c L. If it is NULL
2bc40 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 , then all attac
2bc50 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61 72 hed databases ar
2bc60 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f e searched.** fo
2bc70 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e r the table usin
2bc80 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 g the same algor
2bc90 69 74 68 6d 20 75 73 65 64 20 62 79 20 74 68 65 ithm used by the
2bca0 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 database engine
2bcb0 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 to.** resolve u
2bcc0 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65 nqualified table
2bcd0 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a references..**.
2bce0 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 ** The third and
2bcf0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
2bd00 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 rs to this funct
2bd10 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c ion are the tabl
2bd20 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 e and column.**
2bd30 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69 name of the desi
2bd40 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 red column, resp
2bd50 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 ectively. Neithe
2bd60 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d r of these param
2bd70 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20 eters.** may be
2bd80 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74 61 NULL..**.** Meta
2bd90 64 61 74 61 20 69 73 20 72 65 74 75 72 6e 65 64 data is returned
2bda0 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74 by writing to t
2bdb0 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 he memory locati
2bdc0 6f 6e 73 20 70 61 73 73 65 64 20 61 73 20 74 68 ons passed as th
2bdd0 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62 e 5th.** and sub
2bde0 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65 sequent paramete
2bdf0 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 rs to this funct
2be00 69 6f 6e 2e 20 41 6e 79 20 6f 66 20 74 68 65 73 ion. Any of thes
2be10 65 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 e arguments may
2be20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 be.** NULL, in w
2be30 68 69 63 68 20 63 61 73 65 20 74 68 65 20 63 6f hich case the co
2be40 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d rresponding elem
2be50 65 6e 74 20 6f 66 20 6d 65 74 61 64 61 74 61 20 ent of metadata
2be60 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a is omitted..**.*
2be70 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a * <blockquote>.*
2be80 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d * <table border=
2be90 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e "1">.** <tr><th>
2bea0 20 50 61 72 61 6d 65 74 65 72 20 3c 74 68 3e 20 Parameter <th>
2beb0 4f 75 74 70 75 74 3c 62 72 3e 54 79 70 65 20 3c Output<br>Type <
2bec0 74 68 3e 20 20 44 65 73 63 72 69 70 74 69 6f 6e th> Description
2bed0 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 .**.** <tr><td>
2bee0 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 5th <td> const c
2bef0 68 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 20 74 har* <td> Data t
2bf00 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 ype.** <tr><td>
2bf10 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 6th <td> const c
2bf20 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 6f har* <td> Name o
2bf30 66 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 f default collat
2bf40 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a 20 ion sequence.**
2bf50 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74 64 <tr><td> 7th <td
2bf60 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 > int <t
2bf70 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d d> True if colum
2bf80 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c n has a NOT NULL
2bf90 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 3c constraint.** <
2bfa0 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64 3e tr><td> 8th <td>
2bfb0 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 int <td
2bfc0 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e > True if column
2bfd0 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 is part of the
2bfe0 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 3c PRIMARY KEY.** <
2bff0 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64 3e tr><td> 9th <td>
2c000 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 int <td
2c010 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e > True if column
2c020 20 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d 45 is [AUTOINCREME
2c030 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a NT].** </table>.
2c040 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e ** </blockquote>
2c050 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 .**.** The memor
2c060 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 y pointed to by
2c070 74 68 65 20 63 68 61 72 61 63 74 65 72 20 70 6f the character po
2c080 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 inters returned
2c090 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65 63 6c 61 for the.** decla
2c0a0 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 ration type and
2c0b0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e collation sequen
2c0c0 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 ce is valid only
2c0d0 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 0a until the next.
2c0e0 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 53 ** call to any S
2c0f0 51 4c 69 74 65 20 41 50 49 20 66 75 6e 63 74 69 QLite API functi
2c100 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 on..**.** If the
2c110 20 73 70 65 63 69 66 69 65 64 20 74 61 62 6c 65 specified table
2c120 20 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76 is actually a v
2c130 69 65 77 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 iew, an [error c
2c140 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 ode] is returned
2c150 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 ..**.** If the s
2c160 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 pecified column
2c170 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 is "rowid", "oid
2c180 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 " or "_rowid_" a
2c190 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45 nd an.** [INTEGE
2c1a0 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 R PRIMARY KEY] c
2c1b0 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 olumn has been e
2c1c0 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 xplicitly declar
2c1d0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 ed, then the out
2c1e0 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 put.** parameter
2c1f0 73 20 61 72 65 20 73 65 74 20 66 6f 72 20 74 68 s are set for th
2c200 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 e explicitly dec
2c210 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 49 66 lared column. If
2c220 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 there is no.**
2c230 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 explicitly decla
2c240 72 65 64 20 5b 49 4e 54 45 47 45 52 20 50 52 49 red [INTEGER PRI
2c250 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e MARY KEY] column
2c260 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 , then the outpu
2c270 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 t.** parameters
2c280 61 72 65 20 73 65 74 20 61 73 20 66 6f 6c 6c 6f are set as follo
2c290 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a ws:.**.** <pre>.
2c2a0 2a 2a 20 20 20 20 20 64 61 74 61 20 74 79 70 65 ** data type
2c2b0 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 : "INTEGER".**
2c2c0 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 collation seq
2c2d0 75 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 0a uence: "BINARY".
2c2e0 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a ** not null:
2c2f0 20 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 0.** primar
2c300 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 y key: 1.**
2c310 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 auto increment:
2c320 30 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 0.** </pre>.**.*
2c330 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 * This function
2c340 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 may load one or
2c350 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f more schemas fro
2c360 6d 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 m database files
2c370 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 . If an.** error
2c380 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 occurs during t
2c390 68 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 his process, or
2c3a0 69 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64 if the requested
2c3b0 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e table or column
2c3c0 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f .** cannot be fo
2c3d0 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 und, an [error c
2c3e0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 ode] is returned
2c3f0 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 and an error me
2c400 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69 6e ssage left.** in
2c410 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
2c420 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20 62 onnection] (to b
2c430 65 20 72 65 74 72 69 65 76 65 64 20 75 73 69 6e e retrieved usin
2c440 67 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 g sqlite3_errmsg
2c450 28 29 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ())..**.** This
2c460 41 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 API is only avai
2c470 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 lable if the lib
2c480 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 rary was compile
2c490 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 d with the.** [S
2c4a0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c QLITE_ENABLE_COL
2c4b0 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d UMN_METADATA] C-
2c4c0 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d preprocessor sym
2c4d0 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a bol defined..*/.
2c4e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c int sqlite3_tabl
2c4f0 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 e_column_metadat
2c500 61 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 a(. sqlite3 *db
2c510 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
2c520 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 /* Connection h
2c530 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
2c540 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 char *zDbName,
2c550 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
2c560 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 se name or NULL
2c570 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
2c580 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 *zTableName,
2c590 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a /* Table name *
2c5a0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
2c5b0 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 zColumnName,
2c5c0 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a /* Column name *
2c5d0 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a /. char const *
2c5e0 2a 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 *pzDataType,
2c5f0 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 /* OUTPUT: Decla
2c600 72 65 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f red data type */
2c610 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a . char const **
2c620 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f pzCollSeq, /
2c630 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 * OUTPUT: Collat
2c640 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d ion sequence nam
2c650 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 e */. int *pNot
2c660 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 Null,
2c670 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 /* OUTPUT: Tr
2c680 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 ue if NOT NULL c
2c690 6f 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 onstraint exists
2c6a0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d */. int *pPrim
2c6b0 61 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 aryKey,
2c6c0 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 /* OUTPUT: Tru
2c6d0 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 e if column part
2c6e0 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 of PK */. int
2c6f0 2a 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 *pAutoinc
2c700 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 /* OUTPU
2c710 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d T: True if colum
2c720 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d n is auto-increm
2c730 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a ent */.);../*.**
2c740 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 CAPI3REF: Load
2c750 41 6e 20 45 78 74 65 6e 73 69 6f 6e 20 7b 48 31 An Extension {H1
2c760 32 36 30 30 7d 20 3c 53 32 30 35 30 30 3e 0a 2a 2600} <S20500>.*
2c770 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 *.** This interf
2c780 61 63 65 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c ace loads an SQL
2c790 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 ite extension li
2c7a0 62 72 61 72 79 20 66 72 6f 6d 20 74 68 65 20 6e brary from the n
2c7b0 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a amed file..**.**
2c7c0 20 7b 48 31 32 36 30 31 7d 20 54 68 65 20 73 71 {H12601} The sq
2c7d0 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e lite3_load_exten
2c7e0 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 sion() interface
2c7f0 20 61 74 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61 attempts to loa
2c800 64 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 d an.**
2c810 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f SQLite extensio
2c820 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 n library contai
2c830 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65 20 ned in the file
2c840 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 zFile..**.** {H1
2c850 32 36 30 32 7d 20 54 68 65 20 65 6e 74 72 79 20 2602} The entry
2c860 70 6f 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e 0a point is zProc..
2c870 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 33 7d 20 7a **.** {H12603} z
2c880 50 72 6f 63 20 6d 61 79 20 62 65 20 30 2c 20 69 Proc may be 0, i
2c890 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 n which case the
2c8a0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 name of the ent
2c8b0 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 20 20 20 20 ry point.**
2c8c0 20 20 20 20 20 64 65 66 61 75 6c 74 73 20 74 6f defaults to
2c8d0 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 73 "sqlite3_extens
2c8e0 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 0a 2a 2a ion_init"..**.**
2c8f0 20 7b 48 31 32 36 30 34 7d 20 54 68 65 20 73 71 {H12604} The sq
2c900 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e lite3_load_exten
2c910 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 sion() interface
2c920 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a shall return.**
2c930 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 [SQLIT
2c940 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 E_OK] on success
2c950 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 and [SQLITE_ERR
2c960 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e 67 OR] if something
2c970 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 0a goes wrong..**.
2c980 2a 2a 20 7b 48 31 32 36 30 35 7d 20 49 66 20 61 ** {H12605} If a
2c990 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 61 n error occurs a
2c9a0 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20 6e nd pzErrMsg is n
2c9b0 6f 74 20 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a ot 0, then the.*
2c9c0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
2c9d0 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 te3_load_extensi
2c9e0 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 on()] interface
2c9f0 73 68 61 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f shall attempt to
2ca00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c .** fil
2ca10 6c 20 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68 l *pzErrMsg with
2ca20 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 error message t
2ca30 65 78 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65 ext stored in me
2ca40 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 mory.**
2ca50 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
2ca60 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
2ca70 5d 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20 63 61 ]. {END} The ca
2ca80 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a lling function.*
2ca90 2a 20 20 20 20 20 20 20 20 20 20 73 68 6f 75 6c * shoul
2caa0 64 20 66 72 65 65 20 74 68 69 73 20 6d 65 6d 6f d free this memo
2cab0 72 79 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 ry by calling [s
2cac0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a qlite3_free()]..
2cad0 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 36 7d 20 45 **.** {H12606} E
2cae0 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 xtension loading
2caf0 20 6d 75 73 74 20 62 65 20 65 6e 61 62 6c 65 64 must be enabled
2cb00 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 using.**
2cb10 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 [sqlite3_enab
2cb20 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f le_load_extensio
2cb30 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 63 61 n()] prior to ca
2cb40 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 2c 0a lling this API,.
2cb50 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 74 68 65 ** othe
2cb60 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 77 rwise an error w
2cb70 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e ill be returned.
2cb80 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
2cb90 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a load_extension(.
2cba0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
2cbb0 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 /* Load
2cbc0 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e the extension in
2cbd0 74 6f 20 74 68 69 73 20 64 61 74 61 62 61 73 65 to this database
2cbe0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 connection */.
2cbf0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 const char *zFi
2cc00 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f le, /* Name o
2cc10 66 20 74 68 65 20 73 68 61 72 65 64 20 6c 69 62 f the shared lib
2cc20 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 rary containing
2cc30 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 extension */. c
2cc40 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 onst char *zProc
2cc50 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f , /* Entry po
2cc60 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66 72 int. Derived fr
2cc70 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f om zFile if 0 */
2cc80 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d . char **pzErrM
2cc90 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20 sg /* Put
2cca0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65 error message he
2ccb0 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 re if not 0 */.)
2ccc0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2ccd0 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 F: Enable Or Dis
2cce0 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c able Extension L
2ccf0 6f 61 64 69 6e 67 20 7b 48 31 32 36 32 30 7d 20 oading {H12620}
2cd00 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 <S20500>.**.** S
2cd10 6f 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e o as not to open
2cd20 20 73 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20 security holes
2cd30 69 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 in older applica
2cd40 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a tions that are.*
2cd50 2a 20 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20 * unprepared to
2cd60 64 65 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73 deal with extens
2cd70 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 ion loading, and
2cd80 20 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 as a means of d
2cd90 69 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 isabling.** exte
2cda0 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 nsion loading wh
2cdb0 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75 ile evaluating u
2cdc0 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c ser-entered SQL,
2cdd0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 the following A
2cde0 50 49 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64 65 PI.** is provide
2cdf0 64 20 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 d to turn the [s
2ce00 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 qlite3_load_exte
2ce10 6e 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 nsion()] mechani
2ce20 73 6d 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a sm on and off..*
2ce30 2a 0a 2a 2a 20 45 78 74 65 6e 73 69 6f 6e 20 6c *.** Extension l
2ce40 6f 61 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79 oading is off by
2ce50 20 64 65 66 61 75 6c 74 2e 20 53 65 65 20 74 69 default. See ti
2ce60 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 0a 2a cket #1863..**.*
2ce70 2a 20 7b 48 31 32 36 32 31 7d 20 43 61 6c 6c 20 * {H12621} Call
2ce80 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 the sqlite3_enab
2ce90 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f le_load_extensio
2cea0 6e 28 29 20 72 6f 75 74 69 6e 65 20 77 69 74 68 n() routine with
2ceb0 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 20 20 20 onoff==1.**
2cec0 20 20 20 20 20 20 74 6f 20 74 75 72 6e 20 65 78 to turn ex
2ced0 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 tension loading
2cee0 6f 6e 20 61 6e 64 20 63 61 6c 6c 20 69 74 20 77 on and call it w
2cef0 69 74 68 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 ith onoff==0 to
2cf00 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 turn.**
2cf10 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61 it back off aga
2cf20 69 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 32 in..**.** {H1262
2cf30 32 7d 20 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 2} Extension loa
2cf40 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79 20 64 ding is off by d
2cf50 65 66 61 75 6c 74 2e 0a 2a 2f 0a 69 6e 74 20 73 efault..*/.int s
2cf60 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f qlite3_enable_lo
2cf70 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c ad_extension(sql
2cf80 69 74 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e ite3 *db, int on
2cf90 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 off);../*.** CAP
2cfa0 49 33 52 45 46 3a 20 41 75 74 6f 6d 61 74 69 63 I3REF: Automatic
2cfb0 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78 74 ally Load An Ext
2cfc0 65 6e 73 69 6f 6e 73 20 7b 48 31 32 36 34 30 7d ensions {H12640}
2cfd0 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S20500>.**.**
2cfe0 54 68 69 73 20 41 50 49 20 63 61 6e 20 62 65 20 This API can be
2cff0 69 6e 76 6f 6b 65 64 20 61 74 20 70 72 6f 67 72 invoked at progr
2d000 61 6d 20 73 74 61 72 74 75 70 20 69 6e 20 6f 72 am startup in or
2d010 64 65 72 20 74 6f 20 72 65 67 69 73 74 65 72 0a der to register.
2d020 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 ** one or more s
2d030 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 tatically linked
2d040 20 65 78 74 65 6e 73 69 6f 6e 73 20 74 68 61 74 extensions that
2d050 20 77 69 6c 6c 20 62 65 20 61 76 61 69 6c 61 62 will be availab
2d060 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 le.** to all new
2d070 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
2d080 63 74 69 6f 6e 73 5d 2e 20 7b 45 4e 44 7d 0a 2a ctions]. {END}.*
2d090 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
2d0a0 65 20 73 74 6f 72 65 73 20 61 20 70 6f 69 6e 74 e stores a point
2d0b0 65 72 20 74 6f 20 74 68 65 20 65 78 74 65 6e 73 er to the extens
2d0c0 69 6f 6e 20 69 6e 20 61 6e 20 61 72 72 61 79 20 ion in an array
2d0d0 74 68 61 74 20 69 73 0a 2a 2a 20 6f 62 74 61 69 that is.** obtai
2d0e0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ned from [sqlite
2d0f0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 49 66 3_malloc()]. If
2d100 20 79 6f 75 20 72 75 6e 20 61 20 6d 65 6d 6f 72 you run a memor
2d110 79 20 6c 65 61 6b 20 63 68 65 63 6b 65 72 0a 2a y leak checker.*
2d120 2a 20 6f 6e 20 79 6f 75 72 20 70 72 6f 67 72 61 * on your progra
2d130 6d 20 61 6e 64 20 69 74 20 72 65 70 6f 72 74 73 m and it reports
2d140 20 61 20 6c 65 61 6b 20 62 65 63 61 75 73 65 20 a leak because
2d150 6f 66 20 74 68 69 73 20 61 72 72 61 79 2c 20 69 of this array, i
2d160 6e 76 6f 6b 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 nvoke.** [sqlite
2d170 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 3_reset_auto_ext
2d180 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20 ension()] prior
2d190 74 6f 20 73 68 75 74 64 6f 77 6e 20 74 6f 20 66 to shutdown to f
2d1a0 72 65 65 20 74 68 65 20 6d 65 6d 6f 72 79 2e 0a ree the memory..
2d1b0 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34 31 7d 20 54 **.** {H12641} T
2d1c0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 his function reg
2d1d0 69 73 74 65 72 73 20 61 6e 20 65 78 74 65 6e 73 isters an extens
2d1e0 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 ion entry point
2d1f0 74 68 61 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 that is.**
2d200 20 20 20 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c automaticall
2d210 79 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 y invoked whenev
2d220 65 72 20 61 20 6e 65 77 20 5b 64 61 74 61 62 61 er a new [databa
2d230 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a se connection].*
2d240 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6f 70 * is op
2d250 65 6e 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 ened using [sqli
2d260 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 te3_open()], [sq
2d270 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c lite3_open16()],
2d280 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 .** or
2d290 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
2d2a0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 ()]..**.** {H126
2d2b0 34 32 7d 20 44 75 70 6c 69 63 61 74 65 20 65 78 42} Duplicate ex
2d2c0 74 65 6e 73 69 6f 6e 73 20 61 72 65 20 64 65 74 tensions are det
2d2d0 65 63 74 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67 ected so calling
2d2e0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a this routine.**
2d2f0 20 20 20 20 20 20 20 20 20 20 6d 75 6c 74 69 70 multip
2d300 6c 65 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 le times with th
2d310 65 20 73 61 6d 65 20 65 78 74 65 6e 73 69 6f 6e e same extension
2d320 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a is harmless..**
2d330 0a 2a 2a 20 7b 48 31 32 36 34 33 7d 20 54 68 69 .** {H12643} Thi
2d340 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 s routine stores
2d350 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
2d360 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61 e extension in a
2d370 6e 20 61 72 72 61 79 0a 2a 2a 20 20 20 20 20 20 n array.**
2d380 20 20 20 20 74 68 61 74 20 69 73 20 6f 62 74 61 that is obta
2d390 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 ined from [sqlit
2d3a0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a e3_malloc()]..**
2d3b0 0a 2a 2a 20 7b 48 31 32 36 34 34 7d 20 41 75 74 .** {H12644} Aut
2d3c0 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e omatic extension
2d3d0 73 20 61 70 70 6c 79 20 61 63 72 6f 73 73 20 61 s apply across a
2d3e0 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 69 ll threads..*/.i
2d3f0 6e 74 20 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f nt sqlite3_auto_
2d400 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 20 28 extension(void (
2d410 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29 28 76 6f *xEntryPoint)(vo
2d420 69 64 29 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 id));../*.** CAP
2d430 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 75 74 I3REF: Reset Aut
2d440 6f 6d 61 74 69 63 20 45 78 74 65 6e 73 69 6f 6e omatic Extension
2d450 20 4c 6f 61 64 69 6e 67 20 7b 48 31 32 36 36 30 Loading {H12660
2d460 7d 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a } <S20500>.**.**
2d470 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 This function d
2d480 69 73 61 62 6c 65 73 20 61 6c 6c 20 70 72 65 76 isables all prev
2d490 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 iously registere
2d4a0 64 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 65 d automatic.** e
2d4b0 78 74 65 6e 73 69 6f 6e 73 2e 20 7b 45 4e 44 7d xtensions. {END}
2d4c0 20 20 49 74 20 75 6e 64 6f 65 73 20 74 68 65 20 It undoes the
2d4d0 65 66 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72 effect of all pr
2d4e0 69 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ior.** [sqlite3_
2d4f0 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 auto_extension()
2d500 5d 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b ] calls..**.** {
2d510 48 31 32 36 36 31 7d 20 54 68 69 73 20 66 75 6e H12661} This fun
2d520 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 ction disables a
2d530 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 ll previously re
2d540 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 20 20 20 gistered.**
2d550 20 20 20 20 20 61 75 74 6f 6d 61 74 69 63 20 65 automatic e
2d560 78 74 65 6e 73 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a xtensions..**.**
2d570 20 7b 48 31 32 36 36 32 7d 20 54 68 69 73 20 66 {H12662} This f
2d580 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 unction disables
2d590 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e automatic exten
2d5a0 73 69 6f 6e 73 20 69 6e 20 61 6c 6c 20 74 68 72 sions in all thr
2d5b0 65 61 64 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 eads..*/.void sq
2d5c0 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f lite3_reset_auto
2d5d0 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29 _extension(void)
2d5e0 3b 0a 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 ;../*.****** EXP
2d5f0 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a ERIMENTAL - subj
2d600 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 ect to change wi
2d610 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a thout notice ***
2d620 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a ***********.**.*
2d630 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 * The interface
2d640 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 to the virtual-t
2d650 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69 able mechanism i
2d660 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 s currently cons
2d670 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 idered.** to be
2d680 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 experimental. T
2d690 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 he interface mig
2d6a0 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 ht change in inc
2d6b0 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a ompatible ways..
2d6c0 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20 ** If this is a
2d6d0 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c problem for you,
2d6e0 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 do not use the
2d6f0 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69 interface at thi
2d700 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 s time..**.** Wh
2d710 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 en the virtual-t
2d720 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 able mechanism s
2d730 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 tabilizes, we wi
2d740 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a ll declare the.*
2d750 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 * interface fixe
2d760 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e d, support it in
2d770 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 definitely, and
2d780 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d remove this comm
2d790 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 ent..*/../*.** S
2d7a0 74 72 75 63 74 75 72 65 73 20 75 73 65 64 20 62 tructures used b
2d7b0 79 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 y the virtual ta
2d7c0 62 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f ble interface.*/
2d7d0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
2d7e0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c sqlite3_vtab sql
2d7f0 69 74 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 ite3_vtab;.typed
2d800 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
2d810 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 3_index_info sql
2d820 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b ite3_index_info;
2d830 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
2d840 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 sqlite3_vtab_cur
2d850 73 6f 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62 sor sqlite3_vtab
2d860 5f 63 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 _cursor;.typedef
2d870 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
2d880 6d 6f 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d module sqlite3_m
2d890 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 odule;../*.** CA
2d8a0 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 PI3REF: Virtual
2d8b0 54 61 62 6c 65 20 4f 62 6a 65 63 74 20 7b 48 31 Table Object {H1
2d8c0 38 30 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 8000} <S20400>.*
2d8d0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 * KEYWORDS: sqli
2d8e0 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 76 69 72 74 te3_module {virt
2d8f0 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 ual table module
2d900 7d 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 }.** EXPERIMENTA
2d910 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 74 72 L.**.** This str
2d920 75 63 74 75 72 65 2c 20 73 6f 6d 65 74 69 6d 65 ucture, sometime
2d930 73 20 63 61 6c 6c 65 64 20 61 20 61 20 22 76 69 s called a a "vi
2d940 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 rtual table modu
2d950 6c 65 22 2c 20 0a 2a 2a 20 64 65 66 69 6e 65 73 le", .** defines
2d960 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 the implementat
2d970 69 6f 6e 20 6f 66 20 61 20 5b 76 69 72 74 75 61 ion of a [virtua
2d980 6c 20 74 61 62 6c 65 73 5d 2e 20 20 0a 2a 2a 20 l tables]. .**
2d990 54 68 69 73 20 73 74 72 75 63 74 75 72 65 20 63 This structure c
2d9a0 6f 6e 73 69 73 74 73 20 6d 6f 73 74 6c 79 20 6f onsists mostly o
2d9b0 66 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 f methods for th
2d9c0 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 e module..**.**
2d9d0 41 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 A virtual table
2d9e0 6d 6f 64 75 6c 65 20 69 73 20 63 72 65 61 74 65 module is create
2d9f0 64 20 62 79 20 66 69 6c 6c 69 6e 67 20 69 6e 20 d by filling in
2da00 61 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 a persistent.**
2da10 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 instance of this
2da20 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 20 70 structure and p
2da30 61 73 73 69 6e 67 20 61 20 70 6f 69 6e 74 65 72 assing a pointer
2da40 20 74 6f 20 74 68 61 74 20 69 6e 73 74 61 6e 63 to that instanc
2da50 65 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 e.** to [sqlite3
2da60 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 _create_module()
2da70 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 ] or [sqlite3_cr
2da80 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 eate_module_v2()
2da90 5d 2e 0a 2a 2a 20 54 68 65 20 72 65 67 69 73 74 ]..** The regist
2daa0 72 61 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 76 ration remains v
2dab0 61 6c 69 64 20 75 6e 74 69 6c 20 69 74 20 69 73 alid until it is
2dac0 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 64 replaced by a d
2dad0 69 66 66 65 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75 ifferent.** modu
2dae0 6c 65 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 le or until the
2daf0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2db00 74 69 6f 6e 5d 20 63 6c 6f 73 65 73 2e 20 20 54 tion] closes. T
2db10 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66 he content.** of
2db20 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 this structure
2db30 6d 75 73 74 20 6e 6f 74 20 63 68 61 6e 67 65 20 must not change
2db40 77 68 69 6c 65 20 69 74 20 69 73 20 72 65 67 69 while it is regi
2db50 73 74 65 72 65 64 20 77 69 74 68 0a 2a 2a 20 61 stered with.** a
2db60 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ny database conn
2db70 65 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63 ection..*/.struc
2db80 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 t sqlite3_module
2db90 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f {. int iVersio
2dba0 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 61 n;. int (*xCrea
2dbb0 74 65 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f te)(sqlite3*, vo
2dbc0 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 id *pAux,.
2dbd0 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 int arg
2dbe0 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 c, const char *c
2dbf0 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 onst*argv,.
2dc00 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 sqlite
2dc10 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 3_vtab **ppVTab,
2dc20 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 char**);. int
2dc30 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69 (*xConnect)(sqli
2dc40 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 te3*, void *pAux
2dc50 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,.
2dc60 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 int argc, const
2dc70 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 char *const*arg
2dc80 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 v,.
2dc90 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a sqlite3_vtab *
2dca0 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 *ppVTab, char**)
2dcb0 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 73 74 49 ;. int (*xBestI
2dcc0 6e 64 65 78 29 28 73 71 6c 69 74 65 33 5f 76 74 ndex)(sqlite3_vt
2dcd0 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 ab *pVTab, sqlit
2dce0 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b e3_index_info*);
2dcf0 0a 20 20 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e . int (*xDiscon
2dd00 6e 65 63 74 29 28 73 71 6c 69 74 65 33 5f 76 74 nect)(sqlite3_vt
2dd10 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e ab *pVTab);. in
2dd20 74 20 28 2a 78 44 65 73 74 72 6f 79 29 28 73 71 t (*xDestroy)(sq
2dd30 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 lite3_vtab *pVTa
2dd40 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 b);. int (*xOpe
2dd50 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 n)(sqlite3_vtab
2dd60 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f *pVTab, sqlite3_
2dd70 76 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70 vtab_cursor **pp
2dd80 43 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28 Cursor);. int (
2dd90 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 *xClose)(sqlite3
2dda0 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a _vtab_cursor*);.
2ddb0 20 20 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 29 int (*xFilter)
2ddc0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 (sqlite3_vtab_cu
2ddd0 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75 rsor*, int idxNu
2dde0 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 69 m, const char *i
2ddf0 64 78 53 74 72 2c 0a 20 20 20 20 20 20 20 20 20 dxStr,.
2de00 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c int argc,
2de10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a sqlite3_value *
2de20 2a 61 72 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a *argv);. int (*
2de30 78 4e 65 78 74 29 28 73 71 6c 69 74 65 33 5f 76 xNext)(sqlite3_v
2de40 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 tab_cursor*);.
2de50 69 6e 74 20 28 2a 78 45 6f 66 29 28 73 71 6c 69 int (*xEof)(sqli
2de60 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a te3_vtab_cursor*
2de70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75 );. int (*xColu
2de80 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 mn)(sqlite3_vtab
2de90 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 _cursor*, sqlite
2dea0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3_context*, int)
2deb0 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 ;. int (*xRowid
2dec0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 )(sqlite3_vtab_c
2ded0 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f ursor*, sqlite3_
2dee0 69 6e 74 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a int64 *pRowid);.
2def0 20 20 69 6e 74 20 28 2a 78 55 70 64 61 74 65 29 int (*xUpdate)
2df00 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c (sqlite3_vtab *,
2df10 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76 61 int, sqlite3_va
2df20 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f lue **, sqlite3_
2df30 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20 int64 *);. int
2df40 28 2a 78 42 65 67 69 6e 29 28 73 71 6c 69 74 65 (*xBegin)(sqlite
2df50 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 3_vtab *pVTab);.
2df60 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 int (*xSync)(s
2df70 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 qlite3_vtab *pVT
2df80 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f ab);. int (*xCo
2df90 6d 6d 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74 mmit)(sqlite3_vt
2dfa0 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e ab *pVTab);. in
2dfb0 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73 t (*xRollback)(s
2dfc0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 qlite3_vtab *pVT
2dfd0 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 ab);. int (*xFi
2dfe0 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69 ndFunction)(sqli
2dff0 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c te3_vtab *pVtab,
2e000 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74 int nArg, const
2e010 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 char *zName,.
2e020 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2e030 20 20 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 void (**pxF
2e040 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e unc)(sqlite3_con
2e050 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 text*,int,sqlite
2e060 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 3_value**),.
2e070 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2e080 20 20 20 76 6f 69 64 20 2a 2a 70 70 41 72 67 29 void **ppArg)
2e090 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d ;. int (*xRenam
2e0a0 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 e)(sqlite3_vtab
2e0b0 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74 20 63 68 *pVtab, const ch
2e0c0 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f ar *zNew);.};../
2e0d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 *.** CAPI3REF: V
2e0e0 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 64 irtual Table Ind
2e0f0 65 78 69 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f exing Informatio
2e100 6e 20 7b 48 31 38 31 30 30 7d 20 3c 53 32 30 34 n {H18100} <S204
2e110 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 00>.** KEYWORDS:
2e120 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 sqlite3_index_i
2e130 6e 66 6f 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e nfo.** EXPERIMEN
2e140 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 TAL.**.** The sq
2e150 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f lite3_index_info
2e160 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 20 69 structure and i
2e170 74 73 20 73 75 62 73 74 72 75 63 74 75 72 65 73 ts substructures
2e180 20 69 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 70 is used to.** p
2e190 61 73 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 ass information
2e1a0 69 6e 74 6f 20 61 6e 64 20 72 65 63 65 69 76 65 into and receive
2e1b0 20 74 68 65 20 72 65 70 6c 79 20 66 72 6f 6d 20 the reply from
2e1c0 74 68 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d the [xBestIndex]
2e1d0 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61 20 .** method of a
2e1e0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d [virtual table m
2e1f0 6f 64 75 6c 65 5d 2e 20 20 54 68 65 20 66 69 65 odule]. The fie
2e200 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70 75 lds under **Inpu
2e210 74 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a 20 ts** are the.**
2e220 69 6e 70 75 74 73 20 74 6f 20 78 42 65 73 74 49 inputs to xBestI
2e230 6e 64 65 78 20 61 6e 64 20 61 72 65 20 72 65 61 ndex and are rea
2e240 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49 6e d-only. xBestIn
2e250 64 65 78 20 69 6e 73 65 72 74 73 20 69 74 73 0a dex inserts its.
2e260 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 ** results into
2e270 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 the **Outputs**
2e280 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 fields..**.** Th
2e290 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 e aConstraint[]
2e2a0 61 72 72 61 79 20 72 65 63 6f 72 64 73 20 57 48 array records WH
2e2b0 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 ERE clause const
2e2c0 72 61 69 6e 74 73 20 6f 66 20 74 68 65 20 66 6f raints of the fo
2e2d0 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 63 rm:.**.** <pre>c
2e2e0 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c 2f 70 olumn OP expr</p
2e2f0 72 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 re>.**.** where
2e300 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c 20 26 OP is =, <, &
2e310 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72 20 26 lt;=, >, or &
2e320 67 74 3b 3d 2e 20 20 54 68 65 20 70 61 72 74 69 gt;=. The parti
2e330 63 75 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69 cular operator i
2e340 73 0a 2a 2a 20 73 74 6f 72 65 64 20 69 6e 20 61 s.** stored in a
2e350 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e Constraint[].op.
2e360 20 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74 The index of t
2e370 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f he column is sto
2e380 72 65 64 20 69 6e 0a 2a 2a 20 61 43 6f 6e 73 74 red in.** aConst
2e390 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e raint[].iColumn.
2e3a0 20 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e aConstraint[].
2e3b0 75 73 61 62 6c 65 20 69 73 20 54 52 55 45 20 69 usable is TRUE i
2e3c0 66 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e f the.** expr on
2e3d0 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 the right-hand
2e3e0 73 69 64 65 20 63 61 6e 20 62 65 20 65 76 61 6c side can be eval
2e3f0 75 61 74 65 64 20 28 61 6e 64 20 74 68 75 73 20 uated (and thus
2e400 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a the constraint.*
2e410 2a 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e 64 * is usable) and
2e420 20 66 61 6c 73 65 20 69 66 20 69 74 20 63 61 6e false if it can
2e430 6e 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f not..**.** The o
2e440 70 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74 ptimizer automat
2e450 69 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 20 74 ically inverts t
2e460 65 72 6d 73 20 6f 66 20 74 68 65 20 66 6f 72 6d erms of the form
2e470 20 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e "expr OP column
2e480 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f ".** and makes o
2e490 74 68 65 72 20 73 69 6d 70 6c 69 66 69 63 61 74 ther simplificat
2e4a0 69 6f 6e 73 20 74 6f 20 74 68 65 20 57 48 45 52 ions to the WHER
2e4b0 45 20 63 6c 61 75 73 65 20 69 6e 20 61 6e 20 61 E clause in an a
2e4c0 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74 ttempt to.** get
2e4d0 20 61 73 20 6d 61 6e 79 20 57 48 45 52 45 20 63 as many WHERE c
2e4e0 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e 74 6f lause terms into
2e4f0 20 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20 the form shown
2e500 61 62 6f 76 65 20 61 73 20 70 6f 73 73 69 62 6c above as possibl
2e510 65 2e 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74 e..** The aConst
2e520 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e raint[] array on
2e530 6c 79 20 72 65 70 6f 72 74 73 20 57 48 45 52 45 ly reports WHERE
2e540 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e clause terms in
2e550 20 74 68 65 20 63 6f 72 72 65 63 74 0a 2a 2a 20 the correct.**
2e560 66 6f 72 6d 20 74 68 61 74 20 72 65 66 65 72 20 form that refer
2e570 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 to the particula
2e580 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 r virtual table
2e590 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a being queried..*
2e5a0 2a 0a 2a 2a 20 49 6e 66 6f 72 6d 61 74 69 6f 6e *.** Information
2e5b0 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52 about the ORDER
2e5c0 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 73 74 BY clause is st
2e5d0 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79 ored in aOrderBy
2e5e0 5b 5d 2e 0a 2a 2a 20 45 61 63 68 20 74 65 72 6d []..** Each term
2e5f0 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65 63 of aOrderBy rec
2e600 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 ords a column of
2e610 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c the ORDER BY cl
2e620 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ause..**.** The
2e630 5b 78 42 65 73 74 49 6e 64 65 78 5d 20 6d 65 74 [xBestIndex] met
2e640 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 hod must fill aC
2e650 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d onstraintUsage[]
2e660 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f with informatio
2e670 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 74 20 n.** about what
2e680 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 70 61 parameters to pa
2e690 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 ss to xFilter.
2e6a0 49 66 20 61 72 67 76 49 6e 64 65 78 3e 30 20 74 If argvIndex>0 t
2e6b0 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 hen.** the right
2e6c0 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68 -hand side of th
2e6d0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 e corresponding
2e6e0 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 aConstraint[] is
2e6f0 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e evaluated.** an
2e700 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 61 72 d becomes the ar
2e710 67 76 49 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 gvIndex-th entry
2e720 20 69 6e 20 61 72 67 76 2e 20 20 49 66 20 61 43 in argv. If aC
2e730 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d onstraintUsage[]
2e740 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 .omit.** is true
2e750 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 , then the const
2e760 72 61 69 6e 74 20 69 73 20 61 73 73 75 6d 65 64 raint is assumed
2e770 20 74 6f 20 62 65 20 66 75 6c 6c 79 20 68 61 6e to be fully han
2e780 64 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 dled by the.** v
2e790 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 irtual table and
2e7a0 20 69 73 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 is not checked
2e7b0 61 67 61 69 6e 20 62 79 20 53 51 4c 69 74 65 2e again by SQLite.
2e7c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 64 78 4e 75 .**.** The idxNu
2e7d0 6d 20 61 6e 64 20 69 64 78 50 74 72 20 76 61 6c m and idxPtr val
2e7e0 75 65 73 20 61 72 65 20 72 65 63 6f 72 64 65 64 ues are recorded
2e7f0 20 61 6e 64 20 70 61 73 73 65 64 20 69 6e 74 6f and passed into
2e800 20 74 68 65 0a 2a 2a 20 5b 78 46 69 6c 74 65 72 the.** [xFilter
2e810 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2a 20 5b 73 71 ] method..** [sq
2e820 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 lite3_free()] is
2e830 20 75 73 65 64 20 74 6f 20 66 72 65 65 20 69 64 used to free id
2e840 78 50 74 72 20 69 66 20 61 6e 64 20 6f 6e 6c 79 xPtr if and only
2e850 20 69 66 66 0a 2a 2a 20 6e 65 65 64 54 6f 46 72 iff.** needToFr
2e860 65 65 49 64 78 50 74 72 20 69 73 20 74 72 75 65 eeIdxPtr is true
2e870 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 72 64 65 ..**.** The orde
2e880 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d 65 61 6e rByConsumed mean
2e890 73 20 74 68 61 74 20 6f 75 74 70 75 74 20 66 72 s that output fr
2e8a0 6f 6d 20 5b 78 46 69 6c 74 65 72 5d 2f 5b 78 4e om [xFilter]/[xN
2e8b0 65 78 74 5d 20 77 69 6c 6c 20 6f 63 63 75 72 20 ext] will occur
2e8c0 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65 63 in.** the correc
2e8d0 74 20 6f 72 64 65 72 20 74 6f 20 73 61 74 69 73 t order to satis
2e8e0 66 79 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 fy the ORDER BY
2e8f0 63 6c 61 75 73 65 20 73 6f 20 74 68 61 74 20 6e clause so that n
2e900 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 73 6f o separate.** so
2e910 72 74 69 6e 67 20 73 74 65 70 20 69 73 20 72 65 rting step is re
2e920 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 quired..**.** Th
2e930 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 20 e estimatedCost
2e940 76 61 6c 75 65 20 69 73 20 61 6e 20 65 73 74 69 value is an esti
2e950 6d 61 74 65 20 6f 66 20 74 68 65 20 63 6f 73 74 mate of the cost
2e960 20 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a 2a of doing the.**
2e970 20 70 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f 6b particular look
2e980 75 70 2e 20 20 41 20 66 75 6c 6c 20 73 63 61 6e up. A full scan
2e990 20 6f 66 20 61 20 74 61 62 6c 65 20 77 69 74 68 of a table with
2e9a0 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c N entries shoul
2e9b0 64 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73 74 d have.** a cost
2e9c0 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61 72 79 of N. A binary
2e9d0 20 73 65 61 72 63 68 20 6f 66 20 61 20 74 61 62 search of a tab
2e9e0 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69 65 73 20 le of N entries
2e9f0 73 68 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a 2a should have a.**
2ea00 20 63 6f 73 74 20 6f 66 20 61 70 70 72 6f 78 69 cost of approxi
2ea10 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a mately log(N)..*
2ea20 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 /.struct sqlite3
2ea30 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a 20 20 _index_info {.
2ea40 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20 20 69 /* Inputs */. i
2ea50 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b 20 nt nConstraint;
2ea60 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d /* Num
2ea70 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20 69 ber of entries i
2ea80 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a 2f n aConstraint */
2ea90 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 . struct sqlite
2eaa0 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 3_index_constrai
2eab0 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 nt {. int iC
2eac0 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 olumn;
2ead0 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e /* Column on
2eae0 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 left-hand side
2eaf0 6f 66 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f of constraint */
2eb00 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 . unsigned c
2eb10 68 61 72 20 6f 70 3b 20 20 20 20 20 20 20 20 20 har op;
2eb20 2f 2a 20 43 6f 6e 73 74 72 61 69 6e 74 20 6f 70 /* Constraint op
2eb30 65 72 61 74 6f 72 20 2a 2f 0a 20 20 20 20 20 75 erator */. u
2eb40 6e 73 69 67 6e 65 64 20 63 68 61 72 20 75 73 61 nsigned char usa
2eb50 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54 72 75 65 ble; /* True
2eb60 20 69 66 20 74 68 69 73 20 63 6f 6e 73 74 72 61 if this constra
2eb70 69 6e 74 20 69 73 20 75 73 61 62 6c 65 20 2a 2f int is usable */
2eb80 0a 20 20 20 20 20 69 6e 74 20 69 54 65 72 6d 4f . int iTermO
2eb90 66 66 73 65 74 3b 20 20 20 20 20 20 20 20 20 20 ffset;
2eba0 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c /* Used internal
2ebb0 6c 79 20 2d 20 78 42 65 73 74 49 6e 64 65 78 20 ly - xBestIndex
2ebc0 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65 20 2a 2f should ignore */
2ebd0 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e . } *aConstrain
2ebe0 74 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a t; /*
2ebf0 20 54 61 62 6c 65 20 6f 66 20 57 48 45 52 45 20 Table of WHERE
2ec00 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e clause constrain
2ec10 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72 64 ts */. int nOrd
2ec20 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 20 20 erBy;
2ec30 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 /* Number of
2ec40 74 65 72 6d 73 20 69 6e 20 74 68 65 20 4f 52 44 terms in the ORD
2ec50 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a ER BY clause */.
2ec60 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 struct sqlite3
2ec70 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62 79 20 7b _index_orderby {
2ec80 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d . int iColum
2ec90 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 n;
2eca0 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 /* Column number
2ecb0 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 */. unsigne
2ecc0 64 20 63 68 61 72 20 64 65 73 63 3b 20 20 20 20 d char desc;
2ecd0 20 20 20 2f 2a 20 54 72 75 65 20 66 6f 72 20 44 /* True for D
2ece0 45 53 43 2e 20 20 46 61 6c 73 65 20 66 6f 72 20 ESC. False for
2ecf0 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72 ASC. */. } *aOr
2ed00 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 20 derBy;
2ed10 20 20 20 20 20 2f 2a 20 54 68 65 20 4f 52 44 45 /* The ORDE
2ed20 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 R BY clause */.
2ed30 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f 0a 20 /* Outputs */.
2ed40 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
2ed50 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 index_constraint
2ed60 5f 75 73 61 67 65 20 7b 0a 20 20 20 20 69 6e 74 _usage {. int
2ed70 20 61 72 67 76 49 6e 64 65 78 3b 20 20 20 20 20 argvIndex;
2ed80 20 20 20 20 20 20 2f 2a 20 69 66 20 3e 30 2c 20 /* if >0,
2ed90 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 70 61 constraint is pa
2eda0 72 74 20 6f 66 20 61 72 67 76 20 74 6f 20 78 46 rt of argv to xF
2edb0 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75 6e 73 ilter */. uns
2edc0 69 67 6e 65 64 20 63 68 61 72 20 6f 6d 69 74 3b igned char omit;
2edd0 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 /* Do not
2ede0 63 6f 64 65 20 61 20 74 65 73 74 20 66 6f 72 20 code a test for
2edf0 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 this constraint
2ee00 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 */. } *aConstra
2ee10 69 6e 74 55 73 61 67 65 3b 0a 20 20 69 6e 74 20 intUsage;. int
2ee20 69 64 78 4e 75 6d 3b 20 20 20 20 20 20 20 20 20 idxNum;
2ee30 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 /* Number
2ee40 20 75 73 65 64 20 74 6f 20 69 64 65 6e 74 69 66 used to identif
2ee50 79 20 74 68 65 20 69 6e 64 65 78 20 2a 2f 0a 20 y the index */.
2ee60 20 63 68 61 72 20 2a 69 64 78 53 74 72 3b 20 20 char *idxStr;
2ee70 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 /* S
2ee80 74 72 69 6e 67 2c 20 70 6f 73 73 69 62 6c 79 20 tring, possibly
2ee90 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 obtained from sq
2eea0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a lite3_malloc */.
2eeb0 20 20 69 6e 74 20 6e 65 65 64 54 6f 46 72 65 65 int needToFree
2eec0 49 64 78 53 74 72 3b 20 20 20 20 20 20 2f 2a 20 IdxStr; /*
2eed0 46 72 65 65 20 69 64 78 53 74 72 20 75 73 69 6e Free idxStr usin
2eee0 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 g sqlite3_free()
2eef0 20 69 66 20 74 72 75 65 20 2a 2f 0a 20 20 69 6e if true */. in
2ef00 74 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 t orderByConsume
2ef10 64 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65 d; /* True
2ef20 20 69 66 20 6f 75 74 70 75 74 20 69 73 20 61 6c if output is al
2ef30 72 65 61 64 79 20 6f 72 64 65 72 65 64 20 2a 2f ready ordered */
2ef40 0a 20 20 64 6f 75 62 6c 65 20 65 73 74 69 6d 61 . double estima
2ef50 74 65 64 43 6f 73 74 3b 20 20 20 20 20 20 2f 2a tedCost; /*
2ef60 20 45 73 74 69 6d 61 74 65 64 20 63 6f 73 74 20 Estimated cost
2ef70 6f 66 20 75 73 69 6e 67 20 74 68 69 73 20 69 6e of using this in
2ef80 64 65 78 20 2a 2f 0a 7d 3b 0a 23 64 65 66 69 6e dex */.};.#defin
2ef90 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 e SQLITE_INDEX_C
2efa0 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 20 20 20 ONSTRAINT_EQ
2efb0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
2efc0 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e _INDEX_CONSTRAIN
2efd0 54 5f 47 54 20 20 20 20 34 0a 23 64 65 66 69 6e T_GT 4.#defin
2efe0 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 e SQLITE_INDEX_C
2eff0 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20 20 20 20 ONSTRAINT_LE
2f000 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 8.#define SQLITE
2f010 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e _INDEX_CONSTRAIN
2f020 54 5f 4c 54 20 20 20 20 31 36 0a 23 64 65 66 69 T_LT 16.#defi
2f030 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f ne SQLITE_INDEX_
2f040 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45 20 20 20 CONSTRAINT_GE
2f050 20 33 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 32.#define SQLI
2f060 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 TE_INDEX_CONSTRA
2f070 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a 0a 2f 2a INT_MATCH 64../*
2f080 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
2f090 67 69 73 74 65 72 20 41 20 56 69 72 74 75 61 6c gister A Virtual
2f0a0 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 Table Implement
2f0b0 61 74 69 6f 6e 20 7b 48 31 38 32 30 30 7d 20 3c ation {H18200} <
2f0c0 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 S20400>.** EXPER
2f0d0 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 IMENTAL.**.** Th
2f0e0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 is routine is us
2f0f0 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 ed to register a
2f100 20 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61 new [virtual ta
2f110 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 6e 61 6d 65 ble module] name
2f120 2e 0a 2a 2a 20 4d 6f 64 75 6c 65 20 6e 61 6d 65 ..** Module name
2f130 73 20 6d 75 73 74 20 62 65 20 72 65 67 69 73 74 s must be regist
2f140 65 72 65 64 20 62 65 66 6f 72 65 0a 2a 2a 20 63 ered before.** c
2f150 72 65 61 74 69 6e 67 20 61 20 6e 65 77 20 5b 76 reating a new [v
2f160 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 75 73 irtual table] us
2f170 69 6e 67 20 74 68 65 20 6d 6f 64 75 6c 65 2c 20 ing the module,
2f180 6f 72 20 62 65 66 6f 72 65 20 75 73 69 6e 67 20 or before using
2f190 61 0a 2a 2a 20 70 72 65 65 78 69 73 74 69 6e 67 a.** preexisting
2f1a0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d [virtual table]
2f1b0 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e for the module.
2f1c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 6f 64 75 6c .**.** The modul
2f1d0 65 20 6e 61 6d 65 20 69 73 20 72 65 67 69 73 74 e name is regist
2f1e0 65 72 65 64 20 6f 6e 20 74 68 65 20 5b 64 61 74 ered on the [dat
2f1f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2f200 5d 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 ] specified.** b
2f210 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 y the first para
2f220 6d 65 74 65 72 2e 20 20 54 68 65 20 6e 61 6d 65 meter. The name
2f230 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 of the module i
2f240 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 0a s given by the .
2f250 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 ** second parame
2f260 74 65 72 2e 20 20 54 68 65 20 74 68 69 72 64 20 ter. The third
2f270 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 parameter is a p
2f280 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 ointer to.** the
2f290 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
2f2a0 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 of the [virtual
2f2b0 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 table module].
2f2c0 20 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20 70 The fourth.** p
2f2d0 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 arameter is an a
2f2e0 72 62 69 74 72 61 72 79 20 63 6c 69 65 6e 74 20 rbitrary client
2f2f0 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 data pointer tha
2f300 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f t is passed thro
2f310 75 67 68 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 ugh.** into the
2f320 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 20 5b 78 [xCreate] and [x
2f330 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73 Connect] methods
2f340 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 of the virtual
2f350 74 61 62 6c 65 20 6d 6f 64 75 6c 65 0a 2a 2a 20 table module.**
2f360 77 68 65 6e 20 61 20 6e 65 77 20 76 69 72 74 75 when a new virtu
2f370 61 6c 20 74 61 62 6c 65 20 69 73 20 62 65 20 62 al table is be b
2f380 65 69 6e 67 20 63 72 65 61 74 65 64 20 6f 72 20 eing created or
2f390 72 65 69 6e 69 74 69 61 6c 69 7a 65 64 2e 0a 2a reinitialized..*
2f3a0 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 *.** This interf
2f3b0 61 63 65 20 68 61 73 20 65 78 61 63 74 6c 79 20 ace has exactly
2f3c0 74 68 65 20 73 61 6d 65 20 65 66 66 65 63 74 20 the same effect
2f3d0 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 5b 73 as calling.** [s
2f3e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f qlite3_create_mo
2f3f0 64 75 6c 65 5f 76 32 28 29 5d 20 77 69 74 68 20 dule_v2()] with
2f400 61 20 4e 55 4c 4c 20 63 6c 69 65 6e 74 20 64 61 a NULL client da
2f410 74 61 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a ta destructor..*
2f420 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d /.SQLITE_EXPERIM
2f430 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 ENTAL int sqlite
2f440 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 3_create_module(
2f450 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
2f460 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
2f470 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 SQLite connecti
2f480 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d on to register m
2f490 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 odule with */.
2f4a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
2f4b0 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 e, /* Na
2f4c0 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 me of the module
2f4d0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 */. const sqli
2f4e0 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 te3_module *p,
2f4f0 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 /* Methods for
2f500 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 the module */.
2f510 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 void *pClientDat
2f520 61 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c a /* Cl
2f530 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 ient data for xC
2f540 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a reate/xConnect *
2f550 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.);../*.** CAPI
2f560 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 3REF: Register A
2f570 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 Virtual Table I
2f580 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 7b 48 mplementation {H
2f590 31 38 32 31 30 7d 20 3c 53 32 30 34 30 30 3e 0a 18210} <S20400>.
2f5a0 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a ** EXPERIMENTAL.
2f5b0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
2f5c0 6e 65 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 ne is identical
2f5d0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
2f5e0 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d create_module()]
2f5f0 20 6d 65 74 68 6f 64 2c 0a 2a 2a 20 65 78 63 65 method,.** exce
2f600 70 74 20 74 68 61 74 20 69 74 20 68 61 73 20 61 pt that it has a
2f610 6e 20 65 78 74 72 61 20 70 61 72 61 6d 65 74 65 n extra paramete
2f620 72 20 74 6f 20 73 70 65 63 69 66 79 20 0a 2a 2a r to specify .**
2f630 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 a destructor fu
2f640 6e 63 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 63 nction for the c
2f650 6c 69 65 6e 74 20 64 61 74 61 20 70 6f 69 6e 74 lient data point
2f660 65 72 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c er. SQLite will
2f670 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 .** invoke the d
2f680 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 estructor functi
2f690 6f 6e 20 28 69 66 20 69 74 20 69 73 20 6e 6f 74 on (if it is not
2f6a0 20 4e 55 4c 4c 29 20 77 68 65 6e 20 53 51 4c 69 NULL) when SQLi
2f6b0 74 65 0a 2a 2a 20 6e 6f 20 6c 6f 6e 67 65 72 20 te.** no longer
2f6c0 6e 65 65 64 73 20 74 68 65 20 70 43 6c 69 65 6e needs the pClien
2f6d0 74 44 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 20 tData pointer.
2f6e0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 .*/.SQLITE_EXPER
2f6f0 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 IMENTAL int sqli
2f700 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c te3_create_modul
2f710 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 e_v2(. sqlite3
2f720 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
2f730 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e /* SQLite con
2f740 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 nection to regis
2f750 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 ter module with
2f760 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
2f770 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 *zName,
2f780 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d /* Name of the m
2f790 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 odule */. const
2f7a0 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 sqlite3_module
2f7b0 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 *p, /* Methods
2f7c0 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 for the module
2f7d0 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69 65 */. void *pClie
2f7e0 6e 74 44 61 74 61 2c 20 20 20 20 20 20 20 20 20 ntData,
2f7f0 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 /* Client data f
2f800 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e or xCreate/xConn
2f810 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 ect */. void(*x
2f820 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 Destroy)(void*)
2f830 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 /* Module de
2f840 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f structor functio
2f850 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 n */.);../*.** C
2f860 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c API3REF: Virtual
2f870 20 54 61 62 6c 65 20 49 6e 73 74 61 6e 63 65 20 Table Instance
2f880 4f 62 6a 65 63 74 20 7b 48 31 38 30 31 30 7d 20 Object {H18010}
2f890 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 <S20400>.** KEYW
2f8a0 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 ORDS: sqlite3_vt
2f8b0 61 62 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 ab.** EXPERIMENT
2f8c0 41 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b AL.**.** Every [
2f8d0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f virtual table mo
2f8e0 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 dule] implementa
2f8f0 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 tion uses a subc
2f900 6c 61 73 73 0a 2a 2a 20 6f 66 20 74 68 65 20 66 lass.** of the f
2f910 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 ollowing structu
2f920 72 65 20 74 6f 20 64 65 73 63 72 69 62 65 20 61 re to describe a
2f930 20 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 particular inst
2f940 61 6e 63 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b ance.** of the [
2f950 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 20 virtual table].
2f960 20 45 61 63 68 20 73 75 62 63 6c 61 73 73 20 77 Each subclass w
2f970 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69 6c 6f 72 ill.** be tailor
2f980 65 64 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 ed to the specif
2f990 69 63 20 6e 65 65 64 73 20 6f 66 20 74 68 65 20 ic needs of the
2f9a0 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 module implement
2f9b0 61 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 70 75 ation..** The pu
2f9c0 72 70 6f 73 65 20 6f 66 20 74 68 69 73 20 73 75 rpose of this su
2f9d0 70 65 72 63 6c 61 73 73 20 69 73 20 74 6f 20 64 perclass is to d
2f9e0 65 66 69 6e 65 20 63 65 72 74 61 69 6e 20 66 69 efine certain fi
2f9f0 65 6c 64 73 20 74 68 61 74 20 61 72 65 0a 2a 2a elds that are.**
2fa00 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 6d common to all m
2fa10 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 odule implementa
2fa20 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 tions..**.** Vir
2fa30 74 75 61 6c 20 74 61 62 6c 65 73 20 6d 65 74 68 tual tables meth
2fa40 6f 64 73 20 63 61 6e 20 73 65 74 20 61 6e 20 65 ods can set an e
2fa50 72 72 6f 72 20 6d 65 73 73 61 67 65 20 62 79 20 rror message by
2fa60 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 assigning a.** s
2fa70 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 tring obtained f
2fa80 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 rom [sqlite3_mpr
2fa90 69 6e 74 66 28 29 5d 20 74 6f 20 7a 45 72 72 4d intf()] to zErrM
2faa0 73 67 2e 20 20 54 68 65 20 6d 65 74 68 6f 64 20 sg. The method
2fab0 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 should.** take c
2fac0 61 72 65 20 74 68 61 74 20 61 6e 79 20 70 72 69 are that any pri
2fad0 6f 72 20 73 74 72 69 6e 67 20 69 73 20 66 72 65 or string is fre
2fae0 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 ed by a call to
2faf0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
2fb00 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 73 73 .** prior to ass
2fb10 69 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 74 72 igning a new str
2fb20 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 ing to zErrMsg.
2fb30 20 41 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 After the error
2fb40 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 20 64 message.** is d
2fb50 65 6c 69 76 65 72 65 64 20 75 70 20 74 6f 20 74 elivered up to t
2fb60 68 65 20 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 he client applic
2fb70 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e ation, the strin
2fb80 67 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 g will be automa
2fb90 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 tically.** freed
2fba0 20 62 79 20 73 71 6c 69 74 65 33 5f 66 72 65 65 by sqlite3_free
2fbb0 28 29 20 61 6e 64 20 74 68 65 20 7a 45 72 72 4d () and the zErrM
2fbc0 73 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 62 65 sg field will be
2fbd0 20 7a 65 72 6f 65 64 2e 0a 2a 2f 0a 73 74 72 75 zeroed..*/.stru
2fbe0 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 ct sqlite3_vtab
2fbf0 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 {. const sqlite
2fc00 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 3_module *pModul
2fc10 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c e; /* The modul
2fc20 65 20 66 6f 72 20 74 68 69 73 20 76 69 72 74 75 e for this virtu
2fc30 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e al table */. in
2fc40 74 20 6e 52 65 66 3b 20 20 20 20 20 20 20 20 20 t nRef;
2fc50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
2fc60 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 Used internally
2fc70 20 2a 2f 0a 20 20 63 68 61 72 20 2a 7a 45 72 72 */. char *zErr
2fc80 4d 73 67 3b 20 20 20 20 20 20 20 20 20 20 20 20 Msg;
2fc90 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d /* Error m
2fca0 65 73 73 61 67 65 20 66 72 6f 6d 20 73 71 6c 69 essage from sqli
2fcb0 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 2a 2f te3_mprintf() */
2fcc0 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 . /* Virtual ta
2fcd0 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ble implementati
2fce0 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c ons will typical
2fcf0 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 ly add additiona
2fd00 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a l fields */.};..
2fd10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2fd20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 43 75 Virtual Table Cu
2fd30 72 73 6f 72 20 4f 62 6a 65 63 74 20 20 7b 48 31 rsor Object {H1
2fd40 38 30 32 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 8020} <S20400>.*
2fd50 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 * KEYWORDS: sqli
2fd60 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 te3_vtab_cursor
2fd70 7b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 63 {virtual table c
2fd80 75 72 73 6f 72 7d 0a 2a 2a 20 45 58 50 45 52 49 ursor}.** EXPERI
2fd90 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 MENTAL.**.** Eve
2fda0 72 79 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c ry [virtual tabl
2fdb0 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d e module] implem
2fdc0 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 entation uses a
2fdd0 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a subclass of the.
2fde0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 ** following str
2fdf0 75 63 74 75 72 65 20 74 6f 20 64 65 73 63 72 69 ucture to descri
2fe00 62 65 20 63 75 72 73 6f 72 73 20 74 68 61 74 20 be cursors that
2fe10 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65 0a 2a point into the.*
2fe20 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 * [virtual table
2fe30 5d 20 61 6e 64 20 61 72 65 20 75 73 65 64 0a 2a ] and are used.*
2fe40 2a 20 74 6f 20 6c 6f 6f 70 20 74 68 72 6f 75 67 * to loop throug
2fe50 68 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 h the virtual ta
2fe60 62 6c 65 2e 20 20 43 75 72 73 6f 72 73 20 61 72 ble. Cursors ar
2fe70 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 e created using
2fe80 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
2fe90 6d 6f 64 75 6c 65 2e 78 4f 70 65 6e 20 7c 20 78 module.xOpen | x
2fea0 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 Open] method of
2feb0 74 68 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20 61 the module and a
2fec0 72 65 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 re destroyed.**
2fed0 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f by the [sqlite3_
2fee0 6d 6f 64 75 6c 65 2e 78 43 6c 6f 73 65 20 7c 20 module.xClose |
2fef0 78 43 6c 6f 73 65 5d 20 6d 65 74 68 6f 64 2e 20 xClose] method.
2ff00 20 43 75 73 73 6f 72 73 20 61 72 65 20 75 73 65 Cussors are use
2ff10 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 78 46 69 d.** by the [xFi
2ff20 6c 74 65 72 5d 2c 20 5b 78 4e 65 78 74 5d 2c 20 lter], [xNext],
2ff30 5b 78 45 6f 66 5d 2c 20 5b 78 43 6f 6c 75 6d 6e [xEof], [xColumn
2ff40 5d 2c 20 61 6e 64 20 5b 78 52 6f 77 69 64 5d 20 ], and [xRowid]
2ff50 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 74 68 methods.** of th
2ff60 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 e module. Each
2ff70 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 module implement
2ff80 61 74 69 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e ation will defin
2ff90 65 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 e.** the content
2ffa0 20 6f 66 20 61 20 63 75 72 73 6f 72 20 73 74 72 of a cursor str
2ffb0 75 63 74 75 72 65 20 74 6f 20 73 75 69 74 20 69 ucture to suit i
2ffc0 74 73 20 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a ts own needs..**
2ffd0 0a 2a 2a 20 54 68 69 73 20 73 75 70 65 72 63 6c .** This supercl
2ffe0 61 73 73 20 65 78 69 73 74 73 20 69 6e 20 6f 72 ass exists in or
2fff0 64 65 72 20 74 6f 20 64 65 66 69 6e 65 20 66 69 der to define fi
30000 65 6c 64 73 20 6f 66 20 74 68 65 20 63 75 72 73 elds of the curs
30010 6f 72 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 or that.** are c
30020 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 ommon to all imp
30030 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f lementations..*/
30040 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
30050 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 vtab_cursor {.
30060 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 sqlite3_vtab *pV
30070 74 61 62 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 tab; /* Vir
30080 74 75 61 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 tual table of th
30090 69 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f is cursor */. /
300a0 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 * Virtual table
300b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
300c0 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 will typically a
300d0 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 dd additional fi
300e0 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a elds */.};../*.*
300f0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c * CAPI3REF: Decl
30100 61 72 65 20 54 68 65 20 53 63 68 65 6d 61 20 4f are The Schema O
30110 66 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c f A Virtual Tabl
30120 65 20 7b 48 31 38 32 38 30 7d 20 3c 53 32 30 34 e {H18280} <S204
30130 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 00>.** EXPERIMEN
30140 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 78 TAL.**.** The [x
30150 43 72 65 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f Create] and [xCo
30160 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f nnect] methods o
30170 66 20 61 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 f a.** [virtual
30180 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 63 61 table module] ca
30190 6c 6c 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 ll this interfac
301a0 65 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72 65 20 e.** to declare
301b0 74 68 65 20 66 6f 72 6d 61 74 20 28 74 68 65 20 the format (the
301c0 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 61 74 79 names and dataty
301d0 70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d pes of the colum
301e0 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20 76 69 ns) of.** the vi
301f0 72 74 75 61 6c 20 74 61 62 6c 65 73 20 74 68 65 rtual tables the
30200 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a y implement..*/.
30210 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e SQLITE_EXPERIMEN
30220 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f TAL int sqlite3_
30230 64 65 63 6c 61 72 65 5f 76 74 61 62 28 73 71 6c declare_vtab(sql
30240 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 ite3*, const cha
30250 72 20 2a 7a 53 51 4c 29 3b 0a 0a 2f 2a 0a 2a 2a r *zSQL);../*.**
30260 20 43 41 50 49 33 52 45 46 3a 20 4f 76 65 72 6c CAPI3REF: Overl
30270 6f 61 64 20 41 20 46 75 6e 63 74 69 6f 6e 20 46 oad A Function F
30280 6f 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 or A Virtual Tab
30290 6c 65 20 7b 48 31 38 33 30 30 7d 20 3c 53 32 30 le {H18300} <S20
302a0 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 400>.** EXPERIME
302b0 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 NTAL.**.** Virtu
302c0 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 20 70 72 al tables can pr
302d0 6f 76 69 64 65 20 61 6c 74 65 72 6e 61 74 69 76 ovide alternativ
302e0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
302f0 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a s of functions.*
30300 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 78 46 69 * using the [xFi
30310 6e 64 46 75 6e 63 74 69 6f 6e 5d 20 6d 65 74 68 ndFunction] meth
30320 6f 64 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 od of the [virtu
30330 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d al table module]
30340 2e 20 20 0a 2a 2a 20 42 75 74 20 67 6c 6f 62 61 . .** But globa
30350 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 l versions of th
30360 6f 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a ose functions.**
30370 20 6d 75 73 74 20 65 78 69 73 74 20 69 6e 20 6f must exist in o
30380 72 64 65 72 20 74 6f 20 62 65 20 6f 76 65 72 6c rder to be overl
30390 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 oaded..**.** Thi
303a0 73 20 41 50 49 20 6d 61 6b 65 73 20 73 75 72 65 s API makes sure
303b0 20 61 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f a global versio
303c0 6e 20 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e 20 n of a function
303d0 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 with a particula
303e0 72 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75 r.** name and nu
303f0 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 mber of paramete
30400 72 73 20 65 78 69 73 74 73 2e 20 20 49 66 20 6e rs exists. If n
30410 6f 20 73 75 63 68 20 66 75 6e 63 74 69 6f 6e 20 o such function
30420 65 78 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65 exists.** before
30430 20 74 68 69 73 20 41 50 49 20 69 73 20 63 61 6c this API is cal
30440 6c 65 64 2c 20 61 20 6e 65 77 20 66 75 6e 63 74 led, a new funct
30450 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64 2e 20 ion is created.
30460 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 The implementat
30470 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 65 ion.** of the ne
30480 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61 79 w function alway
30490 73 20 63 61 75 73 65 73 20 61 6e 20 65 78 63 65 s causes an exce
304a0 70 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 72 6f ption to be thro
304b0 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20 6e wn. So.** the n
304c0 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e ew function is n
304d0 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79 74 ot good for anyt
304e0 68 69 6e 67 20 62 79 20 69 74 73 65 6c 66 2e 20 hing by itself.
304f0 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72 Its only.** pur
30500 70 6f 73 65 20 69 73 20 74 6f 20 62 65 20 61 20 pose is to be a
30510 70 6c 61 63 65 68 6f 6c 64 65 72 20 66 75 6e 63 placeholder func
30520 74 69 6f 6e 20 74 68 61 74 20 63 61 6e 20 62 65 tion that can be
30530 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 overloaded.** b
30540 79 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 y a [virtual tab
30550 6c 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 le]..*/.SQLITE_E
30560 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 XPERIMENTAL int
30570 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61 64 sqlite3_overload
30580 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74 65 _function(sqlite
30590 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 3*, const char *
305a0 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 6e zFuncName, int n
305b0 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 Arg);../*.** The
305c0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 interface to th
305d0 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 e virtual-table
305e0 6d 65 63 68 61 6e 69 73 6d 20 64 65 66 69 6e 65 mechanism define
305f0 64 20 61 62 6f 76 65 20 28 62 61 63 6b 20 75 70 d above (back up
30600 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e 74 .** to a comment
30610 20 72 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d 69 remarkably simi
30620 6c 61 72 20 74 6f 20 74 68 69 73 20 6f 6e 65 29 lar to this one)
30630 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f is currently co
30640 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 nsidered.** to b
30650 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 e experimental.
30660 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d The interface m
30670 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 ight change in i
30680 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 ncompatible ways
30690 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 ..** If this is
306a0 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f a problem for yo
306b0 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 u, do not use th
306c0 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 e interface at t
306d0 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 his time..**.**
306e0 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c When the virtual
306f0 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d -table mechanism
30700 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 stabilizes, we
30710 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 will declare the
30720 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 .** interface fi
30730 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 xed, support it
30740 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e indefinitely, an
30750 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f d remove this co
30760 6d 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a mment..**.******
30770 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 EXPERIMENTAL -
30780 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 subject to chang
30790 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 e without notice
307a0 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a **************.
307b0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
307c0 45 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 EF: A Handle To
307d0 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 20 7b 48 31 An Open BLOB {H1
307e0 37 38 30 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 7800} <S30230>.*
307f0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 42 4c 4f * KEYWORDS: {BLO
30800 42 20 68 61 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 B handle} {BLOB
30810 68 61 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 handles}.**.** A
30820 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
30830 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 is object repres
30840 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 42 4c 4f ents an open BLO
30850 42 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 5b 73 B on which.** [s
30860 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e qlite3_blob_open
30870 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 | incremental B
30880 4c 4f 42 20 49 2f 4f 5d 20 63 61 6e 20 62 65 20 LOB I/O] can be
30890 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 20 4f 62 performed..** Ob
308a0 6a 65 63 74 73 20 6f 66 20 74 68 69 73 20 74 79 jects of this ty
308b0 70 65 20 61 72 65 20 63 72 65 61 74 65 64 20 62 pe are created b
308c0 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f y [sqlite3_blob_
308d0 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64 open()].** and d
308e0 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c estroyed by [sql
308f0 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 ite3_blob_close(
30900 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 )]..** The [sqli
30910 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d te3_blob_read()]
30920 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c and [sqlite3_bl
30930 6f 62 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65 ob_write()] inte
30940 72 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 rfaces.** can be
30950 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72 used to read or
30960 20 77 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 write small sub
30970 73 65 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 sections of the
30980 42 4c 4f 42 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 BLOB..** The [sq
30990 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 lite3_blob_bytes
309a0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 ()] interface re
309b0 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f turns the size o
309c0 66 20 74 68 65 20 42 4c 4f 42 20 69 6e 20 62 79 f the BLOB in by
309d0 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 tes..*/.typedef
309e0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62 struct sqlite3_b
309f0 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 lob sqlite3_blob
30a00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
30a10 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 F: Open A BLOB F
30a20 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 or Incremental I
30a30 2f 4f 20 7b 48 31 37 38 31 30 7d 20 3c 53 33 30 /O {H17810} <S30
30a40 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 230>.**.** This
30a50 69 6e 74 65 72 66 61 63 65 73 20 6f 70 65 6e 73 interfaces opens
30a60 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 20 a [BLOB handle
30a70 7c 20 68 61 6e 64 6c 65 5d 20 74 6f 20 74 68 65 | handle] to the
30a80 20 42 4c 4f 42 20 6c 6f 63 61 74 65 64 0a 2a 2a BLOB located.**
30a90 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f in row iRow, co
30aa0 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 lumn zColumn, ta
30ab0 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61 ble zTable in da
30ac0 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 tabase zDb;.** i
30ad0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 n other words, t
30ae0 68 65 20 73 61 6d 65 20 42 4c 4f 42 20 74 68 61 he same BLOB tha
30af0 74 20 77 6f 75 6c 64 20 62 65 20 73 65 6c 65 63 t would be selec
30b00 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 ted by:.**.** <p
30b10 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43 re>.** SELEC
30b20 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a T zColumn FROM z
30b30 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 45 20 Db.zTable WHERE
30b40 5b 72 6f 77 69 64 5d 20 3d 20 69 52 6f 77 3b 0a [rowid] = iRow;.
30b50 2a 2a 20 3c 2f 70 72 65 3e 20 7b 45 4e 44 7d 0a ** </pre> {END}.
30b60 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 6c 61 **.** If the fla
30b70 67 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 gs parameter is
30b80 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 74 68 non-zero, the th
30b90 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 e BLOB is opened
30ba0 20 66 6f 72 20 72 65 61 64 0a 2a 2a 20 61 6e 64 for read.** and
30bb0 20 77 72 69 74 65 20 61 63 63 65 73 73 2e 20 49 write access. I
30bc0 66 20 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68 f it is zero, th
30bd0 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 e BLOB is opened
30be0 20 66 6f 72 20 72 65 61 64 20 61 63 63 65 73 73 for read access
30bf0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ..**.** Note tha
30c00 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e t the database n
30c10 61 6d 65 20 69 73 20 6e 6f 74 20 74 68 65 20 66 ame is not the f
30c20 69 6c 65 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e ilename that con
30c30 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74 tains.** the dat
30c40 61 62 61 73 65 20 62 75 74 20 72 61 74 68 65 72 abase but rather
30c50 20 74 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 the symbolic na
30c60 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 me of the databa
30c70 73 65 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 73 se that.** is as
30c80 73 69 67 6e 65 64 20 77 68 65 6e 20 74 68 65 20 signed when the
30c90 64 61 74 61 62 61 73 65 20 69 73 20 63 6f 6e 6e database is conn
30ca0 65 63 74 65 64 20 75 73 69 6e 67 20 5b 41 54 54 ected using [ATT
30cb0 41 43 48 5d 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 ACH]..** For the
30cc0 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 main database f
30cd0 69 6c 65 2c 20 74 68 65 20 64 61 74 61 62 61 73 ile, the databas
30ce0 65 20 6e 61 6d 65 20 69 73 20 22 6d 61 69 6e 22 e name is "main"
30cf0 2e 0a 2a 2a 20 46 6f 72 20 54 45 4d 50 20 74 61 ..** For TEMP ta
30d00 62 6c 65 73 2c 20 74 68 65 20 64 61 74 61 62 61 bles, the databa
30d10 73 65 20 6e 61 6d 65 20 69 73 20 22 74 65 6d 70 se name is "temp
30d20 22 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 "..**.** On succ
30d30 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d ess, [SQLITE_OK]
30d40 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 is returned and
30d50 20 74 68 65 20 6e 65 77 20 5b 42 4c 4f 42 20 68 the new [BLOB h
30d60 61 6e 64 6c 65 5d 20 69 73 20 77 72 69 74 74 65 andle] is writte
30d70 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c 6f 62 2e n.** to *ppBlob.
30d80 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 Otherwise an [e
30d90 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 rror code] is re
30da0 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 79 20 76 turned and any v
30db0 61 6c 75 65 20 77 72 69 74 74 65 6e 0a 2a 2a 20 alue written.**
30dc0 74 6f 20 2a 70 70 42 6c 6f 62 20 73 68 6f 75 6c to *ppBlob shoul
30dd0 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 d not be used by
30de0 20 74 68 65 20 63 61 6c 6c 65 72 2e 0a 2a 2a 20 the caller..**
30df0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 This function se
30e00 74 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 ts the [database
30e10 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 72 connection] err
30e20 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 or code and mess
30e30 61 67 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c age.** accessibl
30e40 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 e via [sqlite3_e
30e50 72 72 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 rrcode()] and [s
30e60 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d qlite3_errmsg()]
30e70 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 ..**.** If the r
30e80 6f 77 20 74 68 61 74 20 61 20 42 4c 4f 42 20 68 ow that a BLOB h
30e90 61 6e 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 andle points to
30ea0 69 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 61 is modified by a
30eb0 6e 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20 5b n.** [UPDATE], [
30ec0 44 45 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20 5b DELETE], or by [
30ed0 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69 64 ON CONFLICT] sid
30ee0 65 2d 65 66 66 65 63 74 73 0a 2a 2a 20 74 68 65 e-effects.** the
30ef0 6e 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c n the BLOB handl
30f00 65 20 69 73 20 6d 61 72 6b 65 64 20 61 73 20 22 e is marked as "
30f10 65 78 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68 69 expired"..** Thi
30f20 73 20 69 73 20 74 72 75 65 20 69 66 20 61 6e 79 s is true if any
30f30 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 column of the r
30f40 6f 77 20 69 73 20 63 68 61 6e 67 65 64 2c 20 65 ow is changed, e
30f50 76 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 ven a column.**
30f60 6f 74 68 65 72 20 74 68 61 6e 20 74 68 65 20 6f other than the o
30f70 6e 65 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 ne the BLOB hand
30f80 6c 65 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 0a 2a le is open on..*
30f90 2a 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 * Calls to [sqli
30fa0 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d te3_blob_read()]
30fb0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c and [sqlite3_bl
30fc0 6f 62 5f 77 72 69 74 65 28 29 5d 20 66 6f 72 0a ob_write()] for.
30fd0 2a 2a 20 61 20 65 78 70 69 72 65 64 20 42 4c 4f ** a expired BLO
30fe0 42 20 68 61 6e 64 6c 65 20 66 61 69 6c 20 77 69 B handle fail wi
30ff0 74 68 20 61 6e 20 72 65 74 75 72 6e 20 63 6f 64 th an return cod
31000 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f e of [SQLITE_ABO
31010 52 54 5d 2e 0a 2a 2a 20 43 68 61 6e 67 65 73 20 RT]..** Changes
31020 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 61 20 42 written into a B
31030 4c 4f 42 20 70 72 69 6f 72 20 74 6f 20 74 68 65 LOB prior to the
31040 20 42 4c 4f 42 20 65 78 70 69 72 69 6e 67 20 61 BLOB expiring a
31050 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c 62 61 re not.** rollba
31060 63 6b 20 62 79 20 74 68 65 20 65 78 70 69 72 61 ck by the expira
31070 74 69 6f 6e 20 6f 66 20 74 68 65 20 42 4c 4f 42 tion of the BLOB
31080 2e 20 20 53 75 63 68 20 63 68 61 6e 67 65 73 20 . Such changes
31090 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 0a will eventually.
310a0 2a 2a 20 63 6f 6d 6d 69 74 20 69 66 20 74 68 65 ** commit if the
310b0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e transaction con
310c0 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 tinues to comple
310d0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 tion..**.** Requ
310e0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
310f0 37 38 31 33 5d 20 5b 48 31 37 38 31 34 5d 20 5b 7813] [H17814] [
31100 48 31 37 38 31 36 5d 20 5b 48 31 37 38 31 39 5d H17816] [H17819]
31110 20 5b 48 31 37 38 32 31 5d 20 5b 48 31 37 38 32 [H17821] [H1782
31120 34 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 4].*/.int sqlite
31130 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 3_blob_open(. s
31140 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 qlite3*,. const
31150 20 63 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f char *zDb,. co
31160 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 nst char *zTable
31170 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a ,. const char *
31180 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 zColumn,. sqlit
31190 65 33 5f 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20 e3_int64 iRow,.
311a0 20 69 6e 74 20 66 6c 61 67 73 2c 0a 20 20 73 71 int flags,. sq
311b0 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 lite3_blob **ppB
311c0 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 lob.);../*.** CA
311d0 50 49 33 52 45 46 3a 20 43 6c 6f 73 65 20 41 20 PI3REF: Close A
311e0 42 4c 4f 42 20 48 61 6e 64 6c 65 20 7b 48 31 37 BLOB Handle {H17
311f0 38 33 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 830} <S30230>.**
31200 0a 2a 2a 20 43 6c 6f 73 65 73 20 61 6e 20 6f 70 .** Closes an op
31210 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d en [BLOB handle]
31220 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 69 6e 67 20 ..**.** Closing
31230 61 20 42 4c 4f 42 20 73 68 61 6c 6c 20 63 61 75 a BLOB shall cau
31240 73 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 se the current t
31250 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 63 6f ransaction to co
31260 6d 6d 69 74 0a 2a 2a 20 69 66 20 74 68 65 72 65 mmit.** if there
31270 20 61 72 65 20 6e 6f 20 6f 74 68 65 72 20 42 4c are no other BL
31280 4f 42 73 2c 20 6e 6f 20 70 65 6e 64 69 6e 67 20 OBs, no pending
31290 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
312a0 6e 74 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 nts, and the.**
312b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
312c0 69 6f 6e 20 69 73 20 69 6e 20 5b 61 75 74 6f 63 ion is in [autoc
312d0 6f 6d 6d 69 74 20 6d 6f 64 65 5d 2e 0a 2a 2a 20 ommit mode]..**
312e0 49 66 20 61 6e 79 20 77 72 69 74 65 73 20 77 65 If any writes we
312f0 72 65 20 6d 61 64 65 20 74 6f 20 74 68 65 20 42 re made to the B
31300 4c 4f 42 2c 20 74 68 65 79 20 6d 69 67 68 74 20 LOB, they might
31310 62 65 20 68 65 6c 64 20 69 6e 20 63 61 63 68 65 be held in cache
31320 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20 63 6c .** until the cl
31330 6f 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 66 ose operation if
31340 20 74 68 65 79 20 77 69 6c 6c 20 66 69 74 2e 20 they will fit.
31350 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 {END}.**.** Clos
31360 69 6e 67 20 74 68 65 20 42 4c 4f 42 20 6f 66 74 ing the BLOB oft
31370 65 6e 20 66 6f 72 63 65 73 20 74 68 65 20 63 68 en forces the ch
31380 61 6e 67 65 73 0a 2a 2a 20 6f 75 74 20 74 6f 20 anges.** out to
31390 64 69 73 6b 20 61 6e 64 20 73 6f 20 69 66 20 61 disk and so if a
313a0 6e 79 20 49 2f 4f 20 65 72 72 6f 72 73 20 6f 63 ny I/O errors oc
313b0 63 75 72 2c 20 74 68 65 79 20 77 69 6c 6c 20 6c cur, they will l
313c0 69 6b 65 6c 79 20 6f 63 63 75 72 0a 2a 2a 20 61 ikely occur.** a
313d0 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 20 t the time when
313e0 74 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 the BLOB is clos
313f0 65 64 2e 20 20 7b 48 31 37 38 33 33 7d 20 41 6e ed. {H17833} An
31400 79 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 y errors that oc
31410 63 75 72 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c cur during.** cl
31420 6f 73 69 6e 67 20 61 72 65 20 72 65 70 6f 72 74 osing are report
31430 65 64 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f ed as a non-zero
31440 20 72 65 74 75 72 6e 20 76 61 6c 75 65 2e 0a 2a return value..*
31450 2a 0a 2a 2a 20 54 68 65 20 42 4c 4f 42 20 69 73 *.** The BLOB is
31460 20 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69 74 closed uncondit
31470 69 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20 69 ionally. Even i
31480 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 f this routine r
31490 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72 72 eturns.** an err
314a0 6f 72 20 63 6f 64 65 2c 20 74 68 65 20 42 4c 4f or code, the BLO
314b0 42 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73 65 B is still close
314c0 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 d..**.** Require
314d0 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 33 ments:.** [H1783
314e0 33 5d 20 5b 48 31 37 38 33 36 5d 20 5b 48 31 37 3] [H17836] [H17
314f0 38 33 39 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 839].*/.int sqli
31500 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 te3_blob_close(s
31510 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a qlite3_blob *);.
31520 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
31530 20 52 65 74 75 72 6e 20 54 68 65 20 53 69 7a 65 Return The Size
31540 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 Of An Open BLOB
31550 20 7b 48 31 37 38 34 30 7d 20 3c 53 33 30 32 33 {H17840} <S3023
31560 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 0>.**.** Returns
31570 20 74 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 the size in byt
31580 65 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 61 es of the BLOB a
31590 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 74 68 ccessible via th
315a0 65 20 6f 70 65 6e 0a 2a 2a 20 5b 5d 42 4c 4f 42 e open.** []BLOB
315b0 20 68 61 6e 64 6c 65 5d 20 69 6e 20 69 74 73 20 handle] in its
315c0 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 0a 2a only argument..*
315d0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
315e0 73 3a 0a 2a 2a 20 5b 48 31 37 38 34 33 5d 0a 2a s:.** [H17843].*
315f0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c /.int sqlite3_bl
31600 6f 62 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 ob_bytes(sqlite3
31610 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a _blob *);../*.**
31620 20 43 41 50 49 33 52 45 46 3a 20 52 65 61 64 20 CAPI3REF: Read
31630 44 61 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42 Data From A BLOB
31640 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b Incrementally {
31650 48 31 37 38 35 30 7d 20 3c 53 33 30 32 33 30 3e H17850} <S30230>
31660 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 .**.** This func
31670 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 tion is used to
31680 72 65 61 64 20 64 61 74 61 20 66 72 6f 6d 20 61 read data from a
31690 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e n open [BLOB han
316a0 64 6c 65 5d 20 69 6e 74 6f 20 61 0a 2a 2a 20 63 dle] into a.** c
316b0 61 6c 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62 aller-supplied b
316c0 75 66 66 65 72 2e 20 4e 20 62 79 74 65 73 20 6f uffer. N bytes o
316d0 66 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 f data are copie
316e0 64 20 69 6e 74 6f 20 62 75 66 66 65 72 20 5a 0a d into buffer Z.
316f0 2a 2a 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 6e ** from the open
31700 20 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 BLOB, starting
31710 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 at offset iOffse
31720 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 6f 66 66 73 t..**.** If offs
31730 65 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 et iOffset is le
31740 73 73 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20 ss than N bytes
31750 66 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 from the end of
31760 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 the BLOB,.** [SQ
31770 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 LITE_ERROR] is r
31780 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 eturned and no d
31790 61 74 61 20 69 73 20 72 65 61 64 2e 20 20 49 66 ata is read. If
317a0 20 4e 20 6f 72 20 69 4f 66 66 73 65 74 20 69 73 N or iOffset is
317b0 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 .** less than ze
317c0 72 6f 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f ro, [SQLITE_ERRO
317d0 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 R] is returned a
317e0 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65 nd no data is re
317f0 61 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 74 74 ad..**.** An att
31800 65 6d 70 74 20 74 6f 20 72 65 61 64 20 66 72 6f empt to read fro
31810 6d 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c m an expired [BL
31820 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 OB handle] fails
31830 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f with an.** erro
31840 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 r code of [SQLIT
31850 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 E_ABORT]..**.**
31860 4f 6e 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49 On success, SQLI
31870 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 TE_OK is returne
31880 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c d..** Otherwise,
31890 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d an [error code]
318a0 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 or an [extended
318b0 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 error code] is
318c0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
318d0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
318e0 20 5b 48 31 37 38 35 33 5d 20 5b 48 31 37 38 35 [H17853] [H1785
318f0 36 5d 20 5b 48 31 37 38 35 39 5d 20 5b 48 31 37 6] [H17859] [H17
31900 38 36 32 5d 20 5b 48 31 37 38 36 33 5d 20 5b 48 862] [H17863] [H
31910 31 37 38 36 35 5d 20 5b 48 31 37 38 36 38 5d 0a 17865] [H17868].
31920 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 */.int sqlite3_b
31930 6c 6f 62 5f 72 65 61 64 28 73 71 6c 69 74 65 33 lob_read(sqlite3
31940 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 2a 5a _blob *, void *Z
31950 2c 20 69 6e 74 20 4e 2c 20 69 6e 74 20 69 4f 66 , int N, int iOf
31960 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 fset);../*.** CA
31970 50 49 33 52 45 46 3a 20 57 72 69 74 65 20 44 61 PI3REF: Write Da
31980 74 61 20 49 6e 74 6f 20 41 20 42 4c 4f 42 20 49 ta Into A BLOB I
31990 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 48 31 ncrementally {H1
319a0 37 38 37 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 7870} <S30230>.*
319b0 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 *.** This functi
319c0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 77 72 on is used to wr
319d0 69 74 65 20 64 61 74 61 20 69 6e 74 6f 20 61 6e ite data into an
319e0 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 open [BLOB hand
319f0 6c 65 5d 20 66 72 6f 6d 20 61 0a 2a 2a 20 63 61 le] from a.** ca
31a00 6c 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 ller-supplied bu
31a10 66 66 65 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 ffer. N bytes of
31a20 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 data are copied
31a30 20 66 72 6f 6d 20 74 68 65 20 62 75 66 66 65 72 from the buffer
31a40 20 5a 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 6f Z.** into the o
31a50 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74 69 pen BLOB, starti
31a60 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 ng at offset iOf
31a70 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 fset..**.** If t
31a80 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d he [BLOB handle]
31a90 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 passed as the f
31aa0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 77 61 irst argument wa
31ab0 73 20 6e 6f 74 20 6f 70 65 6e 65 64 20 66 6f 72 s not opened for
31ac0 0a 2a 2a 20 77 72 69 74 69 6e 67 20 28 74 68 65 .** writing (the
31ad0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 flags parameter
31ae0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f to [sqlite3_blo
31af0 62 5f 6f 70 65 6e 28 29 5d 20 77 61 73 20 7a 65 b_open()] was ze
31b00 72 6f 29 2c 0a 2a 2a 20 74 68 69 73 20 66 75 6e ro),.** this fun
31b10 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 ction returns [S
31b20 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e QLITE_READONLY].
31b30 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 .**.** This func
31b40 74 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f tion may only mo
31b50 64 69 66 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 dify the content
31b60 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 3b 20 69 s of the BLOB; i
31b70 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 t is.** not poss
31b80 69 62 6c 65 20 74 6f 20 69 6e 63 72 65 61 73 65 ible to increase
31b90 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 42 the size of a B
31ba0 4c 4f 42 20 75 73 69 6e 67 20 74 68 69 73 20 41 LOB using this A
31bb0 50 49 2e 0a 2a 2a 20 49 66 20 6f 66 66 73 65 74 PI..** If offset
31bc0 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 iOffset is less
31bd0 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72 than N bytes fr
31be0 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 om the end of th
31bf0 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 e BLOB,.** [SQLI
31c00 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 TE_ERROR] is ret
31c10 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 urned and no dat
31c20 61 20 69 73 20 77 72 69 74 74 65 6e 2e 20 20 49 a is written. I
31c30 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 f N is.** less t
31c40 68 61 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 54 45 han zero [SQLITE
31c50 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 _ERROR] is retur
31c60 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 ned and no data
31c70 69 73 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a is written..**.*
31c80 2a 20 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 * An attempt to
31c90 77 72 69 74 65 20 74 6f 20 61 6e 20 65 78 70 69 write to an expi
31ca0 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 red [BLOB handle
31cb0 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a ] fails with an.
31cc0 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 ** error code of
31cd0 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e [SQLITE_ABORT].
31ce0 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 65 20 Writes to the
31cf0 42 4c 4f 42 20 74 68 61 74 20 6f 63 63 75 72 72 BLOB that occurr
31d00 65 64 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 ed.** before the
31d10 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 65 [BLOB handle] e
31d20 78 70 69 72 65 64 20 61 72 65 20 6e 6f 74 20 72 xpired are not r
31d30 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79 20 74 68 olled back by th
31d40 65 0a 2a 2a 20 65 78 70 69 72 61 74 69 6f 6e 20 e.** expiration
31d50 6f 66 20 74 68 65 20 68 61 6e 64 6c 65 2c 20 74 of the handle, t
31d60 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 hough of course
31d70 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20 6d 69 those changes mi
31d80 67 68 74 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e ght.** have been
31d90 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 overwritten by
31da0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 the statement th
31db0 61 74 20 65 78 70 69 72 65 64 20 74 68 65 20 42 at expired the B
31dc0 4c 4f 42 20 68 61 6e 64 6c 65 0a 2a 2a 20 6f 72 LOB handle.** or
31dd0 20 62 79 20 6f 74 68 65 72 20 69 6e 64 65 70 65 by other indepe
31de0 6e 64 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 ndent statements
31df0 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 ..**.** On succe
31e00 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 ss, SQLITE_OK is
31e10 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 returned..** Ot
31e20 68 65 72 77 69 73 65 2c 20 61 6e 20 20 5b 65 72 herwise, an [er
31e30 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 ror code] or an
31e40 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 [extended error
31e50 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 code] is returne
31e60 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 d..**.** Require
31e70 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 37 ments:.** [H1787
31e80 33 5d 20 5b 48 31 37 38 37 34 5d 20 5b 48 31 37 3] [H17874] [H17
31e90 38 37 35 5d 20 5b 48 31 37 38 37 36 5d 20 5b 48 875] [H17876] [H
31ea0 31 37 38 37 37 5d 20 5b 48 31 37 38 37 39 5d 20 17877] [H17879]
31eb0 5b 48 31 37 38 38 32 5d 20 5b 48 31 37 38 38 35 [H17882] [H17885
31ec0 5d 0a 2a 2a 20 5b 48 31 37 38 38 38 5d 0a 2a 2f ].** [H17888].*/
31ed0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f .int sqlite3_blo
31ee0 62 5f 77 72 69 74 65 28 73 71 6c 69 74 65 33 5f b_write(sqlite3_
31ef0 62 6c 6f 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f blob *, const vo
31f00 69 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e id *z, int n, in
31f10 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a t iOffset);../*.
31f20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 ** CAPI3REF: Vir
31f30 74 75 61 6c 20 46 69 6c 65 20 53 79 73 74 65 6d tual File System
31f40 20 4f 62 6a 65 63 74 73 20 7b 48 31 31 32 30 30 Objects {H11200
31f50 7d 20 3c 53 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a } <S20100>.**.**
31f60 20 41 20 76 69 72 74 75 61 6c 20 66 69 6c 65 73 A virtual files
31f70 79 73 74 65 6d 20 28 56 46 53 29 20 69 73 20 61 ystem (VFS) is a
31f80 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 n [sqlite3_vfs]
31f90 6f 62 6a 65 63 74 0a 2a 2a 20 74 68 61 74 20 53 object.** that S
31fa0 51 4c 69 74 65 20 75 73 65 73 20 74 6f 20 69 6e QLite uses to in
31fb0 74 65 72 61 63 74 0a 2a 2a 20 77 69 74 68 20 74 teract.** with t
31fc0 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 he underlying op
31fd0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 erating system.
31fe0 20 4d 6f 73 74 20 53 51 4c 69 74 65 20 62 75 69 Most SQLite bui
31ff0 6c 64 73 20 63 6f 6d 65 20 77 69 74 68 20 61 0a lds come with a.
32000 2a 2a 20 73 69 6e 67 6c 65 20 64 65 66 61 75 6c ** single defaul
32010 74 20 56 46 53 20 74 68 61 74 20 69 73 20 61 70 t VFS that is ap
32020 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68 propriate for th
32030 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e e host computer.
32040 0a 2a 2a 20 4e 65 77 20 56 46 53 65 73 20 63 61 .** New VFSes ca
32050 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 n be registered
32060 61 6e 64 20 65 78 69 73 74 69 6e 67 20 56 46 53 and existing VFS
32070 65 73 20 63 61 6e 20 62 65 20 75 6e 72 65 67 69 es can be unregi
32080 73 74 65 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 stered..** The f
32090 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 ollowing interfa
320a0 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 ces are provided
320b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
320c0 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 20 69 te3_vfs_find() i
320d0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
320e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
320f0 56 46 53 20 67 69 76 65 6e 20 69 74 73 20 6e 61 VFS given its na
32100 6d 65 2e 0a 2a 2a 20 4e 61 6d 65 73 20 61 72 65 me..** Names are
32110 20 63 61 73 65 20 73 65 6e 73 69 74 69 76 65 2e case sensitive.
32120 0a 2a 2a 20 4e 61 6d 65 73 20 61 72 65 20 7a 65 .** Names are ze
32130 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 ro-terminated UT
32140 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 F-8 strings..**
32150 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d If there is no m
32160 61 74 63 68 2c 20 61 20 4e 55 4c 4c 20 70 6f 69 atch, a NULL poi
32170 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 nter is returned
32180 2e 0a 2a 2a 20 49 66 20 7a 56 66 73 4e 61 6d 65 ..** If zVfsName
32190 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 is NULL then th
321a0 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 e default VFS is
321b0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
321c0 20 4e 65 77 20 56 46 53 65 73 20 61 72 65 20 72 New VFSes are r
321d0 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 73 egistered with s
321e0 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 qlite3_vfs_regis
321f0 74 65 72 28 29 2e 0a 2a 2a 20 45 61 63 68 20 6e ter()..** Each n
32200 65 77 20 56 46 53 20 62 65 63 6f 6d 65 73 20 74 ew VFS becomes t
32210 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 he default VFS i
32220 66 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 f the makeDflt f
32230 6c 61 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20 54 lag is set..** T
32240 68 65 20 73 61 6d 65 20 56 46 53 20 63 61 6e 20 he same VFS can
32250 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 be registered mu
32260 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 ltiple times wit
32270 68 6f 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20 hout injury..**
32280 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78 69 73 74 To make an exist
32290 69 6e 67 20 56 46 53 20 69 6e 74 6f 20 74 68 65 ing VFS into the
322a0 20 64 65 66 61 75 6c 74 20 56 46 53 2c 20 72 65 default VFS, re
322b0 67 69 73 74 65 72 20 69 74 20 61 67 61 69 6e 0a gister it again.
322c0 2a 2a 20 77 69 74 68 20 74 68 65 20 6d 61 6b 65 ** with the make
322d0 44 66 6c 74 20 66 6c 61 67 20 73 65 74 2e 20 20 Dflt flag set.
322e0 49 66 20 74 77 6f 20 64 69 66 66 65 72 65 6e 74 If two different
322f0 20 56 46 53 65 73 20 77 69 74 68 20 74 68 65 0a VFSes with the.
32300 2a 2a 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 ** same name are
32310 20 72 65 67 69 73 74 65 72 65 64 2c 20 74 68 65 registered, the
32320 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 behavior is und
32330 65 66 69 6e 65 64 2e 20 20 49 66 20 61 0a 2a 2a efined. If a.**
32340 20 56 46 53 20 69 73 20 72 65 67 69 73 74 65 72 VFS is register
32350 65 64 20 77 69 74 68 20 61 20 6e 61 6d 65 20 74 ed with a name t
32360 68 61 74 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 hat is NULL or a
32370 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 0a n empty string,.
32380 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 ** then the beha
32390 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 vior is undefine
323a0 64 2e 0a 2a 2a 0a 2a 2a 20 55 6e 72 65 67 69 73 d..**.** Unregis
323b0 74 65 72 20 61 20 56 46 53 20 77 69 74 68 20 74 ter a VFS with t
323c0 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 he sqlite3_vfs_u
323d0 6e 72 65 67 69 73 74 65 72 28 29 20 69 6e 74 65 nregister() inte
323e0 72 66 61 63 65 2e 0a 2a 2a 20 49 66 20 74 68 65 rface..** If the
323f0 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 default VFS is
32400 75 6e 72 65 67 69 73 74 65 72 65 64 2c 20 61 6e unregistered, an
32410 6f 74 68 65 72 20 56 46 53 20 69 73 20 63 68 6f other VFS is cho
32420 73 65 6e 20 61 73 0a 2a 2a 20 74 68 65 20 64 65 sen as.** the de
32430 66 61 75 6c 74 2e 20 20 54 68 65 20 63 68 6f 69 fault. The choi
32440 63 65 20 66 6f 72 20 74 68 65 20 6e 65 77 20 56 ce for the new V
32450 46 53 20 69 73 20 61 72 62 69 74 72 61 72 79 2e FS is arbitrary.
32460 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
32470 6e 74 73 3a 0a 2a 2a 20 5b 48 31 31 32 30 33 5d nts:.** [H11203]
32480 20 5b 48 31 31 32 30 36 5d 20 5b 48 31 31 32 30 [H11206] [H1120
32490 39 5d 20 5b 48 31 31 32 31 32 5d 20 5b 48 31 31 9] [H11212] [H11
324a0 32 31 35 5d 20 5b 48 31 31 32 31 38 5d 0a 2a 2f 215] [H11218].*/
324b0 0a 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 73 71 .sqlite3_vfs *sq
324c0 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 63 lite3_vfs_find(c
324d0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 4e onst char *zVfsN
324e0 61 6d 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 ame);.int sqlite
324f0 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 73 3_vfs_register(s
32500 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 qlite3_vfs*, int
32510 20 6d 61 6b 65 44 66 6c 74 29 3b 0a 69 6e 74 20 makeDflt);.int
32520 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 sqlite3_vfs_unre
32530 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76 gister(sqlite3_v
32540 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 fs*);../*.** CAP
32550 49 33 52 45 46 3a 20 4d 75 74 65 78 65 73 20 7b I3REF: Mutexes {
32560 48 31 37 30 30 30 7d 20 3c 53 32 30 30 30 30 3e H17000} <S20000>
32570 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 .**.** The SQLit
32580 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 e core uses thes
32590 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 74 e routines for t
325a0 68 72 65 61 64 0a 2a 2a 20 73 79 6e 63 68 72 6f hread.** synchro
325b0 6e 69 7a 61 74 69 6f 6e 2e 20 54 68 6f 75 67 68 nization. Though
325c0 20 74 68 65 79 20 61 72 65 20 69 6e 74 65 6e 64 they are intend
325d0 65 64 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a ed for internal.
325e0 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 ** use by SQLite
325f0 2c 20 63 6f 64 65 20 74 68 61 74 20 6c 69 6e 6b , code that link
32600 73 20 61 67 61 69 6e 73 74 20 53 51 4c 69 74 65 s against SQLite
32610 20 69 73 0a 2a 2a 20 70 65 72 6d 69 74 74 65 64 is.** permitted
32620 20 74 6f 20 75 73 65 20 61 6e 79 20 6f 66 20 74 to use any of t
32630 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a hese routines..*
32640 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 *.** The SQLite
32650 73 6f 75 72 63 65 20 63 6f 64 65 20 63 6f 6e 74 source code cont
32660 61 69 6e 73 20 6d 75 6c 74 69 70 6c 65 20 69 6d ains multiple im
32670 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a plementations.**
32680 20 6f 66 20 74 68 65 73 65 20 6d 75 74 65 78 20 of these mutex
32690 72 6f 75 74 69 6e 65 73 2e 20 20 41 6e 20 61 70 routines. An ap
326a0 70 72 6f 70 72 69 61 74 65 20 69 6d 70 6c 65 6d propriate implem
326b0 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 73 entation.** is s
326c0 65 6c 65 63 74 65 64 20 61 75 74 6f 6d 61 74 69 elected automati
326d0 63 61 6c 6c 79 20 61 74 20 63 6f 6d 70 69 6c 65 cally at compile
326e0 2d 74 69 6d 65 2e 20 20 54 68 65 20 66 6f 6c 6c -time. The foll
326f0 6f 77 69 6e 67 0a 2a 2a 20 69 6d 70 6c 65 6d 65 owing.** impleme
32700 6e 74 61 74 69 6f 6e 73 20 61 72 65 20 61 76 61 ntations are ava
32710 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 53 51 ilable in the SQ
32720 4c 69 74 65 20 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a Lite core:.**.**
32730 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20 <ul>.** <li>
32740 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 SQLITE_MUTEX_OS2
32750 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 .** <li> SQLIT
32760 45 5f 4d 55 54 45 58 5f 50 54 48 52 45 41 44 0a E_MUTEX_PTHREAD.
32770 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 ** <li> SQLITE
32780 5f 4d 55 54 45 58 5f 57 33 32 0a 2a 2a 20 3c 6c _MUTEX_W32.** <l
32790 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 i> SQLITE_MUTE
327a0 58 5f 4e 4f 4f 50 0a 2a 2a 20 3c 2f 75 6c 3e 0a X_NOOP.** </ul>.
327b0 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 **.** The SQLITE
327c0 5f 4d 55 54 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c _MUTEX_NOOP impl
327d0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 20 ementation is a
327e0 73 65 74 20 6f 66 20 72 6f 75 74 69 6e 65 73 0a set of routines.
327f0 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 20 ** that does no
32800 72 65 61 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 real locking and
32810 20 69 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 is appropriate
32820 66 6f 72 20 75 73 65 20 69 6e 0a 2a 2a 20 61 20 for use in.** a
32830 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 20 single-threaded
32840 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 application. Th
32850 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f e SQLITE_MUTEX_O
32860 53 32 2c 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 S2,.** SQLITE_MU
32870 54 45 58 5f 50 54 48 52 45 41 44 2c 20 61 6e 64 TEX_PTHREAD, and
32880 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 SQLITE_MUTEX_W3
32890 32 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2 implementation
328a0 73 0a 2a 2a 20 61 72 65 20 61 70 70 72 6f 70 72 s.** are appropr
328b0 69 61 74 65 20 66 6f 72 20 75 73 65 20 6f 6e 20 iate for use on
328c0 4f 53 2f 32 2c 20 55 6e 69 78 2c 20 61 6e 64 20 OS/2, Unix, and
328d0 57 69 6e 64 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 49 Windows..**.** I
328e0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 f SQLite is comp
328f0 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 iled with the SQ
32900 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 LITE_MUTEX_APPDE
32910 46 20 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a F preprocessor.*
32920 2a 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20 * macro defined
32930 28 77 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f (with "-DSQLITE_
32940 4d 55 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29 MUTEX_APPDEF=1")
32950 2c 20 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a , then no mutex.
32960 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
32970 6e 20 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69 n is included wi
32980 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20 th the library.
32990 49 6e 20 74 68 69 73 20 63 61 73 65 20 74 68 65 In this case the
329a0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 .** application
329b0 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 63 75 must supply a cu
329c0 73 74 6f 6d 20 6d 75 74 65 78 20 69 6d 70 6c 65 stom mutex imple
329d0 6d 65 6e 74 61 74 69 6f 6e 20 75 73 69 6e 67 20 mentation using
329e0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 the.** [SQLITE_C
329f0 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 ONFIG_MUTEX] opt
32a00 69 6f 6e 20 6f 66 20 74 68 65 20 73 71 6c 69 74 ion of the sqlit
32a10 65 33 5f 63 6f 6e 66 69 67 28 29 20 66 75 6e 63 e3_config() func
32a20 74 69 6f 6e 0a 2a 2a 20 62 65 66 6f 72 65 20 63 tion.** before c
32a30 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 69 alling sqlite3_i
32a40 6e 69 74 69 61 6c 69 7a 65 28 29 20 6f 72 20 61 nitialize() or a
32a50 6e 79 20 6f 74 68 65 72 20 70 75 62 6c 69 63 20 ny other public
32a60 73 71 6c 69 74 65 33 5f 0a 2a 2a 20 66 75 6e 63 sqlite3_.** func
32a70 74 69 6f 6e 20 74 68 61 74 20 63 61 6c 6c 73 20 tion that calls
32a80 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
32a90 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 ze()..**.** {H17
32aa0 30 31 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 011} The sqlite3
32ab0 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 72 _mutex_alloc() r
32ac0 6f 75 74 69 6e 65 20 61 6c 6c 6f 63 61 74 65 73 outine allocates
32ad0 20 61 20 6e 65 77 0a 2a 2a 20 6d 75 74 65 78 20 a new.** mutex
32ae0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f and returns a po
32af0 69 6e 74 65 72 20 74 6f 20 69 74 2e 20 7b 48 31 inter to it. {H1
32b00 37 30 31 32 7d 20 49 66 20 69 74 20 72 65 74 75 7012} If it retu
32b10 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74 rns NULL.** that
32b20 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 6d 75 means that a mu
32b30 74 65 78 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 tex could not be
32b40 20 61 6c 6c 6f 63 61 74 65 64 2e 20 7b 48 31 37 allocated. {H17
32b50 30 31 33 7d 20 53 51 4c 69 74 65 0a 2a 2a 20 77 013} SQLite.** w
32b60 69 6c 6c 20 75 6e 77 69 6e 64 20 69 74 73 20 73 ill unwind its s
32b70 74 61 63 6b 20 61 6e 64 20 72 65 74 75 72 6e 20 tack and return
32b80 61 6e 20 65 72 72 6f 72 2e 20 7b 48 31 37 30 31 an error. {H1701
32b90 34 7d 20 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 4} The argument.
32ba0 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 ** to sqlite3_mu
32bb0 74 65 78 5f 61 6c 6c 6f 63 28 29 20 69 73 20 6f tex_alloc() is o
32bc0 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 ne of these inte
32bd0 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a ger constants:.*
32be0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
32bf0 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f > SQLITE_MUTEX_
32c00 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 FAST.** <li> SQ
32c10 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 LITE_MUTEX_RECUR
32c20 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 SIVE.** <li> SQ
32c30 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 LITE_MUTEX_STATI
32c40 43 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c 69 3e C_MASTER.** <li>
32c50 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 SQLITE_MUTEX_S
32c60 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 TATIC_MEM.** <li
32c70 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f > SQLITE_MUTEX_
32c80 53 54 41 54 49 43 5f 4d 45 4d 32 0a 2a 2a 20 3c STATIC_MEM2.** <
32c90 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 li> SQLITE_MUTE
32ca0 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 0a 2a 2a X_STATIC_PRNG.**
32cb0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 <li> SQLITE_MU
32cc0 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 0a 2a TEX_STATIC_LRU.*
32cd0 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d * <li> SQLITE_M
32ce0 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 32 UTEX_STATIC_LRU2
32cf0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
32d00 7b 48 31 37 30 31 35 7d 20 54 68 65 20 66 69 72 {H17015} The fir
32d10 73 74 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 st two constants
32d20 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 6d cause sqlite3_m
32d30 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20 utex_alloc() to
32d40 63 72 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20 create.** a new
32d50 6d 75 74 65 78 2e 20 20 54 68 65 20 6e 65 77 20 mutex. The new
32d60 6d 75 74 65 78 20 69 73 20 72 65 63 75 72 73 69 mutex is recursi
32d70 76 65 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d ve when SQLITE_M
32d80 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a UTEX_RECURSIVE.*
32d90 2a 20 69 73 20 75 73 65 64 20 62 75 74 20 6e 6f * is used but no
32da0 74 20 6e 65 63 65 73 73 61 72 69 6c 79 20 73 6f t necessarily so
32db0 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 when SQLITE_MUT
32dc0 45 58 5f 46 41 53 54 20 69 73 20 75 73 65 64 2e EX_FAST is used.
32dd0 20 7b 45 4e 44 7d 0a 2a 2a 20 54 68 65 20 6d 75 {END}.** The mu
32de0 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 tex implementati
32df0 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 on does not need
32e00 20 74 6f 20 6d 61 6b 65 20 61 20 64 69 73 74 69 to make a disti
32e10 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 nction.** betwee
32e20 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 n SQLITE_MUTEX_R
32e30 45 43 55 52 53 49 56 45 20 61 6e 64 20 53 51 4c ECURSIVE and SQL
32e40 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 ITE_MUTEX_FAST i
32e50 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 f it does.** not
32e60 20 77 61 6e 74 20 74 6f 2e 20 20 7b 48 31 37 30 want to. {H170
32e70 31 36 7d 20 42 75 74 20 53 51 4c 69 74 65 20 77 16} But SQLite w
32e80 69 6c 6c 20 6f 6e 6c 79 20 72 65 71 75 65 73 74 ill only request
32e90 20 61 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 a recursive mut
32ea0 65 78 20 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77 ex in.** cases w
32eb0 68 65 72 65 20 69 74 20 72 65 61 6c 6c 79 20 6e here it really n
32ec0 65 65 64 73 20 6f 6e 65 2e 20 20 7b 45 4e 44 7d eeds one. {END}
32ed0 20 49 66 20 61 20 66 61 73 74 65 72 20 6e 6f 6e If a faster non
32ee0 2d 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 -recursive mutex
32ef0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
32f00 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 on is available
32f10 6f 6e 20 74 68 65 20 68 6f 73 74 20 70 6c 61 74 on the host plat
32f20 66 6f 72 6d 2c 20 74 68 65 20 6d 75 74 65 78 20 form, the mutex
32f30 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20 6d 69 67 subsystem.** mig
32f40 68 74 20 72 65 74 75 72 6e 20 73 75 63 68 20 61 ht return such a
32f50 20 6d 75 74 65 78 20 69 6e 20 72 65 73 70 6f 6e mutex in respon
32f60 73 65 20 74 6f 20 53 51 4c 49 54 45 5f 4d 55 54 se to SQLITE_MUT
32f70 45 58 5f 46 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 7b EX_FAST..**.** {
32f80 48 31 37 30 31 37 7d 20 54 68 65 20 6f 74 68 65 H17017} The othe
32f90 72 20 61 6c 6c 6f 77 65 64 20 70 61 72 61 6d 65 r allowed parame
32fa0 74 65 72 73 20 74 6f 20 73 71 6c 69 74 65 33 5f ters to sqlite3_
32fb0 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 65 61 mutex_alloc() ea
32fc0 63 68 20 72 65 74 75 72 6e 0a 2a 2a 20 61 20 70 ch return.** a p
32fd0 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 61 74 ointer to a stat
32fe0 69 63 20 70 72 65 65 78 69 73 74 69 6e 67 20 6d ic preexisting m
32ff0 75 74 65 78 2e 20 7b 45 4e 44 7d 20 20 46 6f 75 utex. {END} Fou
33000 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 r static mutexes
33010 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 62 79 20 are.** used by
33020 74 68 65 20 63 75 72 72 65 6e 74 20 76 65 72 73 the current vers
33030 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 ion of SQLite.
33040 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 Future versions
33050 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 61 79 of SQLite.** may
33060 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 add additional
33070 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e 20 static mutexes.
33080 20 53 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 Static mutexes
33090 61 72 65 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c are for internal
330a0 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74 .** use by SQLit
330b0 65 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 e only. Applica
330c0 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 53 tions that use S
330d0 51 4c 69 74 65 20 6d 75 74 65 78 65 73 20 73 68 QLite mutexes sh
330e0 6f 75 6c 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79 ould.** use only
330f0 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 the dynamic mut
33100 65 78 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 exes returned by
33110 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 SQLITE_MUTEX_FA
33120 53 54 20 6f 72 0a 2a 2a 20 53 51 4c 49 54 45 5f ST or.** SQLITE_
33130 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 2e MUTEX_RECURSIVE.
33140 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 38 7d 20 .**.** {H17018}
33150 4e 6f 74 65 20 74 68 61 74 20 69 66 20 6f 6e 65 Note that if one
33160 20 6f 66 20 74 68 65 20 64 79 6e 61 6d 69 63 20 of the dynamic
33170 6d 75 74 65 78 20 70 61 72 61 6d 65 74 65 72 73 mutex parameters
33180 20 28 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 (SQLITE_MUTEX_F
33190 41 53 54 0a 2a 2a 20 6f 72 20 53 51 4c 49 54 45 AST.** or SQLITE
331a0 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 _MUTEX_RECURSIVE
331b0 29 20 69 73 20 75 73 65 64 20 74 68 65 6e 20 73 ) is used then s
331c0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c qlite3_mutex_all
331d0 6f 63 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 oc().** returns
331e0 61 20 64 69 66 66 65 72 65 6e 74 20 6d 75 74 65 a different mute
331f0 78 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 2e x on every call.
33200 20 20 7b 48 31 37 30 33 34 7d 20 42 75 74 20 66 {H17034} But f
33210 6f 72 20 74 68 65 20 73 74 61 74 69 63 0a 2a 2a or the static.**
33220 20 6d 75 74 65 78 20 74 79 70 65 73 2c 20 74 68 mutex types, th
33230 65 20 73 61 6d 65 20 6d 75 74 65 78 20 69 73 20 e same mutex is
33240 72 65 74 75 72 6e 65 64 20 6f 6e 20 65 76 65 72 returned on ever
33250 79 20 63 61 6c 6c 20 74 68 61 74 20 68 61 73 0a y call that has.
33260 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 79 70 65 ** the same type
33270 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b number..**.** {
33280 48 31 37 30 31 39 7d 20 54 68 65 20 73 71 6c 69 H17019} The sqli
33290 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 te3_mutex_free()
332a0 20 72 6f 75 74 69 6e 65 20 64 65 61 6c 6c 6f 63 routine dealloc
332b0 61 74 65 73 20 61 20 70 72 65 76 69 6f 75 73 6c ates a previousl
332c0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 64 y.** allocated d
332d0 79 6e 61 6d 69 63 20 6d 75 74 65 78 2e 20 7b 48 ynamic mutex. {H
332e0 31 37 30 32 30 7d 20 53 51 4c 69 74 65 20 69 73 17020} SQLite is
332f0 20 63 61 72 65 66 75 6c 20 74 6f 20 64 65 61 6c careful to deal
33300 6c 6f 63 61 74 65 20 65 76 65 72 79 0a 2a 2a 20 locate every.**
33310 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 74 68 dynamic mutex th
33320 61 74 20 69 74 20 61 6c 6c 6f 63 61 74 65 73 2e at it allocates.
33330 20 7b 41 31 37 30 32 31 7d 20 54 68 65 20 64 79 {A17021} The dy
33340 6e 61 6d 69 63 20 6d 75 74 65 78 65 73 20 6d 75 namic mutexes mu
33350 73 74 20 6e 6f 74 20 62 65 20 69 6e 0a 2a 2a 20 st not be in.**
33360 75 73 65 20 77 68 65 6e 20 74 68 65 79 20 61 72 use when they ar
33370 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 20 7b e deallocated. {
33380 41 31 37 30 32 32 7d 20 41 74 74 65 6d 70 74 69 A17022} Attempti
33390 6e 67 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 ng to deallocate
333a0 20 61 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 a static.** mut
333b0 65 78 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e ex results in un
333c0 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 defined behavior
333d0 2e 20 7b 48 31 37 30 32 33 7d 20 53 51 4c 69 74 . {H17023} SQLit
333e0 65 20 6e 65 76 65 72 20 64 65 61 6c 6c 6f 63 61 e never dealloca
333f0 74 65 73 0a 2a 2a 20 61 20 73 74 61 74 69 63 20 tes.** a static
33400 6d 75 74 65 78 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a mutex. {END}.**.
33410 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d ** The sqlite3_m
33420 75 74 65 78 5f 65 6e 74 65 72 28 29 20 61 6e 64 utex_enter() and
33430 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 sqlite3_mutex_t
33440 72 79 28 29 20 72 6f 75 74 69 6e 65 73 20 61 74 ry() routines at
33450 74 65 6d 70 74 0a 2a 2a 20 74 6f 20 65 6e 74 65 tempt.** to ente
33460 72 20 61 20 6d 75 74 65 78 2e 20 7b 48 31 37 30 r a mutex. {H170
33470 32 34 7d 20 49 66 20 61 6e 6f 74 68 65 72 20 74 24} If another t
33480 68 72 65 61 64 20 69 73 20 61 6c 72 65 61 64 79 hread is already
33490 20 77 69 74 68 69 6e 20 74 68 65 20 6d 75 74 65 within the mute
334a0 78 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 x,.** sqlite3_mu
334b0 74 65 78 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c tex_enter() will
334c0 20 62 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 block and sqlit
334d0 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 77 e3_mutex_try() w
334e0 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 ill return.** SQ
334f0 4c 49 54 45 5f 42 55 53 59 2e 20 7b 48 31 37 30 LITE_BUSY. {H170
33500 32 35 7d 20 20 54 68 65 20 73 71 6c 69 74 65 33 25} The sqlite3
33510 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 69 6e 74 _mutex_try() int
33520 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 5b erface returns [
33530 53 51 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 75 70 SQLITE_OK].** up
33540 6f 6e 20 73 75 63 63 65 73 73 66 75 6c 20 65 6e on successful en
33550 74 72 79 2e 20 20 7b 48 31 37 30 32 36 7d 20 4d try. {H17026} M
33560 75 74 65 78 65 73 20 63 72 65 61 74 65 64 20 75 utexes created u
33570 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d sing.** SQLITE_M
33580 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 63 UTEX_RECURSIVE c
33590 61 6e 20 62 65 20 65 6e 74 65 72 65 64 20 6d 75 an be entered mu
335a0 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 62 79 20 ltiple times by
335b0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e the same thread.
335c0 0a 2a 2a 20 7b 48 31 37 30 32 37 7d 20 49 6e 20 .** {H17027} In
335d0 73 75 63 68 20 63 61 73 65 73 20 74 68 65 2c 0a such cases the,.
335e0 2a 2a 20 6d 75 74 65 78 20 6d 75 73 74 20 62 65 ** mutex must be
335f0 20 65 78 69 74 65 64 20 61 6e 20 65 71 75 61 6c exited an equal
33600 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 number of times
33610 20 62 65 66 6f 72 65 20 61 6e 6f 74 68 65 72 20 before another
33620 74 68 72 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e thread.** can en
33630 74 65 72 2e 20 20 7b 41 31 37 30 32 38 7d 20 49 ter. {A17028} I
33640 66 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 f the same threa
33650 64 20 74 72 69 65 73 20 74 6f 20 65 6e 74 65 72 d tries to enter
33660 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6b 69 any other.** ki
33670 6e 64 20 6f 66 20 6d 75 74 65 78 20 6d 6f 72 65 nd of mutex more
33680 20 74 68 61 6e 20 6f 6e 63 65 2c 20 74 68 65 20 than once, the
33690 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 behavior is unde
336a0 66 69 6e 65 64 2e 0a 2a 2a 20 7b 48 31 37 30 32 fined..** {H1702
336b0 39 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 9} SQLite will n
336c0 65 76 65 72 20 65 78 68 69 62 69 74 0a 2a 2a 20 ever exhibit.**
336d0 73 75 63 68 20 62 65 68 61 76 69 6f 72 20 69 6e such behavior in
336e0 20 69 74 73 20 6f 77 6e 20 75 73 65 20 6f 66 20 its own use of
336f0 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 mutexes..**.** S
33700 6f 6d 65 20 73 79 73 74 65 6d 73 20 28 66 6f 72 ome systems (for
33710 20 65 78 61 6d 70 6c 65 2c 20 57 69 6e 64 6f 77 example, Window
33720 73 20 39 35 29 20 64 6f 20 6e 6f 74 20 73 75 70 s 95) do not sup
33730 70 6f 72 74 20 74 68 65 20 6f 70 65 72 61 74 69 port the operati
33740 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 65 on.** implemente
33750 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 75 74 d by sqlite3_mut
33760 65 78 5f 74 72 79 28 29 2e 20 20 4f 6e 20 74 68 ex_try(). On th
33770 6f 73 65 20 73 79 73 74 65 6d 73 2c 20 73 71 6c ose systems, sql
33780 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 ite3_mutex_try()
33790 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 .** will always
337a0 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 42 55 return SQLITE_BU
337b0 53 59 2e 20 20 7b 48 31 37 30 33 30 7d 20 54 68 SY. {H17030} Th
337c0 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6f 6e e SQLite core on
337d0 6c 79 20 65 76 65 72 20 75 73 65 73 0a 2a 2a 20 ly ever uses.**
337e0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 sqlite3_mutex_tr
337f0 79 28 29 20 61 73 20 61 6e 20 6f 70 74 69 6d 69 y() as an optimi
33800 7a 61 74 69 6f 6e 20 73 6f 20 74 68 69 73 20 69 zation so this i
33810 73 20 61 63 63 65 70 74 61 62 6c 65 20 62 65 68 s acceptable beh
33820 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 avior..**.** {H1
33830 37 30 33 31 7d 20 54 68 65 20 73 71 6c 69 74 65 7031} The sqlite
33840 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20 3_mutex_leave()
33850 72 6f 75 74 69 6e 65 20 65 78 69 74 73 20 61 20 routine exits a
33860 6d 75 74 65 78 20 74 68 61 74 20 77 61 73 0a 2a mutex that was.*
33870 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 65 6e 74 * previously ent
33880 65 72 65 64 20 62 79 20 74 68 65 20 73 61 6d 65 ered by the same
33890 20 74 68 72 65 61 64 2e 20 20 7b 41 31 37 30 33 thread. {A1703
338a0 32 7d 20 54 68 65 20 62 65 68 61 76 69 6f 72 0a 2} The behavior.
338b0 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 ** is undefined
338c0 69 66 20 74 68 65 20 6d 75 74 65 78 20 69 73 20 if the mutex is
338d0 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 65 6e not currently en
338e0 74 65 72 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 tered by the.**
338f0 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 6f calling thread o
33900 72 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 r is not current
33910 6c 79 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 7b ly allocated. {
33920 48 31 37 30 33 33 7d 20 53 51 4c 69 74 65 20 77 H17033} SQLite w
33930 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20 ill.** never do
33940 65 69 74 68 65 72 2e 20 7b 45 4e 44 7d 0a 2a 2a either. {END}.**
33950 0a 2a 2a 20 49 66 20 74 68 65 20 61 72 67 75 6d .** If the argum
33960 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d ent to sqlite3_m
33970 75 74 65 78 5f 65 6e 74 65 72 28 29 2c 20 73 71 utex_enter(), sq
33980 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 lite3_mutex_try(
33990 29 2c 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 ), or.** sqlite3
339a0 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20 69 _mutex_leave() i
339b0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
339c0 2c 20 74 68 65 6e 20 61 6c 6c 20 74 68 72 65 65 , then all three
339d0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 62 65 68 routines.** beh
339e0 61 76 65 20 61 73 20 6e 6f 2d 6f 70 73 2e 0a 2a ave as no-ops..*
339f0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
33a00 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 sqlite3_mutex_he
33a10 6c 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 ld()] and [sqlit
33a20 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 e3_mutex_notheld
33a30 28 29 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f ()]..*/.sqlite3_
33a40 6d 75 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 6d mutex *sqlite3_m
33a50 75 74 65 78 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b utex_alloc(int);
33a60 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 .void sqlite3_mu
33a70 74 65 78 5f 66 72 65 65 28 73 71 6c 69 74 65 33 tex_free(sqlite3
33a80 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 _mutex*);.void s
33a90 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 qlite3_mutex_ent
33aa0 65 72 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 er(sqlite3_mutex
33ab0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f *);.int sqlite3_
33ac0 6d 75 74 65 78 5f 74 72 79 28 73 71 6c 69 74 65 mutex_try(sqlite
33ad0 33 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 3_mutex*);.void
33ae0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 sqlite3_mutex_le
33af0 61 76 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 ave(sqlite3_mute
33b00 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 x*);../*.** CAPI
33b10 33 52 45 46 3a 20 4d 75 74 65 78 20 4d 65 74 68 3REF: Mutex Meth
33b20 6f 64 73 20 4f 62 6a 65 63 74 20 7b 48 31 37 31 ods Object {H171
33b30 32 30 7d 20 3c 53 32 30 31 33 30 3e 0a 2a 2a 20 20} <S20130>.**
33b40 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a EXPERIMENTAL.**.
33b50 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f ** An instance o
33b60 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 f this structure
33b70 20 64 65 66 69 6e 65 73 20 74 68 65 20 6c 6f 77 defines the low
33b80 2d 6c 65 76 65 6c 20 72 6f 75 74 69 6e 65 73 0a -level routines.
33b90 2a 2a 20 75 73 65 64 20 74 6f 20 61 6c 6c 6f 63 ** used to alloc
33ba0 61 74 65 20 61 6e 64 20 75 73 65 20 6d 75 74 65 ate and use mute
33bb0 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 55 73 75 61 6c xes..**.** Usual
33bc0 6c 79 2c 20 74 68 65 20 64 65 66 61 75 6c 74 20 ly, the default
33bd0 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 mutex implementa
33be0 74 69 6f 6e 73 20 70 72 6f 76 69 64 65 64 20 62 tions provided b
33bf0 79 20 53 51 4c 69 74 65 20 61 72 65 0a 2a 2a 20 y SQLite are.**
33c00 73 75 66 66 69 63 69 65 6e 74 2c 20 68 6f 77 65 sufficient, howe
33c10 76 65 72 20 74 68 65 20 75 73 65 72 20 68 61 73 ver the user has
33c20 20 74 68 65 20 6f 70 74 69 6f 6e 20 6f 66 20 73 the option of s
33c30 75 62 73 74 69 74 75 74 69 6e 67 20 61 20 63 75 ubstituting a cu
33c40 73 74 6f 6d 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e stom.** implemen
33c50 74 61 74 69 6f 6e 20 66 6f 72 20 73 70 65 63 69 tation for speci
33c60 61 6c 69 7a 65 64 20 64 65 70 6c 6f 79 6d 65 6e alized deploymen
33c70 74 73 20 6f 72 20 73 79 73 74 65 6d 73 20 66 6f ts or systems fo
33c80 72 20 77 68 69 63 68 20 53 51 4c 69 74 65 0a 2a r which SQLite.*
33c90 2a 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 * does not provi
33ca0 64 65 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d de a suitable im
33cb0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 49 6e plementation. In
33cc0 20 74 68 69 73 20 63 61 73 65 2c 20 74 68 65 20 this case, the
33cd0 75 73 65 72 0a 2a 2a 20 63 72 65 61 74 65 73 20 user.** creates
33ce0 61 6e 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e and populates an
33cf0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 instance of thi
33d00 73 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 70 s structure to p
33d10 61 73 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 ass.** to sqlite
33d20 33 5f 63 6f 6e 66 69 67 28 29 20 61 6c 6f 6e 67 3_config() along
33d30 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 with the [SQLIT
33d40 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20 E_CONFIG_MUTEX]
33d50 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 64 64 69 74 option..** Addit
33d60 69 6f 6e 61 6c 6c 79 2c 20 61 6e 20 69 6e 73 74 ionally, an inst
33d70 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 ance of this str
33d80 75 63 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 ucture can be us
33d90 65 64 20 61 73 20 61 6e 0a 2a 2a 20 6f 75 74 70 ed as an.** outp
33da0 75 74 20 76 61 72 69 61 62 6c 65 20 77 68 65 6e ut variable when
33db0 20 71 75 65 72 79 69 6e 67 20 74 68 65 20 73 79 querying the sy
33dc0 73 74 65 6d 20 66 6f 72 20 74 68 65 20 63 75 72 stem for the cur
33dd0 72 65 6e 74 20 6d 75 74 65 78 0a 2a 2a 20 69 6d rent mutex.** im
33de0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 75 73 plementation, us
33df0 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ing the [SQLITE_
33e00 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d CONFIG_GETMUTEX]
33e10 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 option..**.** T
33e20 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 he xMutexInit me
33e30 74 68 6f 64 20 64 65 66 69 6e 65 64 20 62 79 20 thod defined by
33e40 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 69 this structure i
33e50 73 20 69 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 s invoked as.**
33e60 70 61 72 74 20 6f 66 20 73 79 73 74 65 6d 20 69 part of system i
33e70 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 62 79 nitialization by
33e80 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 the sqlite3_ini
33e90 74 69 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 tialize() functi
33ea0 6f 6e 2e 0a 2a 2a 20 7b 48 31 37 30 30 31 7d 20 on..** {H17001}
33eb0 54 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20 72 The xMutexInit r
33ec0 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 62 65 20 outine shall be
33ed0 63 61 6c 6c 65 64 20 62 79 20 53 51 4c 69 74 65 called by SQLite
33ee0 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 0a 2a once for each.*
33ef0 2a 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c * effective call
33f00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 to [sqlite3_ini
33f10 74 69 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a tialize()]..**.*
33f20 2a 20 54 68 65 20 78 4d 75 74 65 78 45 6e 64 20 * The xMutexEnd
33f30 6d 65 74 68 6f 64 20 64 65 66 69 6e 65 64 20 62 method defined b
33f40 79 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 y this structure
33f50 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 0a 2a is invoked as.*
33f60 2a 20 70 61 72 74 20 6f 66 20 73 79 73 74 65 6d * part of system
33f70 20 73 68 75 74 64 6f 77 6e 20 62 79 20 74 68 65 shutdown by the
33f80 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
33f90 6e 28 29 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 n() function. Th
33fa0 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e.** implementat
33fb0 69 6f 6e 20 6f 66 20 74 68 69 73 20 6d 65 74 68 ion of this meth
33fc0 6f 64 20 69 73 20 65 78 70 65 63 74 65 64 20 74 od is expected t
33fd0 6f 20 72 65 6c 65 61 73 65 20 61 6c 6c 20 6f 75 o release all ou
33fe0 74 73 74 61 6e 64 69 6e 67 0a 2a 2a 20 72 65 73 tstanding.** res
33ff0 6f 75 72 63 65 73 20 6f 62 74 61 69 6e 65 64 20 ources obtained
34000 62 79 20 74 68 65 20 6d 75 74 65 78 20 6d 65 74 by the mutex met
34010 68 6f 64 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 hods implementat
34020 69 6f 6e 2c 20 65 73 70 65 63 69 61 6c 6c 79 0a ion, especially.
34030 2a 2a 20 74 68 6f 73 65 20 6f 62 74 61 69 6e 65 ** those obtaine
34040 64 20 62 79 20 74 68 65 20 78 4d 75 74 65 78 49 d by the xMutexI
34050 6e 69 74 20 6d 65 74 68 6f 64 2e 20 7b 48 31 37 nit method. {H17
34060 30 30 33 7d 20 54 68 65 20 78 4d 75 74 65 78 45 003} The xMutexE
34070 6e 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 nd().** interfac
34080 65 20 73 68 61 6c 6c 20 62 65 20 69 6e 76 6f 6b e shall be invok
34090 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 ed once for each
340a0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
340b0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 3_shutdown()]..*
340c0 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 *.** The remaini
340d0 6e 67 20 73 65 76 65 6e 20 6d 65 74 68 6f 64 73 ng seven methods
340e0 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 defined by this
340f0 20 73 74 72 75 63 74 75 72 65 20 28 78 4d 75 74 structure (xMut
34100 65 78 41 6c 6c 6f 63 2c 0a 2a 2a 20 78 4d 75 74 exAlloc,.** xMut
34110 65 78 46 72 65 65 2c 20 78 4d 75 74 65 78 45 6e exFree, xMutexEn
34120 74 65 72 2c 20 78 4d 75 74 65 78 54 72 79 2c 20 ter, xMutexTry,
34130 78 4d 75 74 65 78 4c 65 61 76 65 2c 20 78 4d 75 xMutexLeave, xMu
34140 74 65 78 48 65 6c 64 20 61 6e 64 0a 2a 2a 20 78 texHeld and.** x
34150 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 20 69 6d MutexNotheld) im
34160 70 6c 65 6d 65 6e 74 20 74 68 65 20 66 6f 6c 6c plement the foll
34170 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 owing interfaces
34180 20 28 72 65 73 70 65 63 74 69 76 65 6c 79 29 3a (respectively):
34190 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 .**.** <ul>.**
341a0 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f <li> [sqlite3_
341b0 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 3c mutex_alloc()] <
341c0 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 /li>.** <li>
341d0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 [sqlite3_mutex_f
341e0 72 65 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 ree()] </li>.**
341f0 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 <li> [sqlite3
34200 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 5d 20 _mutex_enter()]
34210 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 </li>.** <li>
34220 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
34230 74 72 79 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 try()] </li>.**
34240 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 <li> [sqlite3
34250 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 5d 20 _mutex_leave()]
34260 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 </li>.** <li>
34270 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
34280 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a held()] </li>.**
34290 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 <li> [sqlite
342a0 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 3_mutex_notheld(
342b0 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c )] </li>.** </ul
342c0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 >.**.** The only
342d0 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 74 difference is t
342e0 68 61 74 20 74 68 65 20 70 75 62 6c 69 63 20 73 hat the public s
342f0 71 6c 69 74 65 33 5f 58 58 58 20 66 75 6e 63 74 qlite3_XXX funct
34300 69 6f 6e 73 20 65 6e 75 6d 65 72 61 74 65 64 0a ions enumerated.
34310 2a 2a 20 61 62 6f 76 65 20 73 69 6c 65 6e 74 6c ** above silentl
34320 79 20 69 67 6e 6f 72 65 20 61 6e 79 20 69 6e 76 y ignore any inv
34330 6f 63 61 74 69 6f 6e 73 20 74 68 61 74 20 70 61 ocations that pa
34340 73 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ss a NULL pointe
34350 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 r instead.** of
34360 61 20 76 61 6c 69 64 20 6d 75 74 65 78 20 68 61 a valid mutex ha
34370 6e 64 6c 65 2e 20 54 68 65 20 69 6d 70 6c 65 6d ndle. The implem
34380 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 entations of the
34390 20 6d 65 74 68 6f 64 73 20 64 65 66 69 6e 65 64 methods defined
343a0 0a 2a 2a 20 62 79 20 74 68 69 73 20 73 74 72 75 .** by this stru
343b0 63 74 75 72 65 20 61 72 65 20 6e 6f 74 20 72 65 cture are not re
343c0 71 75 69 72 65 64 20 74 6f 20 68 61 6e 64 6c 65 quired to handle
343d0 20 74 68 69 73 20 63 61 73 65 2c 20 74 68 65 20 this case, the
343e0 72 65 73 75 6c 74 73 0a 2a 2a 20 6f 66 20 70 61 results.** of pa
343f0 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 ssing a NULL poi
34400 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 nter instead of
34410 61 20 76 61 6c 69 64 20 6d 75 74 65 78 20 68 61 a valid mutex ha
34420 6e 64 6c 65 20 61 72 65 20 75 6e 64 65 66 69 6e ndle are undefin
34430 65 64 0a 2a 2a 20 28 69 2e 65 2e 20 69 74 20 69 ed.** (i.e. it i
34440 73 20 61 63 63 65 70 74 61 62 6c 65 20 74 6f 20 s acceptable to
34450 70 72 6f 76 69 64 65 20 61 6e 20 69 6d 70 6c 65 provide an imple
34460 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 73 mentation that s
34470 65 67 66 61 75 6c 74 73 20 69 66 0a 2a 2a 20 69 egfaults if.** i
34480 74 20 69 73 20 70 61 73 73 65 64 20 61 20 4e 55 t is passed a NU
34490 4c 4c 20 70 6f 69 6e 74 65 72 29 2e 0a 2a 2f 0a LL pointer)..*/.
344a0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
344b0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
344c0 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 75 74 hods sqlite3_mut
344d0 65 78 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 ex_methods;.stru
344e0 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 ct sqlite3_mutex
344f0 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 _methods {. int
34500 20 28 2a 78 4d 75 74 65 78 49 6e 69 74 29 28 76 (*xMutexInit)(v
34510 6f 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d oid);. int (*xM
34520 75 74 65 78 45 6e 64 29 28 76 6f 69 64 29 3b 0a utexEnd)(void);.
34530 20 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 sqlite3_mutex
34540 2a 28 2a 78 4d 75 74 65 78 41 6c 6c 6f 63 29 28 *(*xMutexAlloc)(
34550 69 6e 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 int);. void (*x
34560 4d 75 74 65 78 46 72 65 65 29 28 73 71 6c 69 74 MutexFree)(sqlit
34570 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 e3_mutex *);. v
34580 6f 69 64 20 28 2a 78 4d 75 74 65 78 45 6e 74 65 oid (*xMutexEnte
34590 72 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 r)(sqlite3_mutex
345a0 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 *);. int (*xMu
345b0 74 65 78 54 72 79 29 28 73 71 6c 69 74 65 33 5f texTry)(sqlite3_
345c0 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 mutex *);. void
345d0 20 28 2a 78 4d 75 74 65 78 4c 65 61 76 65 29 28 (*xMutexLeave)(
345e0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 sqlite3_mutex *)
345f0 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 ;. int (*xMutex
34600 48 65 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d 75 Held)(sqlite3_mu
34610 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a tex *);. int (*
34620 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 28 73 xMutexNotheld)(s
34630 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b qlite3_mutex *);
34640 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .};../*.** CAPI3
34650 52 45 46 3a 20 4d 75 74 65 78 20 56 65 72 69 66 REF: Mutex Verif
34660 69 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 ication Routines
34670 20 7b 48 31 37 30 38 30 7d 20 3c 53 32 30 31 33 {H17080} <S2013
34680 30 3e 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 0> <S30800>.**.*
34690 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 * The sqlite3_mu
346a0 74 65 78 5f 68 65 6c 64 28 29 20 61 6e 64 20 73 tex_held() and s
346b0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 qlite3_mutex_not
346c0 68 65 6c 64 28 29 20 72 6f 75 74 69 6e 65 73 0a held() routines.
346d0 2a 2a 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 ** are intended
346e0 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 for use inside a
346f0 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e ssert() statemen
34700 74 73 2e 20 7b 48 31 37 30 38 31 7d 20 54 68 65 ts. {H17081} The
34710 20 53 51 4c 69 74 65 20 63 6f 72 65 0a 2a 2a 20 SQLite core.**
34720 6e 65 76 65 72 20 75 73 65 73 20 74 68 65 73 65 never uses these
34730 20 72 6f 75 74 69 6e 65 73 20 65 78 63 65 70 74 routines except
34740 20 69 6e 73 69 64 65 20 61 6e 20 61 73 73 65 72 inside an asser
34750 74 28 29 20 61 6e 64 20 61 70 70 6c 69 63 61 74 t() and applicat
34760 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 64 76 69 ions.** are advi
34770 73 65 64 20 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 sed to follow th
34780 65 20 6c 65 61 64 20 6f 66 20 74 68 65 20 63 6f e lead of the co
34790 72 65 2e 20 20 7b 48 31 37 30 38 32 7d 20 54 68 re. {H17082} Th
347a0 65 20 63 6f 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70 e core only.** p
347b0 72 6f 76 69 64 65 73 20 69 6d 70 6c 65 6d 65 6e rovides implemen
347c0 74 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 73 tations for thes
347d0 65 20 72 6f 75 74 69 6e 65 73 20 77 68 65 6e 20 e routines when
347e0 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a it is compiled.*
347f0 2a 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 * with the SQLIT
34800 45 5f 44 45 42 55 47 20 66 6c 61 67 2e 20 20 7b E_DEBUG flag. {
34810 41 31 37 30 38 37 7d 20 45 78 74 65 72 6e 61 6c A17087} External
34820 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 mutex implement
34830 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 6f 6e ations.** are on
34840 6c 79 20 72 65 71 75 69 72 65 64 20 74 6f 20 70 ly required to p
34850 72 6f 76 69 64 65 20 74 68 65 73 65 20 72 6f 75 rovide these rou
34860 74 69 6e 65 73 20 69 66 20 53 51 4c 49 54 45 5f tines if SQLITE_
34870 44 45 42 55 47 20 69 73 0a 2a 2a 20 64 65 66 69 DEBUG is.** defi
34880 6e 65 64 20 61 6e 64 20 69 66 20 4e 44 45 42 55 ned and if NDEBU
34890 47 20 69 73 20 6e 6f 74 20 64 65 66 69 6e 65 64 G is not defined
348a0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 38 33 7d ..**.** {H17083}
348b0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
348c0 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 72 should return tr
348d0 75 65 20 69 66 20 74 68 65 20 6d 75 74 65 78 20 ue if the mutex
348e0 69 6e 20 74 68 65 69 72 20 61 72 67 75 6d 65 6e in their argumen
348f0 74 0a 2a 2a 20 69 73 20 68 65 6c 64 20 6f 72 20 t.** is held or
34900 6e 6f 74 20 68 65 6c 64 2c 20 72 65 73 70 65 63 not held, respec
34910 74 69 76 65 6c 79 2c 20 62 79 20 74 68 65 20 63 tively, by the c
34920 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 2e 0a 2a alling thread..*
34930 2a 0a 2a 2a 20 7b 58 31 37 30 38 34 7d 20 54 68 *.** {X17084} Th
34940 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
34950 20 69 73 20 6e 6f 74 20 72 65 71 75 69 72 65 64 is not required
34960 20 74 6f 20 70 72 6f 76 69 64 65 64 20 76 65 72 to provided ver
34970 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 0a 2a sions of these.*
34980 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 * routines that
34990 61 63 74 75 61 6c 6c 79 20 77 6f 72 6b 2e 20 49 actually work. I
349a0 66 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 f the implementa
349b0 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 70 72 tion does not pr
349c0 6f 76 69 64 65 20 77 6f 72 6b 69 6e 67 0a 2a 2a ovide working.**
349d0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 versions of the
349e0 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 69 74 20 se routines, it
349f0 73 68 6f 75 6c 64 20 61 74 20 6c 65 61 73 74 20 should at least
34a00 70 72 6f 76 69 64 65 20 73 74 75 62 73 20 74 68 provide stubs th
34a10 61 74 20 61 6c 77 61 79 73 0a 2a 2a 20 72 65 74 at always.** ret
34a20 75 72 6e 20 74 72 75 65 20 73 6f 20 74 68 61 74 urn true so that
34a30 20 6f 6e 65 20 64 6f 65 73 20 6e 6f 74 20 67 65 one does not ge
34a40 74 20 73 70 75 72 69 6f 75 73 20 61 73 73 65 72 t spurious asser
34a50 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 2e 0a 2a tion failures..*
34a60 2a 0a 2a 2a 20 7b 48 31 37 30 38 35 7d 20 49 66 *.** {H17085} If
34a70 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f the argument to
34a80 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 sqlite3_mutex_h
34a90 65 6c 64 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 eld() is a NULL
34aa0 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 pointer then.**
34ab0 74 68 65 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 the routine shou
34ac0 6c 64 20 72 65 74 75 72 6e 20 31 2e 20 20 7b 45 ld return 1. {E
34ad0 4e 44 7d 20 54 68 69 73 20 73 65 65 6d 73 20 63 ND} This seems c
34ae0 6f 75 6e 74 65 72 2d 69 6e 74 75 69 74 69 76 65 ounter-intuitive
34af0 20 73 69 6e 63 65 0a 2a 2a 20 63 6c 65 61 72 6c since.** clearl
34b00 79 20 74 68 65 20 6d 75 74 65 78 20 63 61 6e 6e y the mutex cann
34b10 6f 74 20 62 65 20 68 65 6c 64 20 69 66 20 69 74 ot be held if it
34b20 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 2e does not exist.
34b30 20 20 42 75 74 20 74 68 65 0a 2a 2a 20 74 68 65 But the.** the
34b40 20 72 65 61 73 6f 6e 20 74 68 65 20 6d 75 74 65 reason the mute
34b50 78 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 x does not exist
34b60 20 69 73 20 62 65 63 61 75 73 65 20 74 68 65 20 is because the
34b70 62 75 69 6c 64 20 69 73 20 6e 6f 74 0a 2a 2a 20 build is not.**
34b80 75 73 69 6e 67 20 6d 75 74 65 78 65 73 2e 20 20 using mutexes.
34b90 41 6e 64 20 77 65 20 64 6f 20 6e 6f 74 20 77 61 And we do not wa
34ba0 6e 74 20 74 68 65 20 61 73 73 65 72 74 28 29 20 nt the assert()
34bb0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a containing the.*
34bc0 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 * call to sqlite
34bd0 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 74 3_mutex_held() t
34be0 6f 20 66 61 69 6c 2c 20 73 6f 20 61 20 6e 6f 6e o fail, so a non
34bf0 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20 69 73 0a -zero return is.
34c00 2a 2a 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 ** the appropria
34c10 74 65 20 74 68 69 6e 67 20 74 6f 20 64 6f 2e 20 te thing to do.
34c20 20 7b 48 31 37 30 38 36 7d 20 54 68 65 20 73 71 {H17086} The sq
34c30 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 lite3_mutex_noth
34c40 65 6c 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 eld().** interfa
34c50 63 65 20 73 68 6f 75 6c 64 20 61 6c 73 6f 20 72 ce should also r
34c60 65 74 75 72 6e 20 31 20 77 68 65 6e 20 67 69 76 eturn 1 when giv
34c70 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 en a NULL pointe
34c80 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 r..*/.int sqlite
34c90 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 73 71 6c 3_mutex_held(sql
34ca0 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e ite3_mutex*);.in
34cb0 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f t sqlite3_mutex_
34cc0 6e 6f 74 68 65 6c 64 28 73 71 6c 69 74 65 33 5f notheld(sqlite3_
34cd0 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 mutex*);../*.**
34ce0 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 CAPI3REF: Mutex
34cf0 54 79 70 65 73 20 7b 48 31 37 30 30 31 7d 20 3c Types {H17001} <
34d00 48 31 37 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 H17000>.**.** Th
34d10 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 e [sqlite3_mutex
34d20 5f 61 6c 6c 6f 63 28 29 5d 20 69 6e 74 65 72 66 _alloc()] interf
34d30 61 63 65 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ace takes a sing
34d40 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 le argument.** w
34d50 68 69 63 68 20 69 73 20 6f 6e 65 20 6f 66 20 74 hich is one of t
34d60 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e hese integer con
34d70 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 stants..**.** Th
34d80 65 20 73 65 74 20 6f 66 20 73 74 61 74 69 63 20 e set of static
34d90 6d 75 74 65 78 65 73 20 6d 61 79 20 63 68 61 6e mutexes may chan
34da0 67 65 20 66 72 6f 6d 20 6f 6e 65 20 53 51 4c 69 ge from one SQLi
34db0 74 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 te release to th
34dc0 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c e.** next. Appl
34dd0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6f 76 ications that ov
34de0 65 72 72 69 64 65 20 74 68 65 20 62 75 69 6c 74 erride the built
34df0 2d 69 6e 20 6d 75 74 65 78 20 6c 6f 67 69 63 20 -in mutex logic
34e00 6d 75 73 74 20 62 65 0a 2a 2a 20 70 72 65 70 61 must be.** prepa
34e10 72 65 64 20 74 6f 20 61 63 63 6f 6d 6d 6f 64 61 red to accommoda
34e20 74 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 te additional st
34e30 61 74 69 63 20 6d 75 74 65 78 65 73 2e 0a 2a 2f atic mutexes..*/
34e40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
34e50 4d 55 54 45 58 5f 46 41 53 54 20 20 20 20 20 20 MUTEX_FAST
34e60 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 0.#define
34e70 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 SQLITE_MUTEX_RE
34e80 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20 31 CURSIVE 1
34e90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
34ea0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 MUTEX_STATIC_MAS
34eb0 54 45 52 20 20 20 20 32 0a 23 64 65 66 69 6e 65 TER 2.#define
34ec0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 SQLITE_MUTEX_ST
34ed0 41 54 49 43 5f 4d 45 4d 20 20 20 20 20 20 20 33 ATIC_MEM 3
34ee0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c /* sqlite3_mal
34ef0 6c 6f 63 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 loc() */.#define
34f00 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 SQLITE_MUTEX_ST
34f10 41 54 49 43 5f 4d 45 4d 32 20 20 20 20 20 20 34 ATIC_MEM2 4
34f20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 20 2a 2f /* NOT USED */
34f30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
34f40 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4f 50 45 MUTEX_STATIC_OPE
34f50 4e 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c N 4 /* sql
34f60 69 74 65 33 42 74 72 65 65 4f 70 65 6e 28 29 20 ite3BtreeOpen()
34f70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
34f80 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50 E_MUTEX_STATIC_P
34f90 52 4e 47 20 20 20 20 20 20 35 20 20 2f 2a 20 73 RNG 5 /* s
34fa0 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 28 29 20 qlite3_random()
34fb0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
34fc0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c E_MUTEX_STATIC_L
34fd0 52 55 20 20 20 20 20 20 20 36 20 20 2f 2a 20 6c RU 6 /* l
34fe0 72 75 20 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a ru page list */.
34ff0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d #define SQLITE_M
35000 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 32 UTEX_STATIC_LRU2
35010 20 20 20 20 20 20 37 20 20 2f 2a 20 6c 72 75 20 7 /* lru
35020 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a 0a 2f 2a page list */../*
35030 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
35040 74 72 69 65 76 65 20 74 68 65 20 6d 75 74 65 78 trieve the mutex
35050 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 for a database
35060 63 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 37 30 connection {H170
35070 30 32 7d 20 3c 48 31 37 30 30 30 3e 0a 2a 2a 0a 02} <H17000>.**.
35080 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 ** This interfac
35090 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e e returns a poin
350a0 74 65 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 ter the [sqlite3
350b0 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 20 74 _mutex] object t
350c0 68 61 74 20 0a 2a 2a 20 73 65 72 69 61 6c 69 7a hat .** serializ
350d0 65 73 20 61 63 63 65 73 73 20 74 6f 20 74 68 65 es access to the
350e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
350f0 63 74 69 6f 6e 5d 20 67 69 76 65 6e 20 69 6e 20 ction] given in
35100 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 the argument.**
35110 77 68 65 6e 20 74 68 65 20 5b 74 68 72 65 61 64 when the [thread
35120 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 53 65 72 ing mode] is Ser
35130 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 49 66 20 74 ialized..** If t
35140 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f he [threading mo
35150 64 65 5d 20 69 73 20 53 69 6e 67 6c 65 2d 74 68 de] is Single-th
35160 72 65 61 64 20 6f 72 20 4d 75 6c 74 69 2d 74 68 read or Multi-th
35170 72 65 61 64 20 74 68 65 6e 20 74 68 69 73 0a 2a read then this.*
35180 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e * routine return
35190 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
351a0 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 ..*/.sqlite3_mut
351b0 65 78 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 6d ex *sqlite3_db_m
351c0 75 74 65 78 28 73 71 6c 69 74 65 33 2a 29 3b 0a utex(sqlite3*);.
351d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
351e0 20 4c 6f 77 2d 4c 65 76 65 6c 20 43 6f 6e 74 72 Low-Level Contr
351f0 6f 6c 20 4f 66 20 44 61 74 61 62 61 73 65 20 46 ol Of Database F
35200 69 6c 65 73 20 7b 48 31 31 33 30 30 7d 20 3c 53 iles {H11300} <S
35210 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30800>.**.** {H1
35220 31 33 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 1301} The [sqlit
35230 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
35240 29 5d 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b )] interface mak
35250 65 73 20 61 20 64 69 72 65 63 74 20 63 61 6c 6c es a direct call
35260 20 74 6f 20 74 68 65 0a 2a 2a 20 78 46 69 6c 65 to the.** xFile
35270 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 66 Control method f
35280 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f or the [sqlite3_
35290 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 io_methods] obje
352a0 63 74 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a ct associated.**
352b0 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c with a particul
352c0 61 72 20 64 61 74 61 62 61 73 65 20 69 64 65 6e ar database iden
352d0 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65 tified by the se
352e0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 20 7b cond argument. {
352f0 48 31 31 33 30 32 7d 20 54 68 65 0a 2a 2a 20 6e H11302} The.** n
35300 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 ame of the datab
35310 61 73 65 20 69 73 20 74 68 65 20 6e 61 6d 65 20 ase is the name
35320 61 73 73 69 67 6e 65 64 20 74 6f 20 74 68 65 20 assigned to the
35330 64 61 74 61 62 61 73 65 20 62 79 20 74 68 65 0a database by the.
35340 2a 2a 20 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67 ** <a href="lang
35350 5f 61 74 74 61 63 68 2e 68 74 6d 6c 22 3e 41 54 _attach.html">AT
35360 54 41 43 48 3c 2f 61 3e 20 53 51 4c 20 63 6f 6d TACH</a> SQL com
35370 6d 61 6e 64 20 74 68 61 74 20 6f 70 65 6e 65 64 mand that opened
35380 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 the.** database
35390 2e 20 7b 48 31 31 33 30 33 7d 20 54 6f 20 63 6f . {H11303} To co
353a0 6e 74 72 6f 6c 20 74 68 65 20 6d 61 69 6e 20 64 ntrol the main d
353b0 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 75 73 atabase file, us
353c0 65 20 74 68 65 20 6e 61 6d 65 20 22 6d 61 69 6e e the name "main
353d0 22 0a 2a 2a 20 6f 72 20 61 20 4e 55 4c 4c 20 70 ".** or a NULL p
353e0 6f 69 6e 74 65 72 2e 20 7b 48 31 31 33 30 34 7d ointer. {H11304}
353f0 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 The third and f
35400 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 ourth parameters
35410 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 to this routine
35420 0a 2a 2a 20 61 72 65 20 70 61 73 73 65 64 20 64 .** are passed d
35430 69 72 65 63 74 6c 79 20 74 68 72 6f 75 67 68 20 irectly through
35440 74 6f 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e to the second an
35450 64 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 d third paramete
35460 72 73 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46 69 rs of.** the xFi
35470 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 leControl method
35480 2e 20 20 7b 48 31 31 33 30 35 7d 20 54 68 65 20 . {H11305} The
35490 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 return value of
354a0 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c the xFileControl
354b0 0a 2a 2a 20 6d 65 74 68 6f 64 20 62 65 63 6f 6d .** method becom
354c0 65 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 es the return va
354d0 6c 75 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 lue of this rout
354e0 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 ine..**.** {H113
354f0 30 36 7d 20 49 66 20 74 68 65 20 73 65 63 6f 6e 06} If the secon
35500 64 20 70 61 72 61 6d 65 74 65 72 20 28 7a 44 62 d parameter (zDb
35510 4e 61 6d 65 29 20 64 6f 65 73 20 6e 6f 74 20 6d Name) does not m
35520 61 74 63 68 20 74 68 65 20 6e 61 6d 65 20 6f 66 atch the name of
35530 20 61 6e 79 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 any.** open dat
35540 61 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65 6e abase file, then
35550 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 69 73 SQLITE_ERROR is
35560 20 72 65 74 75 72 6e 65 64 2e 20 7b 48 31 31 33 returned. {H113
35570 30 37 7d 20 54 68 69 73 20 65 72 72 6f 72 0a 2a 07} This error.*
35580 2a 20 63 6f 64 65 20 69 73 20 6e 6f 74 20 72 65 * code is not re
35590 6d 65 6d 62 65 72 65 64 20 61 6e 64 20 77 69 6c membered and wil
355a0 6c 20 6e 6f 74 20 62 65 20 72 65 63 61 6c 6c 65 l not be recalle
355b0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 d by [sqlite3_er
355c0 72 63 6f 64 65 28 29 5d 0a 2a 2a 20 6f 72 20 5b rcode()].** or [
355d0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 sqlite3_errmsg()
355e0 5d 2e 20 7b 41 31 31 33 30 38 7d 20 54 68 65 20 ]. {A11308} The
355f0 75 6e 64 65 72 6c 79 69 6e 67 20 78 46 69 6c 65 underlying xFile
35600 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 6d Control method m
35610 69 67 68 74 0a 2a 2a 20 61 6c 73 6f 20 72 65 74 ight.** also ret
35620 75 72 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 urn SQLITE_ERROR
35630 2e 20 20 7b 41 31 31 33 30 39 7d 20 54 68 65 72 . {A11309} Ther
35640 65 20 69 73 20 6e 6f 20 77 61 79 20 74 6f 20 64 e is no way to d
35650 69 73 74 69 6e 67 75 69 73 68 20 62 65 74 77 65 istinguish betwe
35660 65 6e 0a 2a 2a 20 61 6e 20 69 6e 63 6f 72 72 65 en.** an incorre
35670 63 74 20 7a 44 62 4e 61 6d 65 20 61 6e 64 20 61 ct zDbName and a
35680 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 72 n SQLITE_ERROR r
35690 65 74 75 72 6e 20 66 72 6f 6d 20 74 68 65 20 75 eturn from the u
356a0 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 78 46 69 nderlying.** xFi
356b0 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 leControl method
356c0 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 53 65 . {END}.**.** Se
356d0 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f e also: [SQLITE_
356e0 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d FCNTL_LOCKSTATE]
356f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
35700 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 73 71 6c file_control(sql
35710 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 ite3*, const cha
35720 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 69 6e 74 20 r *zDbName, int
35730 6f 70 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a op, void*);../*.
35740 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 ** CAPI3REF: Tes
35750 74 69 6e 67 20 49 6e 74 65 72 66 61 63 65 20 7b ting Interface {
35760 48 31 31 34 30 30 7d 20 3c 53 33 30 38 30 30 3e H11400} <S30800>
35770 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
35780 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 e3_test_control(
35790 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 ) interface is u
357a0 73 65 64 20 74 6f 20 72 65 61 64 20 6f 75 74 20 sed to read out
357b0 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 73 74 61 74 internal.** stat
357c0 65 20 6f 66 20 53 51 4c 69 74 65 20 61 6e 64 20 e of SQLite and
357d0 74 6f 20 69 6e 6a 65 63 74 20 66 61 75 6c 74 73 to inject faults
357e0 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 66 6f 72 into SQLite for
357f0 20 74 65 73 74 69 6e 67 0a 2a 2a 20 70 75 72 70 testing.** purp
35800 6f 73 65 73 2e 20 20 54 68 65 20 66 69 72 73 74 oses. The first
35810 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e parameter is an
35820 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 65 20 operation code
35830 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a that determines.
35840 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 2c 20 6d ** the number, m
35850 65 61 6e 69 6e 67 2c 20 61 6e 64 20 6f 70 65 72 eaning, and oper
35860 61 74 69 6f 6e 20 6f 66 20 61 6c 6c 20 73 75 62 ation of all sub
35870 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65 sequent paramete
35880 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 rs..**.** This i
35890 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 nterface is not
358a0 66 6f 72 20 75 73 65 20 62 79 20 61 70 70 6c 69 for use by appli
358b0 63 61 74 69 6f 6e 73 2e 20 20 49 74 20 65 78 69 cations. It exi
358c0 73 74 73 20 73 6f 6c 65 6c 79 0a 2a 2a 20 66 6f sts solely.** fo
358d0 72 20 76 65 72 69 66 79 69 6e 67 20 74 68 65 20 r verifying the
358e0 63 6f 72 72 65 63 74 20 6f 70 65 72 61 74 69 6f correct operatio
358f0 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 n of the SQLite
35900 6c 69 62 72 61 72 79 2e 20 20 44 65 70 65 6e 64 library. Depend
35910 69 6e 67 0a 2a 2a 20 6f 6e 20 68 6f 77 20 74 68 ing.** on how th
35920 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 e SQLite library
35930 20 69 73 20 63 6f 6d 70 69 6c 65 64 2c 20 74 68 is compiled, th
35940 69 73 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 is interface mig
35950 68 74 20 6e 6f 74 20 65 78 69 73 74 2e 0a 2a 2a ht not exist..**
35960 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 .** The details
35970 6f 66 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e of the operation
35980 20 63 6f 64 65 73 2c 20 74 68 65 69 72 20 6d 65 codes, their me
35990 61 6e 69 6e 67 73 2c 20 74 68 65 20 70 61 72 61 anings, the para
359a0 6d 65 74 65 72 73 0a 2a 2a 20 74 68 65 79 20 74 meters.** they t
359b0 61 6b 65 2c 20 61 6e 64 20 77 68 61 74 20 74 68 ake, and what th
359c0 65 79 20 64 6f 20 61 72 65 20 61 6c 6c 20 73 75 ey do are all su
359d0 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 bject to change
359e0 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 2e 0a without notice..
359f0 2a 2a 20 55 6e 6c 69 6b 65 20 6d 6f 73 74 20 6f ** Unlike most o
35a00 66 20 74 68 65 20 53 51 4c 69 74 65 20 41 50 49 f the SQLite API
35a10 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 , this function
35a20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 is not guarantee
35a30 64 20 74 6f 0a 2a 2a 20 6f 70 65 72 61 74 65 20 d to.** operate
35a40 63 6f 6e 73 69 73 74 65 6e 74 6c 79 20 66 72 6f consistently fro
35a50 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f m one release to
35a60 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 69 6e the next..*/.in
35a70 74 20 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 t sqlite3_test_c
35a80 6f 6e 74 72 6f 6c 28 69 6e 74 20 6f 70 2c 20 2e ontrol(int op, .
35a90 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ..);../*.** CAPI
35aa0 33 52 45 46 3a 20 54 65 73 74 69 6e 67 20 49 6e 3REF: Testing In
35ab0 74 65 72 66 61 63 65 20 4f 70 65 72 61 74 69 6f terface Operatio
35ac0 6e 20 43 6f 64 65 73 20 7b 48 31 31 34 31 30 7d n Codes {H11410}
35ad0 20 3c 48 31 31 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 <H11400>.**.**
35ae0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 These constants
35af0 61 72 65 20 74 68 65 20 76 61 6c 69 64 20 6f 70 are the valid op
35b00 65 72 61 74 69 6f 6e 20 63 6f 64 65 20 70 61 72 eration code par
35b10 61 6d 65 74 65 72 73 20 75 73 65 64 0a 2a 2a 20 ameters used.**
35b20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 as the first arg
35b30 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 ument to [sqlite
35b40 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 3_test_control()
35b50 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 70 ]..**.** These p
35b60 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 74 68 arameters and th
35b70 65 69 72 20 6d 65 61 6e 69 6e 67 73 20 61 72 65 eir meanings are
35b80 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e subject to chan
35b90 67 65 0a 2a 2a 20 77 69 74 68 6f 75 74 20 6e 6f ge.** without no
35ba0 74 69 63 65 2e 20 20 54 68 65 73 65 20 76 61 6c tice. These val
35bb0 75 65 73 20 61 72 65 20 66 6f 72 20 74 65 73 74 ues are for test
35bc0 69 6e 67 20 70 75 72 70 6f 73 65 73 20 6f 6e 6c ing purposes onl
35bd0 79 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f y..** Applicatio
35be0 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 ns should not us
35bf0 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 70 e any of these p
35c00 61 72 61 6d 65 74 65 72 73 20 6f 72 20 74 68 65 arameters or the
35c10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 65 73 .** [sqlite3_tes
35c20 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 t_control()] int
35c30 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 erface..*/.#defi
35c40 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 ne SQLITE_TESTCT
35c50 52 4c 5f 50 52 4e 47 5f 53 41 56 45 20 20 20 20 RL_PRNG_SAVE
35c60 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 5.#d
35c70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 efine SQLITE_TES
35c80 54 43 54 52 4c 5f 50 52 4e 47 5f 52 45 53 54 4f TCTRL_PRNG_RESTO
35c90 52 45 20 20 20 20 20 20 20 20 20 20 20 20 20 36 RE 6
35ca0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
35cb0 54 45 53 54 43 54 52 4c 5f 50 52 4e 47 5f 52 45 TESTCTRL_PRNG_RE
35cc0 53 45 54 20 20 20 20 20 20 20 20 20 20 20 20 20 SET
35cd0 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 7.#define SQLI
35ce0 54 45 5f 54 45 53 54 43 54 52 4c 5f 42 49 54 56 TE_TESTCTRL_BITV
35cf0 45 43 5f 54 45 53 54 20 20 20 20 20 20 20 20 20 EC_TEST
35d00 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 8.#define S
35d10 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 46 QLITE_TESTCTRL_F
35d20 41 55 4c 54 5f 49 4e 53 54 41 4c 4c 20 20 20 20 AULT_INSTALL
35d30 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 9.#defin
35d40 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 e SQLITE_TESTCTR
35d50 4c 5f 42 45 4e 49 47 4e 5f 4d 41 4c 4c 4f 43 5f L_BENIGN_MALLOC_
35d60 48 4f 4f 4b 53 20 20 20 20 20 31 30 0a 23 64 65 HOOKS 10.#de
35d70 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 fine SQLITE_TEST
35d80 43 54 52 4c 5f 50 45 4e 44 49 4e 47 5f 42 59 54 CTRL_PENDING_BYT
35d90 45 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a E 11.
35da0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
35db0 20 53 51 4c 69 74 65 20 52 75 6e 74 69 6d 65 20 SQLite Runtime
35dc0 53 74 61 74 75 73 20 7b 48 31 37 32 30 30 7d 20 Status {H17200}
35dd0 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 <S60200>.** EXPE
35de0 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 RIMENTAL.**.** T
35df0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 his interface is
35e00 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 used to retriev
35e10 65 20 72 75 6e 74 69 6d 65 20 73 74 61 74 75 73 e runtime status
35e20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 information.**
35e30 61 62 6f 75 74 20 74 68 65 20 70 72 65 66 6f 72 about the prefor
35e40 6d 61 6e 63 65 20 6f 66 20 53 51 4c 69 74 65 2c mance of SQLite,
35e50 20 61 6e 64 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 and optionally
35e60 74 6f 20 72 65 73 65 74 20 76 61 72 69 6f 75 73 to reset various
35e70 0a 2a 2a 20 68 69 67 68 77 61 74 65 72 20 6d 61 .** highwater ma
35e80 72 6b 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 rks. The first
35e90 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 argument is an i
35ea0 6e 74 65 67 65 72 20 63 6f 64 65 20 66 6f 72 0a nteger code for.
35eb0 2a 2a 20 74 68 65 20 73 70 65 63 69 66 69 63 20 ** the specific
35ec0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 6d 65 61 parameter to mea
35ed0 73 75 72 65 2e 20 20 52 65 63 6f 67 6e 69 7a 65 sure. Recognize
35ee0 64 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 0a d integer codes.
35ef0 2a 2a 20 61 72 65 20 6f 66 20 74 68 65 20 66 6f ** are of the fo
35f00 72 6d 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 55 rm [SQLITE_STATU
35f10 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 20 7c 20 S_MEMORY_USED |
35f20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 2e 2e SQLITE_STATUS_..
35f30 2e 5d 2e 0a 2a 2a 20 54 68 65 20 63 75 72 72 65 .]..** The curre
35f40 6e 74 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 nt value of the
35f50 70 61 72 61 6d 65 74 65 72 20 69 73 20 72 65 74 parameter is ret
35f60 75 72 6e 65 64 20 69 6e 74 6f 20 2a 70 43 75 72 urned into *pCur
35f70 72 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 68 69 67 rent..** The hig
35f80 68 65 73 74 20 72 65 63 6f 72 64 65 64 20 76 61 hest recorded va
35f90 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 lue is returned
35fa0 69 6e 20 2a 70 48 69 67 68 77 61 74 65 72 2e 20 in *pHighwater.
35fb0 20 49 66 20 74 68 65 0a 2a 2a 20 72 65 73 65 74 If the.** reset
35fc0 46 6c 61 67 20 69 73 20 74 72 75 65 2c 20 74 68 Flag is true, th
35fd0 65 6e 20 74 68 65 20 68 69 67 68 65 73 74 20 72 en the highest r
35fe0 65 63 6f 72 64 20 76 61 6c 75 65 20 69 73 20 72 ecord value is r
35ff0 65 73 65 74 20 61 66 74 65 72 0a 2a 2a 20 2a 70 eset after.** *p
36000 48 69 67 68 77 61 74 65 72 20 69 73 20 77 72 69 Highwater is wri
36010 74 74 65 6e 2e 20 53 6f 6d 65 20 70 61 72 61 6d tten. Some param
36020 65 74 65 72 73 20 64 6f 20 6e 6f 74 20 72 65 63 eters do not rec
36030 6f 72 64 20 74 68 65 20 68 69 67 68 65 73 74 0a ord the highest.
36040 2a 2a 20 76 61 6c 75 65 2e 20 20 46 6f 72 20 74 ** value. For t
36050 68 6f 73 65 20 70 61 72 61 6d 65 74 65 72 73 0a hose parameters.
36060 2a 2a 20 6e 6f 74 68 69 6e 67 20 69 73 20 77 72 ** nothing is wr
36070 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 48 69 67 itten into *pHig
36080 68 77 61 74 65 72 20 61 6e 64 20 74 68 65 20 72 hwater and the r
36090 65 73 65 74 46 6c 61 67 20 69 73 20 69 67 6e 6f esetFlag is igno
360a0 72 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 20 70 61 red..** Other pa
360b0 72 61 6d 65 74 65 72 73 20 72 65 63 6f 72 64 20 rameters record
360c0 6f 6e 6c 79 20 74 68 65 20 68 69 67 68 77 61 74 only the highwat
360d0 65 72 20 6d 61 72 6b 20 61 6e 64 20 6e 6f 74 20 er mark and not
360e0 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 76 the current.** v
360f0 61 6c 75 65 2e 20 20 46 6f 72 20 74 68 65 73 65 alue. For these
36100 20 6c 61 74 74 65 72 20 70 61 72 61 6d 65 74 65 latter paramete
36110 72 73 20 6e 6f 74 68 69 6e 67 20 69 73 20 77 72 rs nothing is wr
36120 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 43 75 72 itten into *pCur
36130 72 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 rent..**.** This
36140 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
36150 20 53 51 4c 49 54 45 5f 4f 4b 20 6f 6e 20 73 75 SQLITE_OK on su
36160 63 63 65 73 73 20 61 6e 64 20 61 20 6e 6f 6e 2d ccess and a non-
36170 7a 65 72 6f 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 zero.** [error c
36180 6f 64 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e ode] on failure.
36190 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
361a0 69 6e 65 20 69 73 20 74 68 72 65 61 64 73 61 66 ine is threadsaf
361b0 65 20 62 75 74 20 69 73 20 6e 6f 74 20 61 74 6f e but is not ato
361c0 6d 69 63 2e 20 20 54 68 69 73 20 72 6f 75 74 69 mic. This routi
361d0 6e 65 20 63 61 6e 0a 2a 2a 20 63 61 6c 6c 65 64 ne can.** called
361e0 20 77 68 69 6c 65 20 6f 74 68 65 72 20 74 68 72 while other thr
361f0 65 61 64 73 20 61 72 65 20 72 75 6e 6e 69 6e 67 eads are running
36200 20 74 68 65 20 73 61 6d 65 20 6f 72 20 64 69 66 the same or dif
36210 66 65 72 65 6e 74 20 53 51 4c 69 74 65 0a 2a 2a ferent SQLite.**
36220 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f interfaces. Ho
36230 77 65 76 65 72 20 74 68 65 20 76 61 6c 75 65 73 wever the values
36240 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 43 returned in *pC
36250 75 72 72 65 6e 74 20 61 6e 64 0a 2a 2a 20 2a 70 urrent and.** *p
36260 48 69 67 68 77 61 74 65 72 20 72 65 66 6c 65 63 Highwater reflec
36270 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 t the status of
36280 53 51 4c 69 74 65 20 61 74 20 64 69 66 66 65 72 SQLite at differ
36290 65 6e 74 20 70 6f 69 6e 74 73 20 69 6e 20 74 69 ent points in ti
362a0 6d 65 0a 2a 2a 20 61 6e 64 20 69 74 20 69 73 20 me.** and it is
362b0 70 6f 73 73 69 62 6c 65 20 74 68 61 74 20 61 6e possible that an
362c0 6f 74 68 65 72 20 74 68 72 65 61 64 20 6d 69 67 other thread mig
362d0 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 70 61 ht change the pa
362e0 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 20 62 65 rameter.** in be
362f0 74 77 65 65 6e 20 74 68 65 20 74 69 6d 65 73 20 tween the times
36300 77 68 65 6e 20 2a 70 43 75 72 72 65 6e 74 20 61 when *pCurrent a
36310 6e 64 20 2a 70 48 69 67 68 77 61 74 65 72 20 61 nd *pHighwater a
36320 72 65 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a re written..**.*
36330 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
36340 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 28 29 ite3_db_status()
36350 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 ].*/.SQLITE_EXPE
36360 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c RIMENTAL int sql
36370 69 74 65 33 5f 73 74 61 74 75 73 28 69 6e 74 20 ite3_status(int
36380 6f 70 2c 20 69 6e 74 20 2a 70 43 75 72 72 65 6e op, int *pCurren
36390 74 2c 20 69 6e 74 20 2a 70 48 69 67 68 77 61 74 t, int *pHighwat
363a0 65 72 2c 20 69 6e 74 20 72 65 73 65 74 46 6c 61 er, int resetFla
363b0 67 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 g);.../*.** CAPI
363c0 33 52 45 46 3a 20 53 74 61 74 75 73 20 50 61 72 3REF: Status Par
363d0 61 6d 65 74 65 72 73 20 7b 48 31 37 32 35 30 7d ameters {H17250}
363e0 20 3c 48 31 37 32 30 30 3e 0a 2a 2a 20 45 58 50 <H17200>.** EXP
363f0 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 ERIMENTAL.**.**
36400 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f These integer co
36410 6e 73 74 61 6e 74 73 20 64 65 73 69 67 6e 61 74 nstants designat
36420 65 20 76 61 72 69 6f 75 73 20 72 75 6e 2d 74 69 e various run-ti
36430 6d 65 20 73 74 61 74 75 73 20 70 61 72 61 6d 65 me status parame
36440 74 65 72 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e ters.** that can
36450 20 62 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 be returned by
36460 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 [sqlite3_status(
36470 29 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a )]..**.** <dl>.*
36480 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 * <dt>SQLITE_STA
36490 54 55 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 3c TUS_MEMORY_USED<
364a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 /dt>.** <dd>This
364b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
364c0 65 20 63 75 72 72 65 6e 74 20 61 6d 6f 75 6e 74 e current amount
364d0 20 6f 66 20 6d 65 6d 6f 72 79 20 63 68 65 63 6b of memory check
364e0 65 64 20 6f 75 74 0a 2a 2a 20 75 73 69 6e 67 20 ed out.** using
364f0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
36500 29 5d 2c 20 65 69 74 68 65 72 20 64 69 72 65 63 )], either direc
36510 74 6c 79 20 6f 72 20 69 6e 64 69 72 65 63 74 6c tly or indirectl
36520 79 2e 20 20 54 68 65 0a 2a 2a 20 66 69 67 75 72 y. The.** figur
36530 65 20 69 6e 63 6c 75 64 65 73 20 63 61 6c 6c 73 e includes calls
36540 20 6d 61 64 65 20 74 6f 20 5b 73 71 6c 69 74 65 made to [sqlite
36550 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 79 20 74 3_malloc()] by t
36560 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a he application.*
36570 2a 20 61 6e 64 20 69 6e 74 65 72 6e 61 6c 20 6d * and internal m
36580 65 6d 6f 72 79 20 75 73 61 67 65 20 62 79 20 74 emory usage by t
36590 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 he SQLite librar
365a0 79 2e 20 20 53 63 72 61 74 63 68 20 6d 65 6d 6f y. Scratch memo
365b0 72 79 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 6c 65 64 ry.** controlled
365c0 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 by [SQLITE_CONF
365d0 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 IG_SCRATCH] and
365e0 61 75 78 69 6c 69 61 72 79 20 70 61 67 65 2d 63 auxiliary page-c
365f0 61 63 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 63 ache.** memory c
36600 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 5b 53 51 ontrolled by [SQ
36610 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 LITE_CONFIG_PAGE
36620 43 41 43 48 45 5d 20 69 73 20 6e 6f 74 20 69 6e CACHE] is not in
36630 63 6c 75 64 65 64 20 69 6e 0a 2a 2a 20 74 68 69 cluded in.** thi
36640 73 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 s parameter. Th
36650 65 20 61 6d 6f 75 6e 74 20 72 65 74 75 72 6e 65 e amount returne
36660 64 20 69 73 20 74 68 65 20 73 75 6d 20 6f 66 20 d is the sum of
36670 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a the allocation.*
36680 2a 20 73 69 7a 65 73 20 61 73 20 72 65 70 6f 72 * sizes as repor
36690 74 65 64 20 62 79 20 74 68 65 20 78 53 69 7a 65 ted by the xSize
366a0 20 6d 65 74 68 6f 64 20 69 6e 20 5b 73 71 6c 69 method in [sqli
366b0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d te3_mem_methods]
366c0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
366d0 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d >SQLITE_STATUS_M
366e0 41 4c 4c 4f 43 5f 53 49 5a 45 3c 2f 64 74 3e 0a ALLOC_SIZE</dt>.
366f0 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 ** <dd>This para
36700 6d 65 74 65 72 20 72 65 63 6f 72 64 73 20 74 68 meter records th
36710 65 20 6c 61 72 67 65 73 74 20 6d 65 6d 6f 72 79 e largest memory
36720 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 allocation requ
36730 65 73 74 0a 2a 2a 20 68 61 6e 64 65 64 20 74 6f est.** handed to
36740 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
36750 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
36760 72 65 61 6c 6c 6f 63 28 29 5d 20 28 6f 72 20 74 realloc()] (or t
36770 68 65 69 72 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c heir.** internal
36780 20 65 71 75 69 76 61 6c 65 6e 74 73 29 2e 20 20 equivalents).
36790 4f 6e 6c 79 20 74 68 65 20 76 61 6c 75 65 20 72 Only the value r
367a0 65 74 75 72 6e 65 64 20 69 6e 20 74 68 65 0a 2a eturned in the.*
367b0 2a 20 2a 70 48 69 67 68 77 61 74 65 72 20 70 61 * *pHighwater pa
367c0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
367d0 74 65 33 5f 73 74 61 74 75 73 28 29 5d 20 69 73 te3_status()] is
367e0 20 6f 66 20 69 6e 74 65 72 65 73 74 2e 20 20 0a of interest. .
367f0 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 77 72 69 ** The value wri
36800 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 2a 70 tten into the *p
36810 43 75 72 72 65 6e 74 20 70 61 72 61 6d 65 74 65 Current paramete
36820 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 3c r is undefined.<
36830 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
36840 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 QLITE_STATUS_PAG
36850 45 43 41 43 48 45 5f 55 53 45 44 3c 2f 64 74 3e ECACHE_USED</dt>
36860 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 .** <dd>This par
36870 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20 74 ameter returns t
36880 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 he number of pag
36890 65 73 20 75 73 65 64 20 6f 75 74 20 6f 66 20 74 es used out of t
368a0 68 65 0a 2a 2a 20 5b 70 61 67 65 63 61 63 68 65 he.** [pagecache
368b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
368c0 72 5d 20 74 68 61 74 20 77 61 73 20 63 6f 6e 66 r] that was conf
368d0 69 67 75 72 65 64 20 75 73 69 6e 67 20 0a 2a 2a igured using .**
368e0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
368f0 50 41 47 45 43 41 43 48 45 5d 2e 20 20 54 68 65 PAGECACHE]. The
36900 0a 2a 2a 20 76 61 6c 75 65 20 72 65 74 75 72 6e .** value return
36910 65 64 20 69 73 20 69 6e 20 70 61 67 65 73 2c 20 ed is in pages,
36920 6e 6f 74 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 not in bytes.</d
36930 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
36940 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45 43 ITE_STATUS_PAGEC
36950 41 43 48 45 5f 4f 56 45 52 46 4c 4f 57 3c 2f 64 ACHE_OVERFLOW</d
36960 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 t>.** <dd>This p
36970 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 arameter returns
36980 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
36990 79 74 65 73 20 6f 66 20 70 61 67 65 20 63 61 63 ytes of page cac
369a0 68 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e he.** allocation
369b0 20 77 68 69 63 68 20 63 6f 75 6c 64 20 6e 6f 74 which could not
369c0 20 62 65 20 73 74 61 74 69 73 66 69 65 64 20 62 be statisfied b
369d0 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f y the [SQLITE_CO
369e0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 0a NFIG_PAGECACHE].
369f0 2a 2a 20 62 75 66 66 65 72 20 61 6e 64 20 77 68 ** buffer and wh
36a00 65 72 65 20 66 6f 72 63 65 64 20 74 6f 20 6f 76 ere forced to ov
36a10 65 72 66 6c 6f 77 20 74 6f 20 5b 73 71 6c 69 74 erflow to [sqlit
36a20 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 e3_malloc()]. T
36a30 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 76 he.** returned v
36a40 61 6c 75 65 20 69 6e 63 6c 75 64 65 73 20 61 6c alue includes al
36a50 6c 6f 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6f locations that o
36a60 76 65 72 66 6c 6f 77 65 64 20 62 65 63 61 75 73 verflowed becaus
36a70 65 20 74 68 65 79 0a 2a 2a 20 77 68 65 72 65 20 e they.** where
36a80 74 6f 6f 20 6c 61 72 67 65 20 28 74 68 65 79 20 too large (they
36a90 77 65 72 65 20 6c 61 72 67 65 72 20 74 68 61 6e were larger than
36aa0 20 74 68 65 20 22 73 7a 22 20 70 61 72 61 6d 65 the "sz" parame
36ab0 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 ter to.** [SQLIT
36ac0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 E_CONFIG_PAGECAC
36ad0 48 45 5d 29 20 61 6e 64 20 61 6c 6c 6f 63 61 74 HE]) and allocat
36ae0 69 6f 6e 73 20 74 68 61 74 20 6f 76 65 72 66 6c ions that overfl
36af0 6f 77 65 64 20 62 65 63 61 75 73 65 0a 2a 2a 20 owed because.**
36b00 6e 6f 20 73 70 61 63 65 20 77 61 73 20 6c 65 66 no space was lef
36b10 74 20 69 6e 20 74 68 65 20 70 61 67 65 20 63 61 t in the page ca
36b20 63 68 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 che.</dd>.**.**
36b30 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 <dt>SQLITE_STATU
36b40 53 5f 50 41 47 45 43 41 43 48 45 5f 53 49 5a 45 S_PAGECACHE_SIZE
36b50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 </dt>.** <dd>Thi
36b60 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 63 6f s parameter reco
36b70 72 64 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 rds the largest
36b80 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
36b90 6e 20 72 65 71 75 65 73 74 0a 2a 2a 20 68 61 6e n request.** han
36ba0 64 65 64 20 74 6f 20 5b 70 61 67 65 63 61 63 68 ded to [pagecach
36bb0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
36bc0 6f 72 5d 2e 20 20 4f 6e 6c 79 20 74 68 65 20 76 or]. Only the v
36bd0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 6e alue returned in
36be0 20 74 68 65 0a 2a 2a 20 2a 70 48 69 67 68 77 61 the.** *pHighwa
36bf0 74 65 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f ter parameter to
36c00 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 [sqlite3_status
36c10 28 29 5d 20 69 73 20 6f 66 20 69 6e 74 65 72 65 ()] is of intere
36c20 73 74 2e 20 20 0a 2a 2a 20 54 68 65 20 76 61 6c st. .** The val
36c30 75 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 ue written into
36c40 74 68 65 20 2a 70 43 75 72 72 65 6e 74 20 70 61 the *pCurrent pa
36c50 72 61 6d 65 74 65 72 20 69 73 20 75 6e 64 65 66 rameter is undef
36c60 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ined.</dd>.**.**
36c70 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 <dt>SQLITE_STAT
36c80 55 53 5f 53 43 52 41 54 43 48 5f 55 53 45 44 3c US_SCRATCH_USED<
36c90 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 /dt>.** <dd>This
36ca0 20 70 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 parameter retur
36cb0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
36cc0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 75 73 65 allocations use
36cd0 64 20 6f 75 74 20 6f 66 20 74 68 65 0a 2a 2a 20 d out of the.**
36ce0 5b 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 [scratch memory
36cf0 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 allocator] confi
36d00 67 75 72 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b gured using.** [
36d10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 SQLITE_CONFIG_SC
36d20 52 41 54 43 48 5d 2e 20 20 54 68 65 20 76 61 6c RATCH]. The val
36d30 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 69 ue returned is i
36d40 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c 20 6e n allocations, n
36d50 6f 74 0a 2a 2a 20 69 6e 20 62 79 74 65 73 2e 20 ot.** in bytes.
36d60 20 53 69 6e 63 65 20 61 20 73 69 6e 67 6c 65 20 Since a single
36d70 74 68 72 65 61 64 20 6d 61 79 20 6f 6e 6c 79 20 thread may only
36d80 68 61 76 65 20 6f 6e 65 20 73 63 72 61 74 63 68 have one scratch
36d90 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f allocation.** o
36da0 75 74 73 74 61 6e 64 69 6e 67 20 61 74 20 74 69 utstanding at ti
36db0 6d 65 2c 20 74 68 69 73 20 70 61 72 61 6d 65 74 me, this paramet
36dc0 65 72 20 61 6c 73 6f 20 72 65 70 6f 72 74 73 20 er also reports
36dd0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 the number of th
36de0 72 65 61 64 73 0a 2a 2a 20 75 73 69 6e 67 20 73 reads.** using s
36df0 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 74 cratch memory at
36e00 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 3c the same time.<
36e10 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
36e20 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 QLITE_STATUS_SCR
36e30 41 54 43 48 5f 4f 56 45 52 46 4c 4f 57 3c 2f 64 ATCH_OVERFLOW</d
36e40 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 t>.** <dd>This p
36e50 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 arameter returns
36e60 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
36e70 79 74 65 73 20 6f 66 20 73 63 72 61 74 63 68 20 ytes of scratch
36e80 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 memory.** alloca
36e90 74 69 6f 6e 20 77 68 69 63 68 20 63 6f 75 6c 64 tion which could
36ea0 20 6e 6f 74 20 62 65 20 73 74 61 74 69 73 66 69 not be statisfi
36eb0 65 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 ed by the [SQLIT
36ec0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 E_CONFIG_SCRATCH
36ed0 5d 0a 2a 2a 20 62 75 66 66 65 72 20 61 6e 64 20 ].** buffer and
36ee0 77 68 65 72 65 20 66 6f 72 63 65 64 20 74 6f 20 where forced to
36ef0 6f 76 65 72 66 6c 6f 77 20 74 6f 20 5b 73 71 6c overflow to [sql
36f00 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 ite3_malloc()].
36f10 20 54 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 72 The values.** r
36f20 65 74 75 72 6e 65 64 20 69 6e 63 6c 75 64 65 20 eturned include
36f30 6f 76 65 72 66 6c 6f 77 73 20 62 65 63 61 75 73 overflows becaus
36f40 65 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 e the requested
36f50 61 6c 6c 6f 63 61 74 69 6f 6e 20 77 61 73 20 74 allocation was t
36f60 6f 6f 0a 2a 2a 20 6c 61 72 67 65 72 20 28 74 68 oo.** larger (th
36f70 61 74 20 69 73 2c 20 62 65 63 61 75 73 65 20 74 at is, because t
36f80 68 65 20 72 65 71 75 65 73 74 65 64 20 61 6c 6c he requested all
36f90 6f 63 61 74 69 6f 6e 20 77 61 73 20 6c 61 72 67 ocation was larg
36fa0 65 72 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20 22 er than the.** "
36fb0 73 7a 22 20 70 61 72 61 6d 65 74 65 72 20 74 6f sz" parameter to
36fc0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
36fd0 53 43 52 41 54 43 48 5d 29 20 61 6e 64 20 62 65 SCRATCH]) and be
36fe0 63 61 75 73 65 20 6e 6f 20 73 63 72 61 74 63 68 cause no scratch
36ff0 20 62 75 66 66 65 72 0a 2a 2a 20 73 6c 6f 74 73 buffer.** slots
37000 20 77 65 72 65 20 61 76 61 69 6c 61 62 6c 65 2e were available.
37010 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 .** </dd>.**.**
37020 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 <dt>SQLITE_STATU
37030 53 5f 53 43 52 41 54 43 48 5f 53 49 5a 45 3c 2f S_SCRATCH_SIZE</
37040 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
37050 70 61 72 61 6d 65 74 65 72 20 72 65 63 6f 72 64 parameter record
37060 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 6d 65 s the largest me
37070 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
37080 72 65 71 75 65 73 74 0a 2a 2a 20 68 61 6e 64 65 request.** hande
37090 64 20 74 6f 20 5b 73 63 72 61 74 63 68 20 6d 65 d to [scratch me
370a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e mory allocator].
370b0 20 20 4f 6e 6c 79 20 74 68 65 20 76 61 6c 75 65 Only the value
370c0 20 72 65 74 75 72 6e 65 64 20 69 6e 20 74 68 65 returned in the
370d0 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74 65 72 20 .** *pHighwater
370e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 parameter to [sq
370f0 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 20 lite3_status()]
37100 69 73 20 6f 66 20 69 6e 74 65 72 65 73 74 2e 20 is of interest.
37110 20 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 77 .** The value w
37120 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 ritten into the
37130 2a 70 43 75 72 72 65 6e 74 20 70 61 72 61 6d 65 *pCurrent parame
37140 74 65 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ter is undefined
37150 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
37160 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 >SQLITE_STATUS_P
37170 41 52 53 45 52 5f 53 54 41 43 4b 3c 2f 64 74 3e ARSER_STACK</dt>
37180 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 .** <dd>This par
37190 61 6d 65 74 65 72 20 72 65 63 6f 72 64 73 20 74 ameter records t
371a0 68 65 20 64 65 65 70 65 73 74 20 70 61 72 73 65 he deepest parse
371b0 72 20 73 74 61 63 6b 2e 20 20 49 74 20 69 73 20 r stack. It is
371c0 6f 6e 6c 79 0a 2a 2a 20 6d 65 61 6e 69 6e 67 66 only.** meaningf
371d0 75 6c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 ul if SQLite is
371e0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 59 compiled with [Y
371f0 59 54 52 41 43 4b 4d 41 58 53 54 41 43 4b 44 45 YTRACKMAXSTACKDE
37200 50 54 48 5d 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f PTH].</dd>.** </
37210 64 6c 3e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 73 74 dl>.**.** New st
37220 61 74 75 73 20 70 61 72 61 6d 65 74 65 72 73 20 atus parameters
37230 6d 61 79 20 62 65 20 61 64 64 65 64 20 66 72 6f may be added fro
37240 6d 20 74 69 6d 65 20 74 6f 20 74 69 6d 65 2e 0a m time to time..
37250 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
37260 45 5f 53 54 41 54 55 53 5f 4d 45 4d 4f 52 59 5f E_STATUS_MEMORY_
37270 55 53 45 44 20 20 20 20 20 20 20 20 20 20 30 0a USED 0.
37280 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
37290 54 41 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f TATUS_PAGECACHE_
372a0 55 53 45 44 20 20 20 20 20 20 20 31 0a 23 64 65 USED 1.#de
372b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 fine SQLITE_STAT
372c0 55 53 5f 50 41 47 45 43 41 43 48 45 5f 4f 56 45 US_PAGECACHE_OVE
372d0 52 46 4c 4f 57 20 20 20 32 0a 23 64 65 66 69 6e RFLOW 2.#defin
372e0 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f e SQLITE_STATUS_
372f0 53 43 52 41 54 43 48 5f 55 53 45 44 20 20 20 20 SCRATCH_USED
37300 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 3.#define S
37310 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 QLITE_STATUS_SCR
37320 41 54 43 48 5f 4f 56 45 52 46 4c 4f 57 20 20 20 ATCH_OVERFLOW
37330 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 4.#define SQLI
37340 54 45 5f 53 54 41 54 55 53 5f 4d 41 4c 4c 4f 43 TE_STATUS_MALLOC
37350 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 35 _SIZE 5
37360 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
37370 53 54 41 54 55 53 5f 50 41 52 53 45 52 5f 53 54 STATUS_PARSER_ST
37380 41 43 4b 20 20 20 20 20 20 20 20 20 36 0a 23 64 ACK 6.#d
37390 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 efine SQLITE_STA
373a0 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f 53 49 TUS_PAGECACHE_SI
373b0 5a 45 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 ZE 7.#defi
373c0 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 ne SQLITE_STATUS
373d0 5f 53 43 52 41 54 43 48 5f 53 49 5a 45 20 20 20 _SCRATCH_SIZE
373e0 20 20 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 8../*.** C
373f0 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 API3REF: Databas
37400 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 53 74 61 e Connection Sta
37410 74 75 73 20 7b 48 31 37 35 30 30 7d 20 3c 53 36 tus {H17500} <S6
37420 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 0200>.** EXPERIM
37430 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 ENTAL.**.** This
37440 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 interface is us
37450 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 72 ed to retrieve r
37460 75 6e 74 69 6d 65 20 73 74 61 74 75 73 20 69 6e untime status in
37470 66 6f 72 6d 61 74 69 6f 6e 20 0a 2a 2a 20 61 62 formation .** ab
37480 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 5b 64 61 out a single [da
37490 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
374a0 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 n]. The first a
374b0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a rgument is the.*
374c0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
374d0 63 74 69 6f 6e 20 6f 62 6a 65 63 74 20 74 6f 20 ction object to
374e0 62 65 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e be interrogated.
374f0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 The second arg
37500 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 74 68 65 20 ument.** is the
37510 70 61 72 61 6d 65 74 65 72 20 74 6f 20 69 6e 74 parameter to int
37520 65 72 72 6f 67 61 74 65 2e 20 20 43 75 72 72 65 errogate. Curre
37530 6e 74 6c 79 2c 20 74 68 65 20 6f 6e 6c 79 20 61 ntly, the only a
37540 6c 6c 6f 77 65 64 20 76 61 6c 75 65 0a 2a 2a 20 llowed value.**
37550 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 70 for the second p
37560 61 72 61 6d 65 74 65 72 20 69 73 20 5b 53 51 4c arameter is [SQL
37570 49 54 45 5f 44 42 53 54 41 54 55 53 5f 4c 4f 4f ITE_DBSTATUS_LOO
37580 4b 41 53 49 44 45 5f 55 53 45 44 5d 2e 0a 2a 2a KASIDE_USED]..**
37590 20 41 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 Additional opti
375a0 6f 6e 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 ons will likely
375b0 61 70 70 65 61 72 20 69 6e 20 66 75 74 75 72 65 appear in future
375c0 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c releases of SQL
375d0 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 ite..**.** The c
375e0 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 urrent value of
375f0 74 68 65 20 72 65 71 75 65 73 74 65 64 20 70 61 the requested pa
37600 72 61 6d 65 74 65 72 20 69 73 20 77 72 69 74 74 rameter is writt
37610 65 6e 20 69 6e 74 6f 20 2a 70 43 75 72 0a 2a 2a en into *pCur.**
37620 20 61 6e 64 20 74 68 65 20 68 69 67 68 65 73 74 and the highest
37630 20 69 6e 73 74 61 6e 74 61 6e 65 6f 75 73 20 76 instantaneous v
37640 61 6c 75 65 20 69 73 20 77 72 69 74 74 65 6e 20 alue is written
37650 69 6e 74 6f 20 2a 70 48 69 77 74 72 2e 20 20 49 into *pHiwtr. I
37660 66 0a 2a 2a 20 74 68 65 20 72 65 73 65 74 46 6c f.** the resetFl
37670 67 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 g is true, then
37680 74 68 65 20 68 69 67 68 65 73 74 20 69 6e 73 74 the highest inst
37690 61 6e 74 61 6e 65 6f 75 73 20 76 61 6c 75 65 20 antaneous value
376a0 69 73 0a 2a 2a 20 72 65 73 65 74 20 62 61 63 6b is.** reset back
376b0 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 63 75 72 down to the cur
376c0 72 65 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a rent value..**.*
376d0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
376e0 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 20 61 ite3_status()] a
376f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 nd [sqlite3_stmt
37700 5f 73 74 61 74 75 73 28 29 5d 2e 0a 2a 2f 0a 53 _status()]..*/.S
37710 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 QLITE_EXPERIMENT
37720 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 AL int sqlite3_d
37730 62 5f 73 74 61 74 75 73 28 73 71 6c 69 74 65 33 b_status(sqlite3
37740 2a 2c 20 69 6e 74 20 6f 70 2c 20 69 6e 74 20 2a *, int op, int *
37750 70 43 75 72 2c 20 69 6e 74 20 2a 70 48 69 77 74 pCur, int *pHiwt
37760 72 2c 20 69 6e 74 20 72 65 73 65 74 46 6c 67 29 r, int resetFlg)
37770 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
37780 46 3a 20 53 74 61 74 75 73 20 50 61 72 61 6d 65 F: Status Parame
37790 74 65 72 73 20 66 6f 72 20 64 61 74 61 62 61 73 ters for databas
377a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 7b 48 e connections {H
377b0 31 37 35 32 30 7d 20 3c 48 31 37 35 30 30 3e 0a 17520} <H17500>.
377c0 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a ** EXPERIMENTAL.
377d0 2a 2a 0a 2a 2a 20 53 74 61 74 75 73 20 76 65 72 **.** Status ver
377e0 62 73 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f bs for [sqlite3_
377f0 64 62 5f 73 74 61 74 75 73 28 29 5d 2e 0a 2a 2a db_status()]..**
37800 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e .** <dl>.** <dt>
37810 53 51 4c 49 54 45 5f 44 42 53 54 41 54 55 53 5f SQLITE_DBSTATUS_
37820 4c 4f 4f 4b 41 53 49 44 45 5f 55 53 45 44 3c 2f LOOKASIDE_USED</
37830 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
37840 70 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e parameter return
37850 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
37860 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 lookaside memory
37870 20 73 6c 6f 74 73 20 63 75 72 72 65 6e 74 6c 79 slots currently
37880 0a 2a 2a 20 63 68 65 63 6b 65 64 20 6f 75 74 2e .** checked out.
37890 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a </dd>.** </dl>.*
378a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
378b0 5f 44 42 53 54 41 54 55 53 5f 4c 4f 4f 4b 41 53 _DBSTATUS_LOOKAS
378c0 49 44 45 5f 55 53 45 44 20 20 20 20 20 30 0a 0a IDE_USED 0..
378d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
378e0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d Prepared Statem
378f0 65 6e 74 20 53 74 61 74 75 73 20 7b 48 31 37 35 ent Status {H175
37900 35 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 50} <S60200>.**
37910 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a EXPERIMENTAL.**.
37920 2a 2a 20 45 61 63 68 20 70 72 65 70 61 72 65 64 ** Each prepared
37930 20 73 74 61 74 65 6d 65 6e 74 20 6d 61 69 6e 74 statement maint
37940 61 69 6e 73 20 76 61 72 69 6f 75 73 0a 2a 2a 20 ains various.**
37950 5b 53 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 [SQLITE_STMTSTAT
37960 55 53 5f 53 4f 52 54 20 7c 20 63 6f 75 6e 74 65 US_SORT | counte
37970 72 73 5d 20 74 68 61 74 20 6d 65 61 73 75 72 65 rs] that measure
37980 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f the number.** o
37990 66 20 74 69 6d 65 73 20 69 74 20 68 61 73 20 70 f times it has p
379a0 65 72 66 6f 72 6d 65 64 20 73 70 65 63 69 66 69 erformed specifi
379b0 63 20 6f 70 65 72 61 74 69 6f 6e 73 2e 20 20 54 c operations. T
379c0 68 65 73 65 20 63 6f 75 6e 74 65 72 73 20 63 61 hese counters ca
379d0 6e 0a 2a 2a 20 62 65 20 75 73 65 64 20 74 6f 20 n.** be used to
379e0 6d 6f 6e 69 74 6f 72 20 74 68 65 20 70 65 72 66 monitor the perf
379f0 6f 72 6d 61 6e 63 65 20 63 68 61 72 61 63 74 65 ormance characte
37a00 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 70 ristics of the p
37a10 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 repared.** state
37a20 6d 65 6e 74 73 2e 20 20 46 6f 72 20 65 78 61 6d ments. For exam
37a30 70 6c 65 2c 20 69 66 20 74 68 65 20 6e 75 6d 62 ple, if the numb
37a40 65 72 20 6f 66 20 74 61 62 6c 65 20 73 74 65 70 er of table step
37a50 73 20 67 72 65 61 74 6c 79 20 65 78 63 65 65 64 s greatly exceed
37a60 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 s.** the number
37a70 6f 66 20 74 61 62 6c 65 20 73 65 61 72 63 68 65 of table searche
37a80 73 20 6f 72 20 72 65 73 75 6c 74 20 72 6f 77 73 s or result rows
37a90 2c 20 74 68 61 74 20 77 6f 75 6c 64 20 74 65 6e , that would ten
37aa0 64 20 74 6f 20 69 6e 64 69 63 61 74 65 0a 2a 2a d to indicate.**
37ab0 20 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72 that the prepar
37ac0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 ed statement is
37ad0 75 73 69 6e 67 20 61 20 66 75 6c 6c 20 74 61 62 using a full tab
37ae0 6c 65 20 73 63 61 6e 20 72 61 74 68 65 72 20 74 le scan rather t
37af0 68 61 6e 0a 2a 2a 20 61 6e 20 69 6e 64 65 78 2e han.** an index.
37b00 20 20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e .**.** This in
37b10 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 terface is used
37b20 74 6f 20 72 65 74 72 69 65 76 65 20 61 6e 64 20 to retrieve and
37b30 72 65 73 65 74 20 63 6f 75 6e 74 65 72 20 76 61 reset counter va
37b40 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 61 20 5b lues from.** a [
37b50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
37b60 6e 74 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 nt]. The first
37b70 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 argument is the
37b80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
37b90 6e 74 0a 2a 2a 20 6f 62 6a 65 63 74 20 74 6f 20 nt.** object to
37ba0 62 65 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e be interrogated.
37bb0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 The second arg
37bc0 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 61 6e 20 69 ument.** is an i
37bd0 6e 74 65 67 65 72 20 63 6f 64 65 20 66 6f 72 20 nteger code for
37be0 61 20 73 70 65 63 69 66 69 63 20 5b 53 51 4c 49 a specific [SQLI
37bf0 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f 53 4f TE_STMTSTATUS_SO
37c00 52 54 20 7c 20 63 6f 75 6e 74 65 72 5d 0a 2a 2a RT | counter].**
37c10 20 74 6f 20 62 65 20 69 6e 74 65 72 72 6f 67 61 to be interroga
37c20 74 65 64 2e 20 0a 2a 2a 20 54 68 65 20 63 75 72 ted. .** The cur
37c30 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 74 68 rent value of th
37c40 65 20 72 65 71 75 65 73 74 65 64 20 63 6f 75 6e e requested coun
37c50 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e ter is returned.
37c60 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 65 74 .** If the reset
37c70 46 6c 67 20 69 73 20 74 72 75 65 2c 20 74 68 65 Flg is true, the
37c80 6e 20 74 68 65 20 63 6f 75 6e 74 65 72 20 69 73 n the counter is
37c90 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 20 61 reset to zero a
37ca0 66 74 65 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 fter this.** int
37cb0 65 72 66 61 63 65 20 63 61 6c 6c 20 72 65 74 75 erface call retu
37cc0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 rns..**.** See a
37cd0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 73 74 lso: [sqlite3_st
37ce0 61 74 75 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c atus()] and [sql
37cf0 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 28 29 ite3_db_status()
37d00 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 ]..*/.SQLITE_EXP
37d10 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 ERIMENTAL int sq
37d20 6c 69 74 65 33 5f 73 74 6d 74 5f 73 74 61 74 75 lite3_stmt_statu
37d30 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c s(sqlite3_stmt*,
37d40 20 69 6e 74 20 6f 70 2c 69 6e 74 20 72 65 73 65 int op,int rese
37d50 74 46 6c 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 tFlg);../*.** CA
37d60 50 49 33 52 45 46 3a 20 53 74 61 74 75 73 20 50 PI3REF: Status P
37d70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 70 72 arameters for pr
37d80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
37d90 73 20 7b 48 31 37 35 37 30 7d 20 3c 48 31 37 35 s {H17570} <H175
37da0 35 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 50>.** EXPERIMEN
37db0 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 TAL.**.** These
37dc0 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 preprocessor mac
37dd0 72 6f 73 20 64 65 66 69 6e 65 20 69 6e 74 65 67 ros define integ
37de0 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 6e 61 er codes that na
37df0 6d 65 20 63 6f 75 6e 74 65 72 0a 2a 2a 20 76 61 me counter.** va
37e00 6c 75 65 73 20 61 73 73 6f 63 69 61 74 65 64 20 lues associated
37e10 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 with the [sqlite
37e20 33 5f 73 74 6d 74 5f 73 74 61 74 75 73 28 29 5d 3_stmt_status()]
37e30 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 54 interface..** T
37e40 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 he meanings of t
37e50 68 65 20 76 61 72 69 6f 75 73 20 63 6f 75 6e 74 he various count
37e60 65 72 73 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f ers are as follo
37e70 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a ws:.**.** <dl>.*
37e80 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 4d * <dt>SQLITE_STM
37e90 54 53 54 41 54 55 53 5f 46 55 4c 4c 53 43 41 4e TSTATUS_FULLSCAN
37ea0 5f 53 54 45 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 _STEP</dt>.** <d
37eb0 64 3e 54 68 69 73 20 69 73 20 74 68 65 20 6e 75 d>This is the nu
37ec0 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 mber of times th
37ed0 61 74 20 53 51 4c 69 74 65 20 68 61 73 20 73 74 at SQLite has st
37ee0 65 70 70 65 64 20 66 6f 72 77 61 72 64 20 69 6e epped forward in
37ef0 0a 2a 2a 20 61 20 74 61 62 6c 65 20 61 73 20 70 .** a table as p
37f00 61 72 74 20 6f 66 20 61 20 66 75 6c 6c 20 74 61 art of a full ta
37f10 62 6c 65 20 73 63 61 6e 2e 20 20 4c 61 72 67 65 ble scan. Large
37f20 20 6e 75 6d 62 65 72 73 20 66 6f 72 20 74 68 69 numbers for thi
37f30 73 20 63 6f 75 6e 74 65 72 0a 2a 2a 20 6d 61 79 s counter.** may
37f40 20 69 6e 64 69 63 61 74 65 20 6f 70 70 6f 72 74 indicate opport
37f50 75 6e 69 74 69 65 73 20 66 6f 72 20 70 65 72 66 unities for perf
37f60 6f 72 6d 61 6e 63 65 20 69 6d 70 72 6f 76 65 6d ormance improvem
37f70 65 6e 74 20 74 68 72 6f 75 67 68 20 0a 2a 2a 20 ent through .**
37f80 63 61 72 65 66 75 6c 20 75 73 65 20 6f 66 20 69 careful use of i
37f90 6e 64 69 63 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a ndices.</dd>.**.
37fa0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 ** <dt>SQLITE_ST
37fb0 4d 54 53 54 41 54 55 53 5f 53 4f 52 54 3c 2f 64 MTSTATUS_SORT</d
37fc0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 69 t>.** <dd>This i
37fd0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
37fe0 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 sort operations
37ff0 74 68 61 74 20 68 61 76 65 20 6f 63 63 75 72 72 that have occurr
38000 65 64 2e 0a 2a 2a 20 41 20 6e 6f 6e 2d 7a 65 72 ed..** A non-zer
38010 6f 20 76 61 6c 75 65 20 69 6e 20 74 68 69 73 20 o value in this
38020 63 6f 75 6e 74 65 72 20 6d 61 79 20 69 6e 64 69 counter may indi
38030 63 61 74 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e cate an opportun
38040 69 74 79 20 74 6f 0a 2a 2a 20 69 6d 70 72 6f 76 ity to.** improv
38050 65 6d 65 6e 74 20 70 65 72 66 6f 72 6d 61 6e 63 ement performanc
38060 65 20 74 68 72 6f 75 67 68 20 63 61 72 65 66 75 e through carefu
38070 6c 20 75 73 65 20 6f 66 20 69 6e 64 69 63 65 73 l use of indices
38080 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 .</dd>.**.** </d
38090 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 l>.*/.#define SQ
380a0 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f LITE_STMTSTATUS_
380b0 46 55 4c 4c 53 43 41 4e 5f 53 54 45 50 20 20 20 FULLSCAN_STEP
380c0 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 1.#define SQLI
380d0 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f 53 4f TE_STMTSTATUS_SO
380e0 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 RT
380f0 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 2../*.** CAPI3RE
38100 46 3a 20 43 75 73 74 6f 6d 20 50 61 67 65 20 43 F: Custom Page C
38110 61 63 68 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 45 ache Object.** E
38120 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a XPERIMENTAL.**.*
38130 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 63 * The sqlite3_pc
38140 61 63 68 65 20 74 79 70 65 20 69 73 20 6f 70 61 ache type is opa
38150 71 75 65 2e 20 20 49 74 20 69 73 20 69 6d 70 6c que. It is impl
38160 65 6d 65 6e 74 65 64 20 62 79 0a 2a 2a 20 74 68 emented by.** th
38170 65 20 70 6c 75 67 67 61 62 6c 65 20 6d 6f 64 75 e pluggable modu
38180 6c 65 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 le. The SQLite
38190 63 6f 72 65 20 68 61 73 20 6e 6f 20 6b 6e 6f 77 core has no know
381a0 6c 65 64 67 65 20 6f 66 0a 2a 2a 20 69 74 73 20 ledge of.** its
381b0 73 69 7a 65 20 6f 72 20 69 6e 74 65 72 6e 61 6c size or internal
381c0 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 20 6e structure and n
381d0 65 76 65 72 20 64 65 61 6c 73 20 77 69 74 68 20 ever deals with
381e0 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 the.** sqlite3_p
381f0 63 61 63 68 65 20 6f 62 6a 65 63 74 20 65 78 63 cache object exc
38200 65 70 74 20 62 79 20 68 6f 6c 64 69 6e 67 20 61 ept by holding a
38210 6e 64 20 70 61 73 73 69 6e 67 20 70 6f 69 6e 74 nd passing point
38220 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 6f 62 ers.** to the ob
38230 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 ject..**.** See
38240 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f [sqlite3_pcache_
38250 6d 65 74 68 6f 64 73 5d 20 66 6f 72 20 61 64 64 methods] for add
38260 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 itional informat
38270 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ion..*/.typedef
38280 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 70 struct sqlite3_p
38290 63 61 63 68 65 20 73 71 6c 69 74 65 33 5f 70 63 cache sqlite3_pc
382a0 61 63 68 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ache;../*.** CAP
382b0 49 33 52 45 46 3a 20 41 70 70 6c 69 63 61 74 69 I3REF: Applicati
382c0 6f 6e 20 44 65 66 69 6e 65 64 20 50 61 67 65 20 on Defined Page
382d0 43 61 63 68 65 2e 0a 2a 2a 20 45 58 50 45 52 49 Cache..** EXPERI
382e0 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 MENTAL.**.** The
382f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
38300 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ]([SQLITE_CONFIG
38310 5f 50 43 41 43 48 45 5d 2c 20 2e 2e 2e 29 20 69 _PCACHE], ...) i
38320 6e 74 65 72 66 61 63 65 20 63 61 6e 0a 2a 2a 20 nterface can.**
38330 72 65 67 69 73 74 65 72 20 61 6e 20 61 6c 74 65 register an alte
38340 72 6e 61 74 69 76 65 20 70 61 67 65 20 63 61 63 rnative page cac
38350 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
38360 6e 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 n by passing in
38370 61 6e 20 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 an .** instance
38380 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 of the sqlite3_p
38390 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 20 73 74 cache_methods st
383a0 72 75 63 74 75 72 65 2e 20 54 68 65 20 6d 61 6a ructure. The maj
383b0 6f 72 69 74 79 20 6f 66 20 74 68 65 20 0a 2a 2a ority of the .**
383c0 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 73 65 heap memory use
383d0 64 20 62 79 20 73 71 6c 69 74 65 20 69 73 20 75 d by sqlite is u
383e0 73 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20 sed by the page
383f0 63 61 63 68 65 20 74 6f 20 63 61 63 68 65 20 64 cache to cache d
38400 61 74 61 20 72 65 61 64 20 0a 2a 2a 20 66 72 6f ata read .** fro
38410 6d 2c 20 6f 72 20 72 65 61 64 79 20 74 6f 20 62 m, or ready to b
38420 65 20 77 72 69 74 74 65 6e 20 74 6f 2c 20 74 68 e written to, th
38430 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e e database file.
38440 20 42 79 20 69 6d 70 6c 65 6d 65 6e 74 69 6e 67 By implementing
38450 20 61 20 0a 2a 2a 20 63 75 73 74 6f 6d 20 70 61 a .** custom pa
38460 67 65 20 63 61 63 68 65 20 75 73 69 6e 67 20 74 ge cache using t
38470 68 69 73 20 41 50 49 2c 20 61 6e 20 61 70 70 6c his API, an appl
38480 69 63 61 74 69 6f 6e 20 63 61 6e 20 63 6f 6e 74 ication can cont
38490 72 6f 6c 20 6d 6f 72 65 20 0a 2a 2a 20 70 72 65 rol more .** pre
384a0 63 69 73 65 6c 79 20 74 68 65 20 61 6d 6f 75 6e cisely the amoun
384b0 74 20 6f 66 20 6d 65 6d 6f 72 79 20 63 6f 6e 73 t of memory cons
384c0 75 6d 65 64 20 62 79 20 73 71 6c 69 74 65 2c 20 umed by sqlite,
384d0 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 the way in which
384e0 20 0a 2a 2a 20 73 61 69 64 20 6d 65 6d 6f 72 79 .** said memory
384f0 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e is allocated an
38500 64 20 72 65 6c 65 61 73 65 64 2c 20 61 6e 64 20 d released, and
38510 74 68 65 20 70 6f 6c 69 63 69 65 73 20 75 73 65 the policies use
38520 64 20 74 6f 20 0a 2a 2a 20 64 65 74 65 72 6d 69 d to .** determi
38530 6e 65 20 65 78 61 63 74 6c 79 20 77 68 69 63 68 ne exactly which
38540 20 70 61 72 74 73 20 6f 66 20 61 20 64 61 74 61 parts of a data
38550 62 61 73 65 20 66 69 6c 65 20 61 72 65 20 63 61 base file are ca
38560 63 68 65 64 20 61 6e 64 20 66 6f 72 20 0a 2a 2a ched and for .**
38570 20 68 6f 77 20 6c 6f 6e 67 2e 0a 2a 2a 0a 2a 2a how long..**.**
38580 20 54 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 The contents of
38590 20 74 68 65 20 73 74 72 75 63 74 75 72 65 20 61 the structure a
385a0 72 65 20 63 6f 70 69 65 64 20 74 6f 20 61 6e 20 re copied to an
385b0 69 6e 74 65 72 6e 61 6c 20 62 75 66 66 65 72 20 internal buffer
385c0 62 79 20 73 71 6c 69 74 65 0a 2a 2a 20 77 69 74 by sqlite.** wit
385d0 68 69 6e 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 hin the call to
385e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d [sqlite3_config]
385f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 ..**.** The xIni
38600 74 28 29 20 6d 65 74 68 6f 64 20 69 73 20 63 61 t() method is ca
38610 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 lled once for ea
38620 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 ch call to [sqli
38630 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
38640 5d 0a 2a 2a 20 28 75 73 75 61 6c 6c 79 20 6f 6e ].** (usually on
38650 6c 79 20 6f 6e 63 65 20 64 75 72 69 6e 67 20 74 ly once during t
38660 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 he lifetime of t
38670 68 65 20 70 72 6f 63 65 73 73 29 2e 20 49 74 20 he process). It
38680 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 61 20 63 is passed.** a c
38690 6f 70 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 opy of the sqlit
386a0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 e3_pcache_method
386b0 73 2e 70 41 72 67 20 76 61 6c 75 65 2e 20 49 74 s.pArg value. It
386c0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
386d0 73 65 74 0a 2a 2a 20 75 70 20 67 6c 6f 62 61 6c set.** up global
386e0 20 73 74 72 75 63 74 75 72 65 73 20 61 6e 64 20 structures and
386f0 6d 75 74 65 78 65 73 20 72 65 71 75 69 72 65 64 mutexes required
38700 20 62 79 20 74 68 65 20 63 75 73 74 6f 6d 20 70 by the custom p
38710 61 67 65 20 63 61 63 68 65 20 0a 2a 2a 20 69 6d age cache .** im
38720 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 54 68 plementation. Th
38730 65 20 78 53 68 75 74 64 6f 77 6e 28 29 20 6d 65 e xShutdown() me
38740 74 68 6f 64 20 69 73 20 63 61 6c 6c 65 64 20 66 thod is called f
38750 72 6f 6d 20 77 69 74 68 69 6e 20 0a 2a 2a 20 5b rom within .** [
38760 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
38770 28 29 5d 2c 20 69 66 20 74 68 65 20 61 70 70 6c ()], if the appl
38780 69 63 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 ication invokes
38790 74 68 69 73 20 41 50 49 2e 20 49 74 20 63 61 6e this API. It can
387a0 20 62 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 63 be used.** to c
387b0 6c 65 61 6e 20 75 70 20 61 6e 79 20 6f 75 74 73 lean up any outs
387c0 74 61 6e 64 69 6e 67 20 72 65 73 6f 75 72 63 65 tanding resource
387d0 73 20 62 65 66 6f 72 65 20 70 72 6f 63 65 73 73 s before process
387e0 20 73 68 75 74 64 6f 77 6e 2c 20 69 66 20 72 65 shutdown, if re
387f0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 quired..**.** Th
38800 65 20 78 43 72 65 61 74 65 28 29 20 6d 65 74 68 e xCreate() meth
38810 6f 64 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f od is used to co
38820 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 63 61 nstruct a new ca
38830 63 68 65 20 69 6e 73 74 61 6e 63 65 2e 20 54 68 che instance. Th
38840 65 0a 2a 2a 20 66 69 72 73 74 20 70 61 72 61 6d e.** first param
38850 65 74 65 72 2c 20 73 7a 50 61 67 65 2c 20 69 73 eter, szPage, is
38860 20 74 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 the size in byt
38870 65 73 20 6f 66 20 74 68 65 20 70 61 67 65 73 20 es of the pages
38880 74 68 61 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 that must.** be
38890 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 74 68 65 allocated by the
388a0 20 63 61 63 68 65 2e 20 73 7a 50 61 67 65 20 77 cache. szPage w
388b0 69 6c 6c 20 6e 6f 74 20 62 65 20 61 20 70 6f 77 ill not be a pow
388c0 65 72 20 6f 66 20 74 77 6f 2e 20 54 68 65 0a 2a er of two. The.*
388d0 2a 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e * second argumen
388e0 74 2c 20 62 50 75 72 67 65 61 62 6c 65 2c 20 69 t, bPurgeable, i
388f0 73 20 74 72 75 65 20 69 66 20 74 68 65 20 63 61 s true if the ca
38900 63 68 65 20 62 65 69 6e 67 20 63 72 65 61 74 65 che being create
38910 64 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 75 73 65 d will.** be use
38920 64 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 d to cache datab
38930 61 73 65 20 70 61 67 65 73 20 72 65 61 64 20 66 ase pages read f
38940 72 6f 6d 20 61 20 66 69 6c 65 20 73 74 6f 72 65 rom a file store
38950 64 20 6f 6e 20 64 69 73 6b 2c 20 6f 72 0a 2a 2a d on disk, or.**
38960 20 66 61 6c 73 65 20 69 66 20 69 74 20 69 73 20 false if it is
38970 75 73 65 64 20 66 6f 72 20 61 6e 20 69 6e 2d 6d used for an in-m
38980 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 2e 20 emory database.
38990 54 68 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d The cache implem
389a0 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 entation.** does
389b0 20 6e 6f 74 20 68 61 76 65 20 74 6f 20 64 6f 20 not have to do
389c0 61 6e 79 74 68 69 6e 67 20 73 70 65 63 69 61 6c anything special
389d0 20 62 61 73 65 64 20 6f 6e 20 74 68 65 20 76 61 based on the va
389e0 6c 75 65 20 6f 66 20 62 50 75 72 67 65 61 62 6c lue of bPurgeabl
389f0 65 2c 0a 2a 2a 20 69 74 20 69 73 20 70 75 72 65 e,.** it is pure
38a00 6c 79 20 61 64 76 69 73 6f 72 79 2e 20 0a 2a 2a ly advisory. .**
38a10 0a 2a 2a 20 54 68 65 20 78 43 61 63 68 65 73 69 .** The xCachesi
38a20 7a 65 28 29 20 6d 65 74 68 6f 64 20 6d 61 79 20 ze() method may
38a30 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 be called at any
38a40 20 74 69 6d 65 20 62 79 20 53 51 4c 69 74 65 20 time by SQLite
38a50 74 6f 20 73 65 74 20 74 68 65 0a 2a 2a 20 73 75 to set the.** su
38a60 67 67 65 73 74 65 64 20 6d 61 78 69 6d 75 6d 20 ggested maximum
38a70 63 61 63 68 65 2d 73 69 7a 65 20 28 6e 75 6d 62 cache-size (numb
38a80 65 72 20 6f 66 20 70 61 67 65 73 20 73 74 6f 72 er of pages stor
38a90 65 64 20 62 79 29 20 74 68 65 20 63 61 63 68 65 ed by) the cache
38aa0 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 70 61 73 .** instance pas
38ab0 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 sed as the first
38ac0 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 69 73 20 argument. This
38ad0 69 73 20 74 68 65 20 76 61 6c 75 65 20 63 6f 6e is the value con
38ae0 66 69 67 75 72 65 64 20 75 73 69 6e 67 0a 2a 2a figured using.**
38af0 20 74 68 65 20 53 51 4c 69 74 65 20 22 5b 50 52 the SQLite "[PR
38b00 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d AGMA cache_size]
38b10 22 20 63 6f 6d 6d 61 6e 64 2e 20 41 73 20 77 69 " command. As wi
38b20 74 68 20 74 68 65 20 62 50 75 72 67 65 61 62 6c th the bPurgeabl
38b30 65 20 70 61 72 61 6d 65 74 65 72 2c 0a 2a 2a 20 e parameter,.**
38b40 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 the implementati
38b50 6f 6e 20 69 73 20 6e 6f 74 20 72 65 71 75 69 72 on is not requir
38b60 65 64 20 74 6f 20 64 6f 20 61 6e 79 74 68 69 6e ed to do anythin
38b70 67 20 73 70 65 63 69 61 6c 20 77 69 74 68 20 74 g special with t
38b80 68 69 73 0a 2a 2a 20 76 61 6c 75 65 2c 20 69 74 his.** value, it
38b90 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c is advisory onl
38ba0 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 50 61 y..**.** The xPa
38bb0 67 65 63 6f 75 6e 74 28 29 20 6d 65 74 68 6f 64 gecount() method
38bc0 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 should return t
38bd0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 he number of pag
38be0 65 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 es currently.**
38bf0 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 61 stored in the ca
38c00 63 68 65 20 73 75 70 70 6c 69 65 64 20 61 73 20 che supplied as
38c10 61 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 an argument..**
38c20 0a 2a 2a 20 54 68 65 20 78 46 65 74 63 68 28 29 .** The xFetch()
38c30 20 6d 65 74 68 6f 64 20 69 73 20 75 73 65 64 20 method is used
38c40 74 6f 20 66 65 74 63 68 20 61 20 70 61 67 65 20 to fetch a page
38c50 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 and return a poi
38c60 6e 74 65 72 20 74 6f 20 69 74 2e 20 0a 2a 2a 20 nter to it. .**
38c70 41 20 27 70 61 67 65 27 2c 20 69 6e 20 74 68 69 A 'page', in thi
38c80 73 20 63 6f 6e 74 65 78 74 2c 20 69 73 20 61 20 s context, is a
38c90 62 75 66 66 65 72 20 6f 66 20 73 7a 50 61 67 65 buffer of szPage
38ca0 20 62 79 74 65 73 20 61 6c 69 67 6e 65 64 20 61 bytes aligned a
38cb0 74 20 61 6e 0a 2a 2a 20 38 2d 62 79 74 65 20 62 t an.** 8-byte b
38cc0 6f 75 6e 64 61 72 79 2e 20 54 68 65 20 70 61 67 oundary. The pag
38cd0 65 20 74 6f 20 62 65 20 66 65 74 63 68 65 64 20 e to be fetched
38ce0 69 73 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 is determined by
38cf0 20 74 68 65 20 6b 65 79 2e 20 54 68 65 0a 2a 2a the key. The.**
38d00 20 6d 69 6d 69 6d 75 6d 20 6b 65 79 20 76 61 6c mimimum key val
38d10 75 65 20 69 73 20 31 2e 20 41 66 74 65 72 20 69 ue is 1. After i
38d20 74 20 68 61 73 20 62 65 65 6e 20 72 65 74 72 69 t has been retri
38d30 65 76 65 64 20 75 73 69 6e 67 20 78 46 65 74 63 eved using xFetc
38d40 68 2c 20 74 68 65 20 70 61 67 65 20 0a 2a 2a 20 h, the page .**
38d50 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f is considered to
38d60 20 62 65 20 70 69 6e 6e 65 64 2e 0a 2a 2a 0a 2a be pinned..**.*
38d70 2a 20 49 66 20 74 68 65 20 72 65 71 75 65 73 74 * If the request
38d80 65 64 20 70 61 67 65 20 69 73 20 61 6c 72 65 61 ed page is alrea
38d90 64 79 20 69 6e 20 74 68 65 20 70 61 67 65 20 63 dy in the page c
38da0 61 63 68 65 2c 20 74 68 65 6e 20 61 20 70 6f 69 ache, then a poi
38db0 6e 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 63 nter to.** the c
38dc0 61 63 68 65 64 20 62 75 66 66 65 72 20 73 68 6f ached buffer sho
38dd0 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 20 uld be returned
38de0 77 69 74 68 20 69 74 73 20 63 6f 6e 74 65 6e 74 with its content
38df0 73 20 69 6e 74 61 63 74 2e 20 49 66 20 74 68 65 s intact. If the
38e00 0a 2a 2a 20 70 61 67 65 20 69 73 20 6e 6f 74 20 .** page is not
38e10 61 6c 72 65 61 64 79 20 69 6e 20 74 68 65 20 63 already in the c
38e20 61 63 68 65 2c 20 74 68 65 6e 20 74 68 65 20 65 ache, then the e
38e30 78 70 65 63 74 65 64 20 62 65 68 61 76 69 6f 75 xpected behaviou
38e40 72 20 6f 66 20 74 68 65 0a 2a 2a 20 63 61 63 68 r of the.** cach
38e50 65 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 20 e is determined
38e60 62 79 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 by the value of
38e70 74 68 65 20 63 72 65 61 74 65 46 6c 61 67 20 70 the createFlag p
38e80 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 0a arameter passed.
38e90 2a 2a 20 74 6f 20 78 46 65 74 63 68 2c 20 61 63 ** to xFetch, ac
38ea0 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 66 cording to the f
38eb0 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 3a 0a ollowing table:.
38ec0 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 **.** <table bor
38ed0 64 65 72 3d 31 20 77 69 64 74 68 3d 38 35 25 20 der=1 width=85%
38ee0 61 6c 69 67 6e 3d 63 65 6e 74 65 72 3e 0a 2a 2a align=center>.**
38ef0 20 20 20 3c 74 72 3e 3c 74 68 3e 63 72 65 61 74 <tr><th>creat
38f00 65 46 6c 61 67 3c 74 68 3e 45 78 70 65 63 74 65 eFlag<th>Expecte
38f10 64 20 42 65 68 61 76 69 6f 75 72 0a 2a 2a 20 20 d Behaviour.**
38f20 20 3c 74 72 3e 3c 74 64 3e 30 3c 74 64 3e 4e 55 <tr><td>0<td>NU
38f30 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 LL should be ret
38f40 75 72 6e 65 64 2e 20 4e 6f 20 6e 65 77 20 63 61 urned. No new ca
38f50 63 68 65 20 65 6e 74 72 79 20 69 73 20 63 72 65 che entry is cre
38f60 61 74 65 64 2e 0a 2a 2a 20 20 20 3c 74 72 3e 3c ated..** <tr><
38f70 74 64 3e 31 3c 74 64 3e 49 66 20 63 72 65 61 74 td>1<td>If creat
38f80 65 46 6c 61 67 20 69 73 20 73 65 74 20 74 6f 20 eFlag is set to
38f90 31 2c 20 74 68 69 73 20 69 6e 64 69 63 61 74 65 1, this indicate
38fa0 73 20 74 68 61 74 20 0a 2a 2a 20 20 20 20 20 20 s that .**
38fb0 20 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 SQLite
38fc0 20 69 73 20 68 6f 6c 64 69 6e 67 20 70 69 6e 6e is holding pinn
38fd0 65 64 20 70 61 67 65 73 20 74 68 61 74 20 63 61 ed pages that ca
38fe0 6e 20 62 65 20 75 6e 70 69 6e 6e 65 64 0a 2a 2a n be unpinned.**
38ff0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
39000 62 79 20 77 72 69 74 69 6e 67 20 74 68 65 69 72 by writing their
39010 20 63 6f 6e 74 65 6e 74 73 20 74 6f 20 74 68 65 contents to the
39020 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 28 database file (
39030 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 a.**
39040 20 20 20 20 72 65 6c 61 74 69 76 65 6c 79 20 65 relatively e
39050 78 70 65 6e 73 69 76 65 20 6f 70 65 72 61 74 69 xpensive operati
39060 6f 6e 29 2e 20 49 6e 20 74 68 69 73 20 73 69 74 on). In this sit
39070 75 61 74 69 6f 6e 20 74 68 65 0a 2a 2a 20 20 20 uation the.**
39080 20 20 20 20 20 20 20 20 20 20 20 20 20 63 61 63 cac
39090 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
390a0 6e 20 68 61 73 20 74 77 6f 20 63 68 6f 69 63 65 n has two choice
390b0 73 3a 20 69 74 20 63 61 6e 20 72 65 74 75 72 6e s: it can return
390c0 20 4e 55 4c 4c 2c 0a 2a 2a 20 20 20 20 20 20 20 NULL,.**
390d0 20 20 20 20 20 20 20 20 20 69 6e 20 77 68 69 63 in whic
390e0 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 h case SQLite wi
390f0 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f 20 75 6e ll attempt to un
39100 70 69 6e 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 pin one or more
39110 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 .**
39120 20 20 20 70 61 67 65 73 20 62 65 66 6f 72 65 20 pages before
39130 72 65 2d 72 65 71 75 65 73 74 69 6e 67 20 74 68 re-requesting th
39140 65 20 73 61 6d 65 20 70 61 67 65 2c 20 6f 72 20 e same page, or
39150 69 74 20 63 61 6e 0a 2a 2a 20 20 20 20 20 20 20 it can.**
39160 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 allocat
39170 65 20 61 20 6e 65 77 20 70 61 67 65 20 61 6e 64 e a new page and
39180 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 return a pointe
39190 72 20 74 6f 20 69 74 2e 20 49 66 20 61 20 6e 65 r to it. If a ne
391a0 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 w.**
391b0 20 20 20 20 70 61 67 65 20 69 73 20 61 6c 6c 6f page is allo
391c0 63 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 20 cated, then the
391d0 66 69 72 73 74 20 73 69 7a 65 6f 66 28 76 6f 69 first sizeof(voi
391e0 64 2a 29 20 62 79 74 65 73 20 6f 66 0a 2a 2a 20 d*) bytes of.**
391f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 i
39200 74 20 28 61 74 20 6c 65 61 73 74 29 20 6d 75 73 t (at least) mus
39210 74 20 62 65 20 7a 65 72 6f 65 64 20 62 65 66 6f t be zeroed befo
39220 72 65 20 69 74 20 69 73 20 72 65 74 75 72 6e 65 re it is returne
39230 64 2e 0a 2a 2a 20 20 20 3c 74 72 3e 3c 74 64 3e d..** <tr><td>
39240 32 3c 74 64 3e 49 66 20 63 72 65 61 74 65 46 6c 2<td>If createFl
39250 61 67 20 69 73 20 73 65 74 20 74 6f 20 32 2c 20 ag is set to 2,
39260 74 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 6e then SQLite is n
39270 6f 74 20 68 6f 6c 64 69 6e 67 20 61 6e 79 0a 2a ot holding any.*
39280 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 *
39290 20 70 69 6e 6e 65 64 20 70 61 67 65 73 20 61 73 pinned pages as
392a0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 sociated with th
392b0 65 20 73 70 65 63 69 66 69 63 20 63 61 63 68 65 e specific cache
392c0 20 70 61 73 73 65 64 0a 2a 2a 20 20 20 20 20 20 passed.**
392d0 20 20 20 20 20 20 20 20 20 20 61 73 20 74 68 65 as the
392e0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
392f0 74 6f 20 78 46 65 74 63 68 28 29 20 74 68 61 74 to xFetch() that
39300 20 63 61 6e 20 62 65 20 75 6e 70 69 6e 6e 65 64 can be unpinned
39310 2e 20 54 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 . The.**
39320 20 20 20 20 20 20 20 20 63 61 63 68 65 20 69 6d cache im
39330 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f plementation sho
39340 75 6c 64 20 61 74 74 65 6d 70 74 20 74 6f 20 61 uld attempt to a
39350 6c 6c 6f 63 61 74 65 20 61 20 6e 65 77 0a 2a 2a llocate a new.**
39360 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
39370 63 61 63 68 65 20 65 6e 74 72 79 20 61 6e 64 20 cache entry and
39380 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 return a pointer
39390 20 74 6f 20 69 74 2e 20 41 67 61 69 6e 2c 20 74 to it. Again, t
393a0 68 65 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 he first.**
393b0 20 20 20 20 20 20 20 20 20 20 20 73 69 7a 65 6f sizeo
393c0 66 28 76 6f 69 64 2a 29 20 62 79 74 65 73 20 6f f(void*) bytes o
393d0 66 20 74 68 65 20 70 61 67 65 20 73 68 6f 75 6c f the page shoul
393e0 64 20 62 65 20 7a 65 72 6f 65 64 20 62 65 66 6f d be zeroed befo
393f0 72 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 re .**
39400 20 20 20 20 20 20 69 74 20 69 73 20 72 65 74 75 it is retu
39410 72 6e 65 64 2e 20 49 66 20 74 68 65 20 78 46 65 rned. If the xFe
39420 74 63 68 28 29 20 6d 65 74 68 6f 64 20 72 65 74 tch() method ret
39430 75 72 6e 73 20 4e 55 4c 4c 20 77 68 65 6e 20 0a urns NULL when .
39440 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 **
39450 20 20 63 72 65 61 74 65 46 6c 61 67 3d 3d 32 2c createFlag==2,
39460 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 SQLite assumes
39470 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c that a memory al
39480 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 20 20 20 location .**
39490 20 20 20 20 20 20 20 20 20 20 20 20 66 61 69 6c fail
394a0 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 53 ed and returns S
394b0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 74 6f 20 74 QLITE_NOMEM to t
394c0 68 65 20 75 73 65 72 2e 0a 2a 2a 20 3c 2f 74 61 he user..** </ta
394d0 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 78 55 6e 70 69 ble>.**.** xUnpi
394e0 6e 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 n() is called by
394f0 20 53 51 4c 69 74 65 20 77 69 74 68 20 61 20 70 SQLite with a p
39500 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 75 72 72 ointer to a curr
39510 65 6e 74 6c 79 20 70 69 6e 6e 65 64 20 70 61 67 ently pinned pag
39520 65 0a 2a 2a 20 61 73 20 69 74 73 20 73 65 63 6f e.** as its seco
39530 6e 64 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 nd argument. If
39540 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
39550 74 65 72 2c 20 64 69 73 63 61 72 64 2c 20 69 73 ter, discard, is
39560 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 non-zero,.** th
39570 65 6e 20 74 68 65 20 70 61 67 65 20 73 68 6f 75 en the page shou
39580 6c 64 20 62 65 20 65 76 69 63 74 65 64 20 66 72 ld be evicted fr
39590 6f 6d 20 74 68 65 20 63 61 63 68 65 2e 20 49 6e om the cache. In
395a0 20 74 68 69 73 20 63 61 73 65 20 53 51 4c 69 74 this case SQLit
395b0 65 20 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 e .** assumes th
395c0 61 74 20 74 68 65 20 6e 65 78 74 20 74 69 6d 65 at the next time
395d0 20 74 68 65 20 70 61 67 65 20 69 73 20 72 65 74 the page is ret
395e0 72 69 65 76 65 64 20 66 72 6f 6d 20 74 68 65 20 rieved from the
395f0 63 61 63 68 65 20 75 73 69 6e 67 0a 2a 2a 20 74 cache using.** t
39600 68 65 20 78 46 65 74 63 68 28 29 20 6d 65 74 68 he xFetch() meth
39610 6f 64 2c 20 69 74 20 77 69 6c 6c 20 62 65 20 7a od, it will be z
39620 65 72 6f 65 64 2e 20 49 66 20 74 68 65 20 64 69 eroed. If the di
39630 73 63 61 72 64 20 70 61 72 61 6d 65 74 65 72 20 scard parameter
39640 69 73 0a 2a 2a 20 7a 65 72 6f 2c 20 74 68 65 6e is.** zero, then
39650 20 74 68 65 20 70 61 67 65 20 69 73 20 63 6f 6e the page is con
39660 73 69 64 65 72 65 64 20 74 6f 20 62 65 20 75 6e sidered to be un
39670 70 69 6e 6e 65 64 2e 20 54 68 65 20 63 61 63 68 pinned. The cach
39680 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
39690 0a 2a 2a 20 6d 61 79 20 63 68 6f 6f 73 65 20 74 .** may choose t
396a0 6f 20 72 65 63 6c 61 69 6d 20 28 66 72 65 65 20 o reclaim (free
396b0 6f 72 20 72 65 63 79 63 6c 65 29 20 75 6e 70 69 or recycle) unpi
396c0 6e 6e 65 64 20 70 61 67 65 73 20 61 74 20 61 6e nned pages at an
396d0 79 20 74 69 6d 65 2e 0a 2a 2a 20 53 51 4c 69 74 y time..** SQLit
396e0 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 6e e assumes that n
396f0 65 78 74 20 74 69 6d 65 20 74 68 65 20 70 61 67 ext time the pag
39700 65 20 69 73 20 72 65 74 72 69 65 76 65 64 20 66 e is retrieved f
39710 72 6f 6d 20 74 68 65 20 63 61 63 68 65 0a 2a 2a rom the cache.**
39720 20 69 74 20 77 69 6c 6c 20 65 69 74 68 65 72 20 it will either
39730 62 65 20 7a 65 72 6f 65 64 2c 20 6f 72 20 63 6f be zeroed, or co
39740 6e 74 61 69 6e 20 74 68 65 20 73 61 6d 65 20 64 ntain the same d
39750 61 74 61 20 74 68 61 74 20 69 74 20 64 69 64 20 ata that it did
39760 77 68 65 6e 20 69 74 0a 2a 2a 20 77 61 73 20 75 when it.** was u
39770 6e 70 69 6e 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 npinned..**.** T
39780 68 65 20 63 61 63 68 65 20 69 73 20 6e 6f 74 20 he cache is not
39790 72 65 71 75 69 72 65 64 20 74 6f 20 70 65 72 66 required to perf
397a0 6f 72 6d 20 61 6e 79 20 72 65 66 65 72 65 6e 63 orm any referenc
397b0 65 20 63 6f 75 6e 74 69 6e 67 2e 20 41 20 73 69 e counting. A si
397c0 6e 67 6c 65 20 0a 2a 2a 20 63 61 6c 6c 20 74 6f ngle .** call to
397d0 20 78 55 6e 70 69 6e 28 29 20 75 6e 70 69 6e 73 xUnpin() unpins
397e0 20 74 68 65 20 70 61 67 65 20 72 65 67 61 72 64 the page regard
397f0 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 less of the numb
39800 65 72 20 6f 66 20 70 72 69 6f 72 20 63 61 6c 6c er of prior call
39810 73 20 0a 2a 2a 20 74 6f 20 78 46 65 74 63 68 28 s .** to xFetch(
39820 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 65 )..**.** The xRe
39830 6b 65 79 28 29 20 6d 65 74 68 6f 64 20 69 73 20 key() method is
39840 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 used to change t
39850 68 65 20 6b 65 79 20 76 61 6c 75 65 20 61 73 73 he key value ass
39860 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 ociated with the
39870 0a 2a 2a 20 70 61 67 65 20 70 61 73 73 65 64 20 .** page passed
39880 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 as the second ar
39890 67 75 6d 65 6e 74 20 66 72 6f 6d 20 6f 6c 64 4b gument from oldK
398a0 65 79 20 74 6f 20 6e 65 77 4b 65 79 2e 20 49 66 ey to newKey. If
398b0 20 74 68 65 20 63 61 63 68 65 0a 2a 2a 20 70 72 the cache.** pr
398c0 65 76 69 6f 75 73 6c 79 20 63 6f 6e 74 61 69 6e eviously contain
398d0 73 20 61 6e 20 65 6e 74 72 79 20 61 73 73 6f 63 s an entry assoc
398e0 69 61 74 65 64 20 77 69 74 68 20 6e 65 77 4b 65 iated with newKe
398f0 79 2c 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a y, it should be.
39900 2a 2a 20 64 69 73 63 61 72 64 65 64 2e 20 41 6e ** discarded. An
39910 79 20 70 72 69 6f 72 20 63 61 63 68 65 20 65 6e y prior cache en
39920 74 72 79 20 61 73 73 6f 63 69 61 74 65 64 20 77 try associated w
39930 69 74 68 20 6e 65 77 4b 65 79 20 69 73 20 67 75 ith newKey is gu
39940 61 72 61 6e 74 65 65 64 20 6e 6f 74 0a 2a 2a 20 aranteed not.**
39950 74 6f 20 62 65 20 70 69 6e 6e 65 64 2e 0a 2a 2a to be pinned..**
39960 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 .** When SQLite
39970 63 61 6c 6c 73 20 74 68 65 20 78 54 72 75 6e 63 calls the xTrunc
39980 61 74 65 28 29 20 6d 65 74 68 6f 64 2c 20 74 68 ate() method, th
39990 65 20 63 61 63 68 65 20 6d 75 73 74 20 64 69 73 e cache must dis
399a0 63 61 72 64 20 61 6c 6c 0a 2a 2a 20 65 78 69 73 card all.** exis
399b0 74 69 6e 67 20 63 61 63 68 65 20 65 6e 74 72 69 ting cache entri
399c0 65 73 20 77 69 74 68 20 70 61 67 65 20 6e 75 6d es with page num
399d0 62 65 72 73 20 28 6b 65 79 73 29 20 67 72 65 61 bers (keys) grea
399e0 74 65 72 20 74 68 61 6e 20 6f 72 20 65 71 75 61 ter than or equa
399f0 6c 0a 2a 2a 20 74 6f 20 74 68 65 20 76 61 6c 75 l.** to the valu
39a00 65 20 6f 66 20 74 68 65 20 69 4c 69 6d 69 74 20 e of the iLimit
39a10 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 parameter passed
39a20 20 74 6f 20 78 54 72 75 6e 63 61 74 65 28 29 2e to xTruncate().
39a30 20 49 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 If any.** of th
39a40 65 73 65 20 70 61 67 65 73 20 61 72 65 20 70 69 ese pages are pi
39a50 6e 6e 65 64 2c 20 74 68 65 79 20 61 72 65 20 69 nned, they are i
39a60 6d 70 6c 69 63 69 74 6c 79 20 75 6e 70 69 6e 6e mplicitly unpinn
39a70 65 64 2c 20 6d 65 61 6e 69 6e 67 20 74 68 61 74 ed, meaning that
39a80 0a 2a 2a 20 74 68 65 79 20 63 61 6e 20 62 65 20 .** they can be
39a90 73 61 66 65 6c 79 20 64 69 73 63 61 72 64 65 64 safely discarded
39aa0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 73 ..**.** The xDes
39ab0 74 72 6f 79 28 29 20 6d 65 74 68 6f 64 20 69 73 troy() method is
39ac0 20 75 73 65 64 20 74 6f 20 64 65 6c 65 74 65 20 used to delete
39ad0 61 20 63 61 63 68 65 20 61 6c 6c 6f 63 61 74 65 a cache allocate
39ae0 64 20 62 79 20 78 43 72 65 61 74 65 28 29 2e 0a d by xCreate()..
39af0 2a 2a 20 41 6c 6c 20 72 65 73 6f 75 72 63 65 73 ** All resources
39b00 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
39b10 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63 the specified c
39b20 61 63 68 65 20 73 68 6f 75 6c 64 20 62 65 20 66 ache should be f
39b30 72 65 65 64 2e 20 41 66 74 65 72 0a 2a 2a 20 63 reed. After.** c
39b40 61 6c 6c 69 6e 67 20 74 68 65 20 78 44 65 73 74 alling the xDest
39b50 72 6f 79 28 29 20 6d 65 74 68 6f 64 2c 20 53 51 roy() method, SQ
39b60 4c 69 74 65 20 63 6f 6e 73 69 64 65 72 73 20 74 Lite considers t
39b70 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 he [sqlite3_pcac
39b80 68 65 2a 5d 0a 2a 2a 20 68 61 6e 64 6c 65 20 69 he*].** handle i
39b90 6e 76 61 6c 69 64 2c 20 61 6e 64 20 77 69 6c 6c nvalid, and will
39ba0 20 6e 6f 74 20 75 73 65 20 69 74 20 77 69 74 68 not use it with
39bb0 20 61 6e 79 20 6f 74 68 65 72 20 73 71 6c 69 74 any other sqlit
39bc0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 e3_pcache_method
39bd0 73 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2e 0a s.** functions..
39be0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
39bf0 74 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 t sqlite3_pcache
39c00 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 _methods sqlite3
39c10 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3b _pcache_methods;
39c20 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
39c30 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 20 7b pcache_methods {
39c40 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 3b 0a 20 . void *pArg;.
39c50 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f int (*xInit)(vo
39c60 69 64 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 id*);. void (*x
39c70 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 Shutdown)(void*)
39c80 3b 0a 20 20 73 71 6c 69 74 65 33 5f 70 63 61 63 ;. sqlite3_pcac
39c90 68 65 20 2a 28 2a 78 43 72 65 61 74 65 29 28 69 he *(*xCreate)(i
39ca0 6e 74 20 73 7a 50 61 67 65 2c 20 69 6e 74 20 62 nt szPage, int b
39cb0 50 75 72 67 65 61 62 6c 65 29 3b 0a 20 20 76 6f Purgeable);. vo
39cc0 69 64 20 28 2a 78 43 61 63 68 65 73 69 7a 65 29 id (*xCachesize)
39cd0 28 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 2a (sqlite3_pcache*
39ce0 2c 20 69 6e 74 20 6e 43 61 63 68 65 73 69 7a 65 , int nCachesize
39cf0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 50 61 67 65 );. int (*xPage
39d00 63 6f 75 6e 74 29 28 73 71 6c 69 74 65 33 5f 70 count)(sqlite3_p
39d10 63 61 63 68 65 2a 29 3b 0a 20 20 76 6f 69 64 20 cache*);. void
39d20 2a 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 *(*xFetch)(sqlit
39d30 65 33 5f 70 63 61 63 68 65 2a 2c 20 75 6e 73 69 e3_pcache*, unsi
39d40 67 6e 65 64 20 6b 65 79 2c 20 69 6e 74 20 63 72 gned key, int cr
39d50 65 61 74 65 46 6c 61 67 29 3b 0a 20 20 76 6f 69 eateFlag);. voi
39d60 64 20 28 2a 78 55 6e 70 69 6e 29 28 73 71 6c 69 d (*xUnpin)(sqli
39d70 74 65 33 5f 70 63 61 63 68 65 2a 2c 20 76 6f 69 te3_pcache*, voi
39d80 64 2a 2c 20 69 6e 74 20 64 69 73 63 61 72 64 29 d*, int discard)
39d90 3b 0a 20 20 76 6f 69 64 20 28 2a 78 52 65 6b 65 ;. void (*xReke
39da0 79 29 28 73 71 6c 69 74 65 33 5f 70 63 61 63 68 y)(sqlite3_pcach
39db0 65 2a 2c 20 76 6f 69 64 2a 2c 20 75 6e 73 69 67 e*, void*, unsig
39dc0 6e 65 64 20 6f 6c 64 4b 65 79 2c 20 75 6e 73 69 ned oldKey, unsi
39dd0 67 6e 65 64 20 6e 65 77 4b 65 79 29 3b 0a 20 20 gned newKey);.
39de0 76 6f 69 64 20 28 2a 78 54 72 75 6e 63 61 74 65 void (*xTruncate
39df0 29 28 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 )(sqlite3_pcache
39e00 2a 2c 20 75 6e 73 69 67 6e 65 64 20 69 4c 69 6d *, unsigned iLim
39e10 69 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 it);. void (*xD
39e20 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f estroy)(sqlite3_
39e30 70 63 61 63 68 65 2a 29 3b 0a 7d 3b 0a 0a 2f 2a pcache*);.};../*
39e40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e .** CAPI3REF: On
39e50 6c 69 6e 65 20 42 61 63 6b 75 70 20 4f 62 6a 65 line Backup Obje
39e60 63 74 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 ct.** EXPERIMENT
39e70 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c AL.**.** The sql
39e80 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 ite3_backup obje
39e90 63 74 20 72 65 63 6f 72 64 73 20 73 74 61 74 65 ct records state
39ea0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f information abo
39eb0 75 74 20 61 6e 20 6f 6e 67 6f 69 6e 67 0a 2a 2a ut an ongoing.**
39ec0 20 6f 6e 6c 69 6e 65 20 62 61 63 6b 75 70 20 6f online backup o
39ed0 70 65 72 61 74 69 6f 6e 2e 20 20 54 68 65 20 73 peration. The s
39ee0 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 qlite3_backup ob
39ef0 6a 65 63 74 20 69 73 20 63 72 65 61 74 65 64 20 ject is created
39f00 62 79 0a 2a 2a 20 61 20 63 61 6c 6c 20 74 6f 20 by.** a call to
39f10 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f [sqlite3_backup_
39f20 69 6e 69 74 28 29 5d 20 61 6e 64 20 69 73 20 64 init()] and is d
39f30 65 73 74 72 6f 79 65 64 20 62 79 20 61 20 63 61 estroyed by a ca
39f40 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ll to.** [sqlite
39f50 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 3_backup_finish(
39f60 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c )]..**.** See Al
39f70 73 6f 3a 20 5b 55 73 69 6e 67 20 74 68 65 20 53 so: [Using the S
39f80 51 4c 69 74 65 20 4f 6e 6c 69 6e 65 20 42 61 63 QLite Online Bac
39f90 6b 75 70 20 41 50 49 5d 0a 2a 2f 0a 74 79 70 65 kup API].*/.type
39fa0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
39fb0 65 33 5f 62 61 63 6b 75 70 20 73 71 6c 69 74 65 e3_backup sqlite
39fc0 33 5f 62 61 63 6b 75 70 3b 0a 0a 2f 2a 0a 2a 2a 3_backup;../*.**
39fd0 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 6c 69 6e CAPI3REF: Onlin
39fe0 65 20 42 61 63 6b 75 70 20 41 50 49 2e 0a 2a 2a e Backup API..**
39ff0 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a EXPERIMENTAL.**
3a000 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 69 73 20 .** This API is
3a010 75 73 65 64 20 74 6f 20 6f 76 65 72 77 72 69 74 used to overwrit
3a020 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f e the contents o
3a030 66 20 6f 6e 65 20 64 61 74 61 62 61 73 65 20 77 f one database w
3a040 69 74 68 20 74 68 61 74 0a 2a 2a 20 6f 66 20 61 ith that.** of a
3a050 6e 6f 74 68 65 72 2e 20 49 74 20 69 73 20 75 73 nother. It is us
3a060 65 66 75 6c 20 65 69 74 68 65 72 20 66 6f 72 20 eful either for
3a070 63 72 65 61 74 69 6e 67 20 62 61 63 6b 75 70 73 creating backups
3a080 20 6f 66 20 64 61 74 61 62 61 73 65 73 20 6f 72 of databases or
3a090 0a 2a 2a 20 66 6f 72 20 63 6f 70 79 69 6e 67 20 .** for copying
3a0a0 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 in-memory databa
3a0b0 73 65 73 20 74 6f 20 6f 72 20 66 72 6f 6d 20 70 ses to or from p
3a0c0 65 72 73 69 73 74 65 6e 74 20 66 69 6c 65 73 2e ersistent files.
3a0d0 20 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 6f .**.** See Also
3a0e0 3a 20 5b 55 73 69 6e 67 20 74 68 65 20 53 51 4c : [Using the SQL
3a0f0 69 74 65 20 4f 6e 6c 69 6e 65 20 42 61 63 6b 75 ite Online Backu
3a100 70 20 41 50 49 5d 0a 2a 2a 0a 2a 2a 20 45 78 63 p API].**.** Exc
3a110 6c 75 73 69 76 65 20 61 63 63 65 73 73 20 69 73 lusive access is
3a120 20 72 65 71 75 69 72 65 64 20 74 6f 20 74 68 65 required to the
3a130 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 destination dat
3a140 61 62 61 73 65 20 66 6f 72 20 74 68 65 20 0a 2a abase for the .*
3a150 2a 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 * duration of th
3a160 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 48 6f 77 e operation. How
3a170 65 76 65 72 20 74 68 65 20 73 6f 75 72 63 65 20 ever the source
3a180 64 61 74 61 62 61 73 65 20 69 73 20 6f 6e 6c 79 database is only
3a190 0a 2a 2a 20 72 65 61 64 2d 6c 6f 63 6b 65 64 20 .** read-locked
3a1a0 77 68 69 6c 65 20 69 74 20 69 73 20 61 63 74 75 while it is actu
3a1b0 61 6c 6c 79 20 62 65 69 6e 67 20 72 65 61 64 2c ally being read,
3a1c0 20 69 74 20 69 73 20 6e 6f 74 20 6c 6f 63 6b 65 it is not locke
3a1d0 64 0a 2a 2a 20 63 6f 6e 74 69 6e 75 6f 75 73 6c d.** continuousl
3a1e0 79 20 66 6f 72 20 74 68 65 20 65 6e 74 69 72 65 y for the entire
3a1f0 20 6f 70 65 72 61 74 69 6f 6e 2e 20 54 68 75 73 operation. Thus
3a200 2c 20 74 68 65 20 62 61 63 6b 75 70 20 6d 61 79 , the backup may
3a210 20 62 65 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 be.** performed
3a220 20 6f 6e 20 61 20 6c 69 76 65 20 64 61 74 61 62 on a live datab
3a230 61 73 65 20 77 69 74 68 6f 75 74 20 70 72 65 76 ase without prev
3a240 65 6e 74 69 6e 67 20 6f 74 68 65 72 20 75 73 65 enting other use
3a250 72 73 20 66 72 6f 6d 0a 2a 2a 20 77 72 69 74 69 rs from.** writi
3a260 6e 67 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 ng to the databa
3a270 73 65 20 66 6f 72 20 61 6e 20 65 78 74 65 6e 64 se for an extend
3a280 65 64 20 70 65 72 69 6f 64 20 6f 66 20 74 69 6d ed period of tim
3a290 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 6f 20 70 65 72 e..** .** To per
3a2a0 66 6f 72 6d 20 61 20 62 61 63 6b 75 70 20 6f 70 form a backup op
3a2b0 65 72 61 74 69 6f 6e 3a 20 0a 2a 2a 20 20 20 3c eration: .** <
3a2c0 6f 6c 3e 0a 2a 2a 20 20 20 20 20 3c 6c 69 3e 3c ol>.** <li><
3a2d0 62 3e 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 b>sqlite3_backup
3a2e0 5f 69 6e 69 74 28 29 3c 2f 62 3e 20 69 73 20 63 _init()</b> is c
3a2f0 61 6c 6c 65 64 20 6f 6e 63 65 20 74 6f 20 69 6e alled once to in
3a300 69 74 69 61 6c 69 7a 65 20 74 68 65 0a 2a 2a 20 itialize the.**
3a310 20 20 20 20 20 20 20 20 62 61 63 6b 75 70 2c 20 backup,
3a320 0a 2a 2a 20 20 20 20 20 3c 6c 69 3e 3c 62 3e 73 .** <li><b>s
3a330 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 qlite3_backup_st
3a340 65 70 28 29 3c 2f 62 3e 20 69 73 20 63 61 6c 6c ep()</b> is call
3a350 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 ed one or more t
3a360 69 6d 65 73 20 74 6f 20 74 72 61 6e 73 66 65 72 imes to transfer
3a370 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 74 68 65 .** the
3a380 20 64 61 74 61 20 62 65 74 77 65 65 6e 20 74 68 data between th
3a390 65 20 74 77 6f 20 64 61 74 61 62 61 73 65 73 2c e two databases,
3a3a0 20 61 6e 64 20 66 69 6e 61 6c 6c 79 0a 2a 2a 20 and finally.**
3a3b0 20 20 20 20 3c 6c 69 3e 3c 62 3e 73 71 6c 69 74 <li><b>sqlit
3a3c0 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 e3_backup_finish
3a3d0 28 29 3c 2f 62 3e 20 69 73 20 63 61 6c 6c 65 64 ()</b> is called
3a3e0 20 74 6f 20 72 65 6c 65 61 73 65 20 61 6c 6c 20 to release all
3a3f0 72 65 73 6f 75 72 63 65 73 20 0a 2a 2a 20 20 20 resources .**
3a400 20 20 20 20 20 20 61 73 73 6f 63 69 61 74 65 64 associated
3a410 20 77 69 74 68 20 74 68 65 20 62 61 63 6b 75 70 with the backup
3a420 20 6f 70 65 72 61 74 69 6f 6e 2e 20 0a 2a 2a 20 operation. .**
3a430 20 20 3c 2f 6f 6c 3e 0a 2a 2a 20 54 68 65 72 65 </ol>.** There
3a440 20 73 68 6f 75 6c 64 20 62 65 20 65 78 61 63 74 should be exact
3a450 6c 79 20 6f 6e 65 20 63 61 6c 6c 20 74 6f 20 73 ly one call to s
3a460 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 qlite3_backup_fi
3a470 6e 69 73 68 28 29 20 66 6f 72 20 65 61 63 68 0a nish() for each.
3a480 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 ** successful ca
3a490 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 ll to sqlite3_ba
3a4a0 63 6b 75 70 5f 69 6e 69 74 28 29 2e 0a 2a 2a 0a ckup_init()..**.
3a4b0 2a 2a 20 3c 62 3e 73 71 6c 69 74 65 33 5f 62 61 ** <b>sqlite3_ba
3a4c0 63 6b 75 70 5f 69 6e 69 74 28 29 3c 2f 62 3e 0a ckup_init()</b>.
3a4d0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
3a4e0 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 70 61 two arguments pa
3a4f0 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 ssed to [sqlite3
3a500 5f 62 61 63 6b 75 70 5f 69 6e 69 74 28 29 5d 20 _backup_init()]
3a510 61 72 65 20 74 68 65 20 64 61 74 61 62 61 73 65 are the database
3a520 0a 2a 2a 20 68 61 6e 64 6c 65 20 61 73 73 6f 63 .** handle assoc
3a530 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64 iated with the d
3a540 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 estination datab
3a550 61 73 65 20 61 6e 64 20 74 68 65 20 64 61 74 61 ase and the data
3a560 62 61 73 65 20 6e 61 6d 65 20 0a 2a 2a 20 75 73 base name .** us
3a570 65 64 20 74 6f 20 61 74 74 61 63 68 20 74 68 65 ed to attach the
3a580 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 destination dat
3a590 61 62 61 73 65 20 74 6f 20 74 68 65 20 68 61 6e abase to the han
3a5a0 64 6c 65 2e 20 54 68 65 20 64 61 74 61 62 61 73 dle. The databas
3a5b0 65 20 6e 61 6d 65 0a 2a 2a 20 69 73 20 22 6d 61 e name.** is "ma
3a5c0 69 6e 22 20 66 6f 72 20 74 68 65 20 6d 61 69 6e in" for the main
3a5d0 20 64 61 74 61 62 61 73 65 2c 20 22 74 65 6d 70 database, "temp
3a5e0 22 20 66 6f 72 20 74 68 65 20 74 65 6d 70 6f 72 " for the tempor
3a5f0 61 72 79 20 64 61 74 61 62 61 73 65 2c 20 6f 72 ary database, or
3a600 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 73 70 65 .** the name spe
3a610 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f cified as part o
3a620 66 20 74 68 65 20 5b 41 54 54 41 43 48 5d 20 73 f the [ATTACH] s
3a630 74 61 74 65 6d 65 6e 74 20 69 66 20 74 68 65 20 tatement if the
3a640 64 65 73 74 69 6e 61 74 69 6f 6e 20 69 73 0a 2a destination is.*
3a650 2a 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 * an attached da
3a660 74 61 62 61 73 65 2e 20 54 68 65 20 74 68 69 72 tabase. The thir
3a670 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67 d and fourth arg
3a680 75 6d 65 6e 74 73 20 70 61 73 73 65 64 20 74 6f uments passed to
3a690 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 .** sqlite3_bac
3a6a0 6b 75 70 5f 69 6e 69 74 28 29 20 69 64 65 6e 74 kup_init() ident
3a6b0 69 66 79 20 74 68 65 20 5b 64 61 74 61 62 61 73 ify the [databas
3a6c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a e connection].**
3a6d0 20 61 6e 64 20 64 61 74 61 62 61 73 65 20 6e 61 and database na
3a6e0 6d 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 61 63 me used.** to ac
3a6f0 63 65 73 73 20 74 68 65 20 73 6f 75 72 63 65 20 cess the source
3a700 64 61 74 61 62 61 73 65 2e 20 54 68 65 20 76 61 database. The va
3a710 6c 75 65 73 20 70 61 73 73 65 64 20 66 6f 72 20 lues passed for
3a720 74 68 65 20 73 6f 75 72 63 65 20 61 6e 64 20 0a the source and .
3a730 2a 2a 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 5b ** destination [
3a740 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
3a750 69 6f 6e 5d 20 70 61 72 61 6d 65 74 65 72 73 20 ion] parameters
3a760 6d 75 73 74 20 6e 6f 74 20 62 65 20 74 68 65 20 must not be the
3a770 73 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 same..**.** If a
3a780 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 n error occurs w
3a790 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 62 61 ithin sqlite3_ba
3a7a0 63 6b 75 70 5f 69 6e 69 74 28 29 2c 20 74 68 65 ckup_init(), the
3a7b0 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e n NULL is return
3a7c0 65 64 0a 2a 2a 20 61 6e 64 20 61 6e 20 65 72 72 ed.** and an err
3a7d0 6f 72 20 63 6f 64 65 20 61 6e 64 20 65 72 72 6f or code and erro
3a7e0 72 20 6d 65 73 73 61 67 65 20 77 72 69 74 74 65 r message writte
3a7f0 6e 20 69 6e 74 6f 20 74 68 65 20 5b 64 61 74 61 n into the [data
3a800 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
3a810 20 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 .** passed as t
3a820 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
3a830 74 2e 20 54 68 65 79 20 6d 61 79 20 62 65 20 72 t. They may be r
3a840 65 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 74 etrieved using t
3a850 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 he.** [sqlite3_e
3a860 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69 rrcode()], [sqli
3a870 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 te3_errmsg()], a
3a880 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d nd [sqlite3_errm
3a890 73 67 31 36 28 29 5d 20 66 75 6e 63 74 69 6f 6e sg16()] function
3a8a0 73 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c s..** Otherwise,
3a8b0 20 69 66 20 73 75 63 63 65 73 73 66 75 6c 2c 20 if successful,
3a8c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
3a8d0 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d [sqlite3_backup]
3a8e0 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 72 65 object is.** re
3a8f0 74 75 72 6e 65 64 2e 20 54 68 69 73 20 70 6f 69 turned. This poi
3a900 6e 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 nter may be used
3a910 20 77 69 74 68 20 74 68 65 20 73 71 6c 69 74 65 with the sqlite
3a920 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 3_backup_step()
3a930 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 and.** sqlite3_b
3a940 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 29 20 66 ackup_finish() f
3a950 75 6e 63 74 69 6f 6e 73 20 74 6f 20 70 65 72 66 unctions to perf
3a960 6f 72 6d 20 74 68 65 20 73 70 65 63 69 66 69 65 orm the specifie
3a970 64 20 62 61 63 6b 75 70 20 0a 2a 2a 20 6f 70 65 d backup .** ope
3a980 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 62 ration..**.** <b
3a990 3e 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f >sqlite3_backup_
3a9a0 73 74 65 70 28 29 3c 2f 62 3e 0a 2a 2a 0a 2a 2a step()</b>.**.**
3a9b0 20 46 75 6e 63 74 69 6f 6e 20 5b 73 71 6c 69 74 Function [sqlit
3a9c0 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 e3_backup_step()
3a9d0 5d 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 70 ] is used to cop
3a9e0 79 20 75 70 20 74 6f 20 6e 50 61 67 65 20 70 61 y up to nPage pa
3a9f0 67 65 73 20 62 65 74 77 65 65 6e 20 0a 2a 2a 20 ges between .**
3aa00 74 68 65 20 73 6f 75 72 63 65 20 61 6e 64 20 64 the source and d
3aa10 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 estination datab
3aa20 61 73 65 73 2c 20 77 68 65 72 65 20 6e 50 61 67 ases, where nPag
3aa30 65 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f e is the value o
3aa40 66 20 74 68 65 20 0a 2a 2a 20 73 65 63 6f 6e 64 f the .** second
3aa50 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 parameter passe
3aa60 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 d to sqlite3_bac
3aa70 6b 75 70 5f 73 74 65 70 28 29 2e 20 49 66 20 6e kup_step(). If n
3aa80 50 61 67 65 20 69 73 20 61 20 6e 65 67 61 74 69 Page is a negati
3aa90 76 65 0a 2a 2a 20 76 61 6c 75 65 2c 20 61 6c 6c ve.** value, all
3aaa0 20 72 65 6d 61 69 6e 69 6e 67 20 73 6f 75 72 63 remaining sourc
3aab0 65 20 70 61 67 65 73 20 61 72 65 20 63 6f 70 69 e pages are copi
3aac0 65 64 2e 20 49 66 20 74 68 65 20 72 65 71 75 69 ed. If the requi
3aad0 72 65 64 20 70 61 67 65 73 20 61 72 65 20 0a 2a red pages are .*
3aae0 2a 20 73 75 63 63 65 73 66 75 6c 6c 79 20 63 6f * succesfully co
3aaf0 70 69 65 64 2c 20 62 75 74 20 74 68 65 72 65 20 pied, but there
3ab00 61 72 65 20 73 74 69 6c 6c 20 6d 6f 72 65 20 70 are still more p
3ab10 61 67 65 73 20 74 6f 20 63 6f 70 79 20 62 65 66 ages to copy bef
3ab20 6f 72 65 20 74 68 65 20 0a 2a 2a 20 62 61 63 6b ore the .** back
3ab30 75 70 20 69 73 20 63 6f 6d 70 6c 65 74 65 2c 20 up is complete,
3ab40 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 it returns [SQLI
3ab50 54 45 5f 4f 4b 5d 2e 20 49 66 20 6e 6f 20 65 72 TE_OK]. If no er
3ab60 72 6f 72 20 6f 63 63 75 72 65 64 20 61 6e 64 20 ror occured and
3ab70 74 68 65 72 65 20 0a 2a 2a 20 61 72 65 20 6e 6f there .** are no
3ab80 20 6d 6f 72 65 20 70 61 67 65 73 20 74 6f 20 63 more pages to c
3ab90 6f 70 79 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 opy, then [SQLIT
3aba0 45 5f 44 4f 4e 45 5d 20 69 73 20 72 65 74 75 72 E_DONE] is retur
3abb0 6e 65 64 2e 20 49 66 20 61 6e 20 65 72 72 6f 72 ned. If an error
3abc0 20 0a 2a 2a 20 6f 63 63 75 72 73 2c 20 74 68 65 .** occurs, the
3abd0 6e 20 61 6e 20 53 51 4c 69 74 65 20 65 72 72 6f n an SQLite erro
3abe0 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e r code is return
3abf0 65 64 2e 20 41 73 20 77 65 6c 6c 20 61 73 20 5b ed. As well as [
3ac00 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e 64 0a 2a SQLITE_OK] and.*
3ac10 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c * [SQLITE_DONE],
3ac20 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 a call to sqlit
3ac30 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 e3_backup_step()
3ac40 20 6d 61 79 20 72 65 74 75 72 6e 20 5b 53 51 4c may return [SQL
3ac50 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2c 0a 2a ITE_READONLY],.*
3ac60 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d * [SQLITE_NOMEM]
3ac70 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c , [SQLITE_BUSY],
3ac80 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5d [SQLITE_LOCKED]
3ac90 2c 20 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 , or an.** [SQLI
3aca0 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 TE_IOERR_ACCESS
3acb0 7c 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 58 | SQLITE_IOERR_X
3acc0 58 58 5d 20 65 78 74 65 6e 64 65 64 20 65 72 72 XX] extended err
3acd0 6f 72 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 41 or code..**.** A
3ace0 73 20 77 65 6c 6c 20 61 73 20 74 68 65 20 63 61 s well as the ca
3acf0 73 65 20 77 68 65 72 65 20 74 68 65 20 64 65 73 se where the des
3ad00 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 73 tination databas
3ad10 65 20 66 69 6c 65 20 77 61 73 20 6f 70 65 6e 65 e file was opene
3ad20 64 20 66 6f 72 0a 2a 2a 20 72 65 61 64 2d 6f 6e d for.** read-on
3ad30 6c 79 20 61 63 63 65 73 73 2c 20 73 71 6c 69 74 ly access, sqlit
3ad40 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 e3_backup_step()
3ad50 20 6d 61 79 20 72 65 74 75 72 6e 20 5b 53 51 4c may return [SQL
3ad60 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 20 69 66 ITE_READONLY] if
3ad70 0a 2a 2a 20 74 68 65 20 64 65 73 74 69 6e 61 74 .** the destinat
3ad80 69 6f 6e 20 69 73 20 61 6e 20 69 6e 2d 6d 65 6d ion is an in-mem
3ad90 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 74 ory database wit
3ada0 68 20 61 20 64 69 66 66 65 72 65 6e 74 20 70 61 h a different pa
3adb0 67 65 20 73 69 7a 65 0a 2a 2a 20 66 72 6f 6d 20 ge size.** from
3adc0 74 68 65 20 73 6f 75 72 63 65 20 64 61 74 61 62 the source datab
3add0 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 ase..**.** If sq
3ade0 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 lite3_backup_ste
3adf0 70 28 29 20 63 61 6e 6e 6f 74 20 6f 62 74 61 69 p() cannot obtai
3ae00 6e 20 61 20 72 65 71 75 69 72 65 64 20 66 69 6c n a required fil
3ae10 65 2d 73 79 73 74 65 6d 20 6c 6f 63 6b 2c 20 74 e-system lock, t
3ae20 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 hen.** the [sqli
3ae30 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 te3_busy_handler
3ae40 20 7c 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 | busy-handler
3ae50 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 69 73 20 function].** is
3ae60 69 6e 76 6f 6b 65 64 20 28 69 66 20 6f 6e 65 20 invoked (if one
3ae70 69 73 20 73 70 65 63 69 66 69 65 64 29 2e 20 49 is specified). I
3ae80 66 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 2d 68 f the .** busy-h
3ae90 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 6e andler returns n
3aea0 6f 6e 2d 7a 65 72 6f 20 62 65 66 6f 72 65 20 74 on-zero before t
3aeb0 68 65 20 6c 6f 63 6b 20 69 73 20 61 76 61 69 6c he lock is avail
3aec0 61 62 6c 65 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b able, then .** [
3aed0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20 SQLITE_BUSY] is
3aee0 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 returned to the
3aef0 63 61 6c 6c 65 72 2e 20 49 6e 20 74 68 69 73 20 caller. In this
3af00 63 61 73 65 20 74 68 65 20 63 61 6c 6c 20 74 6f case the call to
3af10 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 6b .** sqlite3_back
3af20 75 70 5f 73 74 65 70 28 29 20 63 61 6e 20 62 65 up_step() can be
3af30 20 72 65 74 72 69 65 64 20 6c 61 74 65 72 2e 20 retried later.
3af40 49 66 20 74 68 65 20 73 6f 75 72 63 65 0a 2a 2a If the source.**
3af50 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
3af60 63 74 69 6f 6e 5d 0a 2a 2a 20 69 73 20 62 65 69 ction].** is bei
3af70 6e 67 20 75 73 65 64 20 74 6f 20 77 72 69 74 65 ng used to write
3af80 20 74 6f 20 74 68 65 20 73 6f 75 72 63 65 20 64 to the source d
3af90 61 74 61 62 61 73 65 20 77 68 65 6e 20 73 71 6c atabase when sql
3afa0 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 ite3_backup_step
3afb0 28 29 0a 2a 2a 20 69 73 20 63 61 6c 6c 65 64 2c ().** is called,
3afc0 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 4c 4f then [SQLITE_LO
3afd0 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 CKED] is returne
3afe0 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 20 41 d immediately. A
3aff0 67 61 69 6e 2c 20 69 6e 20 74 68 69 73 0a 2a 2a gain, in this.**
3b000 20 63 61 73 65 20 74 68 65 20 63 61 6c 6c 20 74 case the call t
3b010 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 o sqlite3_backup
3b020 5f 73 74 65 70 28 29 20 63 61 6e 20 62 65 20 72 _step() can be r
3b030 65 74 72 69 65 64 20 6c 61 74 65 72 20 6f 6e 2e etried later on.
3b040 20 49 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 If.** [SQLITE_I
3b050 4f 45 52 52 5f 41 43 43 45 53 53 20 7c 20 53 51 OERR_ACCESS | SQ
3b060 4c 49 54 45 5f 49 4f 45 52 52 5f 58 58 58 5d 2c LITE_IOERR_XXX],
3b070 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c [SQLITE_NOMEM],
3b080 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 or.** [SQLITE_R
3b090 45 41 44 4f 4e 4c 59 5d 20 69 73 20 72 65 74 75 EADONLY] is retu
3b0a0 72 6e 65 64 2c 20 74 68 65 6e 20 0a 2a 2a 20 74 rned, then .** t
3b0b0 68 65 72 65 20 69 73 20 6e 6f 20 70 6f 69 6e 74 here is no point
3b0c0 20 69 6e 20 72 65 74 72 79 69 6e 67 20 74 68 65 in retrying the
3b0d0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
3b0e0 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 2e 20 _backup_step().
3b0f0 54 68 65 73 65 20 0a 2a 2a 20 65 72 72 6f 72 73 These .** errors
3b100 20 61 72 65 20 63 6f 6e 73 69 64 65 72 65 64 20 are considered
3b110 66 61 74 61 6c 2e 20 41 74 20 74 68 69 73 20 70 fatal. At this p
3b120 6f 69 6e 74 20 74 68 65 20 61 70 70 6c 69 63 61 oint the applica
3b130 74 69 6f 6e 20 6d 75 73 74 20 61 63 63 65 70 74 tion must accept
3b140 20 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 62 61 .** that the ba
3b150 63 6b 75 70 20 6f 70 65 72 61 74 69 6f 6e 20 68 ckup operation h
3b160 61 73 20 66 61 69 6c 65 64 20 61 6e 64 20 70 61 as failed and pa
3b170 73 73 20 74 68 65 20 62 61 63 6b 75 70 20 6f 70 ss the backup op
3b180 65 72 61 74 69 6f 6e 20 68 61 6e 64 6c 65 20 0a eration handle .
3b190 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 ** to the sqlite
3b1a0 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 3_backup_finish(
3b1b0 29 20 74 6f 20 72 65 6c 65 61 73 65 20 61 73 73 ) to release ass
3b1c0 6f 63 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 ociated resource
3b1d0 73 2e 0a 2a 2a 0a 2a 2a 20 46 6f 6c 6c 6f 77 69 s..**.** Followi
3b1e0 6e 67 20 74 68 65 20 66 69 72 73 74 20 63 61 6c ng the first cal
3b1f0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 l to sqlite3_bac
3b200 6b 75 70 5f 73 74 65 70 28 29 2c 20 61 6e 20 65 kup_step(), an e
3b210 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 20 69 73 xclusive lock is
3b220 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 6f 6e 20 .** obtained on
3b230 74 68 65 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 the destination
3b240 66 69 6c 65 2e 20 49 74 20 69 73 20 6e 6f 74 20 file. It is not
3b250 72 65 6c 65 61 73 65 64 20 75 6e 74 69 6c 20 65 released until e
3b260 69 74 68 65 72 20 0a 2a 2a 20 73 71 6c 69 74 65 ither .** sqlite
3b270 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 3_backup_finish(
3b280 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 72 20 74 ) is called or t
3b290 68 65 20 62 61 63 6b 75 70 20 6f 70 65 72 61 74 he backup operat
3b2a0 69 6f 6e 20 69 73 20 63 6f 6d 70 6c 65 74 65 20 ion is complete
3b2b0 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f .** and sqlite3_
3b2c0 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 72 65 backup_step() re
3b2d0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 4f turns [SQLITE_DO
3b2e0 4e 45 5d 2e 20 41 64 64 69 74 69 6f 6e 61 6c 6c NE]. Additionall
3b2f0 79 2c 20 65 61 63 68 20 74 69 6d 65 20 0a 2a 2a y, each time .**
3b300 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 a call to sqlit
3b310 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 e3_backup_step()
3b320 20 69 73 20 6d 61 64 65 20 61 20 5b 73 68 61 72 is made a [shar
3b330 65 64 20 6c 6f 63 6b 5d 20 69 73 20 6f 62 74 61 ed lock] is obta
3b340 69 6e 65 64 20 6f 6e 0a 2a 2a 20 74 68 65 20 73 ined on.** the s
3b350 6f 75 72 63 65 20 64 61 74 61 62 61 73 65 20 66 ource database f
3b360 69 6c 65 2e 20 54 68 69 73 20 6c 6f 63 6b 20 69 ile. This lock i
3b370 73 20 72 65 6c 65 61 73 65 64 20 62 65 66 6f 72 s released befor
3b380 65 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 e the.** sqlite3
3b390 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 63 _backup_step() c
3b3a0 61 6c 6c 20 72 65 74 75 72 6e 73 2e 20 42 65 63 all returns. Bec
3b3b0 61 75 73 65 20 74 68 65 20 73 6f 75 72 63 65 20 ause the source
3b3c0 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a database is not.
3b3d0 2a 2a 20 6c 6f 63 6b 65 64 20 62 65 74 77 65 65 ** locked betwee
3b3e0 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 n calls to sqlit
3b3f0 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 e3_backup_step()
3b400 2c 20 69 74 20 6d 61 79 20 62 65 20 6d 6f 64 69 , it may be modi
3b410 66 69 65 64 20 6d 69 64 2d 77 61 79 0a 2a 2a 20 fied mid-way.**
3b420 74 68 72 6f 75 67 68 20 74 68 65 20 62 61 63 6b through the back
3b430 75 70 20 70 72 6f 63 65 64 75 72 65 2e 20 49 66 up procedure. If
3b440 20 74 68 65 20 73 6f 75 72 63 65 20 64 61 74 61 the source data
3b450 62 61 73 65 20 69 73 20 6d 6f 64 69 66 69 65 64 base is modified
3b460 20 62 79 20 61 6e 0a 2a 2a 20 65 78 74 65 72 6e by an.** extern
3b470 61 6c 20 70 72 6f 63 65 73 73 20 6f 72 20 76 69 al process or vi
3b480 61 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e a a database con
3b490 6e 65 63 74 69 6f 6e 20 6f 74 68 65 72 20 74 68 nection other th
3b4a0 61 6e 20 74 68 65 20 6f 6e 65 20 62 65 69 6e 67 an the one being
3b4b0 0a 2a 2a 20 75 73 65 64 20 62 79 20 74 68 65 20 .** used by the
3b4c0 62 61 63 6b 75 70 20 6f 70 65 72 61 74 69 6f 6e backup operation
3b4d0 2c 20 74 68 65 6e 20 74 68 65 20 62 61 63 6b 75 , then the backu
3b4e0 70 20 77 69 6c 6c 20 62 65 20 74 72 61 6e 73 70 p will be transp
3b4f0 61 72 65 6e 74 6c 79 0a 2a 2a 20 72 65 73 74 61 arently.** resta
3b500 72 74 65 64 20 62 79 20 74 68 65 20 6e 65 78 74 rted by the next
3b510 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
3b520 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 2e 20 _backup_step().
3b530 49 66 20 74 68 65 20 73 6f 75 72 63 65 20 0a 2a If the source .*
3b540 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 6d 6f * database is mo
3b550 64 69 66 69 65 64 20 62 79 20 74 68 65 20 75 73 dified by the us
3b560 69 6e 67 20 74 68 65 20 73 61 6d 65 20 64 61 74 ing the same dat
3b570 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
3b580 20 61 73 20 69 73 20 75 73 65 64 0a 2a 2a 20 62 as is used.** b
3b590 79 20 74 68 65 20 62 61 63 6b 75 70 20 6f 70 65 y the backup ope
3b5a0 72 61 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 ration, then the
3b5b0 20 62 61 63 6b 75 70 20 64 61 74 61 62 61 73 65 backup database
3b5c0 20 69 73 20 74 72 61 6e 73 70 61 72 65 6e 74 6c is transparentl
3b5d0 79 20 0a 2a 2a 20 75 70 64 61 74 65 64 20 61 74 y .** updated at
3b5e0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a the same time..
3b5f0 2a 2a 0a 2a 2a 20 3c 62 3e 73 71 6c 69 74 65 33 **.** <b>sqlite3
3b600 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 29 _backup_finish()
3b610 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 63 65 20 </b>.**.** Once
3b620 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 sqlite3_backup_s
3b630 74 65 70 28 29 20 68 61 73 20 72 65 74 75 72 6e tep() has return
3b640 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d ed [SQLITE_DONE]
3b650 2c 20 6f 72 20 77 68 65 6e 20 74 68 65 20 0a 2a , or when the .*
3b660 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 69 * application wi
3b670 73 68 65 73 20 74 6f 20 61 62 61 6e 64 6f 6e 20 shes to abandon
3b680 74 68 65 20 62 61 63 6b 75 70 20 6f 70 65 72 61 the backup opera
3b690 74 69 6f 6e 2c 20 74 68 65 20 5b 73 71 6c 69 74 tion, the [sqlit
3b6a0 65 33 5f 62 61 63 6b 75 70 5d 0a 2a 2a 20 6f 62 e3_backup].** ob
3b6b0 6a 65 63 74 20 73 68 6f 75 6c 64 20 62 65 20 70 ject should be p
3b6c0 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 assed to sqlite3
3b6d0 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 29 _backup_finish()
3b6e0 2e 20 54 68 69 73 20 72 65 6c 65 61 73 65 73 20 . This releases
3b6f0 61 6c 6c 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 all.** resources
3b700 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
3b710 20 74 68 65 20 62 61 63 6b 75 70 20 6f 70 65 72 the backup oper
3b720 61 74 69 6f 6e 2e 20 49 66 20 73 71 6c 69 74 65 ation. If sqlite
3b730 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 0a 3_backup_step().
3b740 2a 2a 20 68 61 73 20 6e 6f 74 20 79 65 74 20 72 ** has not yet r
3b750 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f eturned [SQLITE_
3b760 44 4f 4e 45 5d 2c 20 74 68 65 6e 20 61 6e 79 20 DONE], then any
3b770 61 63 74 69 76 65 20 77 72 69 74 65 2d 74 72 61 active write-tra
3b780 6e 73 61 63 74 69 6f 6e 20 6f 6e 20 74 68 65 0a nsaction on the.
3b790 2a 2a 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 ** destination d
3b7a0 61 74 61 62 61 73 65 20 69 73 20 72 6f 6c 6c 65 atabase is rolle
3b7b0 64 20 62 61 63 6b 2e 20 54 68 65 20 5b 73 71 6c d back. The [sql
3b7c0 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a ite3_backup] obj
3b7d0 65 63 74 20 69 73 20 69 6e 76 61 6c 69 64 0a 2a ect is invalid.*
3b7e0 2a 20 61 6e 64 20 6d 61 79 20 6e 6f 74 20 62 65 * and may not be
3b7f0 20 75 73 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 used following
3b800 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 a call to sqlite
3b810 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 3_backup_finish(
3b820 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c )..**.** The val
3b830 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ue returned by s
3b840 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 qlite3_backup_fi
3b850 6e 69 73 68 20 69 73 20 5b 53 51 4c 49 54 45 5f nish is [SQLITE_
3b860 4f 4b 5d 20 69 66 20 6e 6f 20 65 72 72 6f 72 0a OK] if no error.
3b870 2a 2a 20 6f 63 63 75 72 72 65 64 2c 20 72 65 67 ** occurred, reg
3b880 61 72 64 6c 65 73 73 20 6f 72 20 77 68 65 74 68 ardless or wheth
3b890 65 72 20 6f 72 20 6e 6f 74 20 73 71 6c 69 74 65 er or not sqlite
3b8a0 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 3_backup_step()
3b8b0 77 61 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 61 20 was called.** a
3b8c0 73 75 66 66 69 63 69 65 6e 74 20 6e 75 6d 62 65 sufficient numbe
3b8d0 72 20 6f 66 20 74 69 6d 65 73 20 74 6f 20 63 6f r of times to co
3b8e0 6d 70 6c 65 74 65 20 74 68 65 20 62 61 63 6b 75 mplete the backu
3b8f0 70 20 6f 70 65 72 61 74 69 6f 6e 2e 20 4f 72 2c p operation. Or,
3b900 20 69 66 0a 2a 2a 20 61 6e 20 6f 75 74 2d 6f 66 if.** an out-of
3b910 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f -memory conditio
3b920 6e 20 6f 72 20 49 4f 20 65 72 72 6f 72 20 6f 63 n or IO error oc
3b930 63 75 72 65 64 20 64 75 72 69 6e 67 20 61 20 63 cured during a c
3b940 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 all to.** sqlite
3b950 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 3_backup_step()
3b960 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d then [SQLITE_NOM
3b970 45 4d 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 EM] or an.** [SQ
3b980 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 LITE_IOERR_ACCES
3b990 53 20 7c 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 S | SQLITE_IOERR
3b9a0 5f 58 58 58 5d 20 65 72 72 6f 72 20 63 6f 64 65 _XXX] error code
3b9b0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e .** is returned.
3b9c0 20 49 6e 20 74 68 69 73 20 63 61 73 65 20 74 68 In this case th
3b9d0 65 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 e error code and
3b9e0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 an error messag
3b9f0 65 20 61 72 65 0a 2a 2a 20 77 72 69 74 74 65 6e e are.** written
3ba00 20 74 6f 20 74 68 65 20 64 65 73 74 69 6e 61 74 to the destinat
3ba10 69 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f ion [database co
3ba20 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a nnection]..**.**
3ba30 20 41 20 72 65 74 75 72 6e 20 6f 66 20 5b 53 51 A return of [SQ
3ba40 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 LITE_BUSY] or [S
3ba50 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5d 20 66 72 QLITE_LOCKED] fr
3ba60 6f 6d 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 om sqlite3_backu
3ba70 70 5f 73 74 65 70 28 29 20 69 73 0a 2a 2a 20 6e p_step() is.** n
3ba80 6f 74 20 61 20 70 65 72 6d 61 6e 65 6e 74 20 65 ot a permanent e
3ba90 72 72 6f 72 20 61 6e 64 20 64 6f 65 73 20 6e 6f rror and does no
3baa0 74 20 61 66 66 65 63 74 20 74 68 65 20 72 65 74 t affect the ret
3bab0 75 72 6e 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 urn value of.**
3bac0 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 sqlite3_backup_f
3bad0 69 6e 69 73 68 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c inish()..**.** <
3bae0 62 3e 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 b>sqlite3_backup
3baf0 5f 72 65 6d 61 69 6e 69 6e 67 28 29 2c 20 73 71 _remaining(), sq
3bb00 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 70 61 67 lite3_backup_pag
3bb10 65 63 6f 75 6e 74 28 29 3c 2f 62 3e 0a 2a 2a 0a ecount()</b>.**.
3bb20 2a 2a 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 ** Each call to
3bb30 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 sqlite3_backup_s
3bb40 74 65 70 28 29 20 73 65 74 73 20 74 77 6f 20 76 tep() sets two v
3bb50 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 74 alues stored int
3bb60 65 72 6e 61 6c 6c 79 0a 2a 2a 20 62 79 20 61 6e ernally.** by an
3bb70 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 [sqlite3_backup
3bb80 5d 20 6f 62 6a 65 63 74 2e 20 54 68 65 20 6e 75 ] object. The nu
3bb90 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 73 74 mber of pages st
3bba0 69 6c 6c 20 74 6f 20 62 65 20 62 61 63 6b 65 64 ill to be backed
3bbb0 0a 2a 2a 20 75 70 2c 20 77 68 69 63 68 20 6d 61 .** up, which ma
3bbc0 79 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20 y be queried by
3bbd0 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 72 sqlite3_backup_r
3bbe0 65 6d 61 69 6e 69 6e 67 28 29 2c 20 61 6e 64 20 emaining(), and
3bbf0 74 68 65 20 74 6f 74 61 6c 0a 2a 2a 20 6e 75 6d the total.** num
3bc00 62 65 72 20 6f 66 20 70 61 67 65 73 20 69 6e 20 ber of pages in
3bc10 74 68 65 20 73 6f 75 72 63 65 20 64 61 74 61 62 the source datab
3bc20 61 73 65 20 66 69 6c 65 2c 20 77 68 69 63 68 20 ase file, which
3bc30 6d 61 79 20 62 65 20 71 75 65 72 69 65 64 20 62 may be queried b
3bc40 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 y.** sqlite3_bac
3bc50 6b 75 70 5f 70 61 67 65 63 6f 75 6e 74 28 29 2e kup_pagecount().
3bc60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 .**.** The value
3bc70 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 s returned by th
3bc80 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 ese functions ar
3bc90 65 20 6f 6e 6c 79 20 75 70 64 61 74 65 64 20 62 e only updated b
3bca0 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 y.** sqlite3_bac
3bcb0 6b 75 70 5f 73 74 65 70 28 29 2e 20 49 66 20 74 kup_step(). If t
3bcc0 68 65 20 73 6f 75 72 63 65 20 64 61 74 61 62 61 he source databa
3bcd0 73 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64 se is modified d
3bce0 75 72 69 6e 67 20 61 20 62 61 63 6b 75 70 0a 2a uring a backup.*
3bcf0 2a 20 6f 70 65 72 61 74 69 6f 6e 2c 20 74 68 65 * operation, the
3bd00 6e 20 74 68 65 20 76 61 6c 75 65 73 20 61 72 65 n the values are
3bd10 20 6e 6f 74 20 75 70 64 61 74 65 64 20 74 6f 20 not updated to
3bd20 61 63 63 6f 75 6e 74 20 66 6f 72 20 61 6e 79 20 account for any
3bd30 65 78 74 72 61 0a 2a 2a 20 70 61 67 65 73 20 74 extra.** pages t
3bd40 68 61 74 20 6e 65 65 64 20 74 6f 20 62 65 20 75 hat need to be u
3bd50 70 64 61 74 65 64 20 6f 72 20 74 68 65 20 73 69 pdated or the si
3bd60 7a 65 20 6f 66 20 74 68 65 20 73 6f 75 72 63 65 ze of the source
3bd70 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a database file.*
3bd80 2a 20 63 68 61 6e 67 69 6e 67 2e 0a 2a 2a 0a 2a * changing..**.*
3bd90 2a 20 3c 62 3e 43 6f 6e 63 75 72 72 65 6e 74 20 * <b>Concurrent
3bda0 55 73 61 67 65 20 6f 66 20 44 61 74 61 62 61 73 Usage of Databas
3bdb0 65 20 48 61 6e 64 6c 65 73 3c 2f 62 3e 0a 2a 2a e Handles</b>.**
3bdc0 0a 2a 2a 20 54 68 65 20 73 6f 75 72 63 65 20 5b .** The source [
3bdd0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
3bde0 69 6f 6e 5d 20 6d 61 79 20 62 65 20 75 73 65 64 ion] may be used
3bdf0 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 by the applicat
3be00 69 6f 6e 20 66 6f 72 20 6f 74 68 65 72 0a 2a 2a ion for other.**
3be10 20 70 75 72 70 6f 73 65 73 20 77 68 69 6c 65 20 purposes while
3be20 61 20 62 61 63 6b 75 70 20 6f 70 65 72 61 74 69 a backup operati
3be30 6f 6e 20 69 73 20 75 6e 64 65 72 77 61 79 20 6f on is underway o
3be40 72 20 62 65 69 6e 67 20 69 6e 69 74 69 61 6c 69 r being initiali
3be50 7a 65 64 2e 0a 2a 2a 20 49 66 20 53 51 4c 69 74 zed..** If SQLit
3be60 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 61 6e e is compiled an
3be70 64 20 63 6f 6e 66 69 67 75 72 65 64 20 74 6f 20 d configured to
3be80 73 75 70 70 6f 72 74 20 74 68 72 65 61 64 73 61 support threadsa
3be90 66 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 fe database.** c
3bea0 6f 6e 6e 65 63 74 69 6f 6e 73 2c 20 74 68 65 6e onnections, then
3beb0 20 74 68 65 20 73 6f 75 72 63 65 20 64 61 74 61 the source data
3bec0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
3bed0 6d 61 79 20 62 65 20 75 73 65 64 20 63 6f 6e 63 may be used conc
3bee0 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 66 72 6f 6d urrently.** from
3bef0 20 77 69 74 68 69 6e 20 6f 74 68 65 72 20 74 68 within other th
3bf00 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 48 6f 77 reads..**.** How
3bf10 65 76 65 72 2c 20 74 68 65 20 61 70 70 6c 69 63 ever, the applic
3bf20 61 74 69 6f 6e 20 6d 75 73 74 20 67 75 61 72 61 ation must guara
3bf30 6e 74 65 65 20 74 68 61 74 20 74 68 65 20 64 65 ntee that the de
3bf40 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 stination databa
3bf50 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e se.** connection
3bf60 20 68 61 6e 64 6c 65 20 69 73 20 6e 6f 74 20 70 handle is not p
3bf70 61 73 73 65 64 20 74 6f 20 61 6e 79 20 6f 74 68 assed to any oth
3bf80 65 72 20 41 50 49 20 28 62 79 20 61 6e 79 20 74 er API (by any t
3bf90 68 72 65 61 64 29 20 61 66 74 65 72 20 0a 2a 2a hread) after .**
3bfa0 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f sqlite3_backup_
3bfb0 69 6e 69 74 28 29 20 69 73 20 63 61 6c 6c 65 64 init() is called
3bfc0 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 and before the
3bfd0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 63 61 corresponding ca
3bfe0 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 ll to.** sqlite3
3bff0 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 29 _backup_finish()
3c000 2e 20 55 6e 66 6f 72 74 75 6e 61 74 65 6c 79 20 . Unfortunately
3c010 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 SQLite does not
3c020 63 75 72 72 65 6e 74 6c 79 20 63 68 65 63 6b 0a currently check.
3c030 2a 2a 20 66 6f 72 20 74 68 69 73 2c 20 69 66 20 ** for this, if
3c040 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
3c050 64 6f 65 73 20 75 73 65 20 74 68 65 20 64 65 73 does use the des
3c060 74 69 6e 61 74 69 6f 6e 20 5b 64 61 74 61 62 61 tination [databa
3c070 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a se connection].*
3c080 2a 20 66 6f 72 20 73 6f 6d 65 20 6f 74 68 65 72 * for some other
3c090 20 70 75 72 70 6f 73 65 20 64 75 72 69 6e 67 20 purpose during
3c0a0 61 20 62 61 63 6b 75 70 20 6f 70 65 72 61 74 69 a backup operati
3c0b0 6f 6e 2c 20 74 68 69 6e 67 73 20 6d 61 79 20 61 on, things may a
3c0c0 70 70 65 61 72 20 74 6f 0a 2a 2a 20 77 6f 72 6b ppear to.** work
3c0d0 20 63 6f 72 72 65 63 74 6c 79 20 62 75 74 20 69 correctly but i
3c0e0 6e 20 66 61 63 74 20 62 65 20 73 75 62 74 6c 79 n fact be subtly
3c0f0 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 69 6e 67 2e malfunctioning.
3c100 20 20 55 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 Use of the.**
3c110 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 destination data
3c120 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
3c130 77 68 69 6c 65 20 61 20 62 61 63 6b 75 70 20 69 while a backup i
3c140 73 20 69 6e 20 70 72 6f 67 72 65 73 73 20 6d 69 s in progress mi
3c150 67 68 74 0a 2a 2a 20 61 6c 73 6f 20 63 61 75 73 ght.** also caus
3c160 65 20 61 20 6d 75 74 65 78 20 64 65 61 64 6c 6f e a mutex deadlo
3c170 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 75 72 74 68 65 ck..**.** Furthe
3c180 72 6d 6f 72 65 2c 20 69 66 20 72 75 6e 6e 69 6e rmore, if runnin
3c190 67 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 g in [shared cac
3c1a0 68 65 20 6d 6f 64 65 5d 2c 20 74 68 65 20 61 70 he mode], the ap
3c1b0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 0a 2a plication must.*
3c1c0 2a 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 * guarantee that
3c1d0 20 74 68 65 20 73 68 61 72 65 64 20 63 61 63 68 the shared cach
3c1e0 65 20 75 73 65 64 20 62 79 20 74 68 65 20 64 65 e used by the de
3c1f0 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 stination databa
3c200 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 63 63 se.** is not acc
3c210 65 73 73 65 64 20 77 68 69 6c 65 20 74 68 65 20 essed while the
3c220 62 61 63 6b 75 70 20 69 73 20 72 75 6e 6e 69 6e backup is runnin
3c230 67 2e 20 49 6e 20 70 72 61 63 74 69 63 65 20 74 g. In practice t
3c240 68 69 73 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 his means.** tha
3c250 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f t the applicatio
3c260 6e 20 6d 75 73 74 20 67 75 61 72 61 6e 74 65 65 n must guarantee
3c270 20 74 68 61 74 20 74 68 65 20 66 69 6c 65 2d 73 that the file-s
3c280 79 73 74 65 6d 20 66 69 6c 65 20 62 65 69 6e 67 ystem file being
3c290 20 0a 2a 2a 20 62 61 63 6b 65 64 20 75 70 20 74 .** backed up t
3c2a0 6f 20 69 73 20 6e 6f 74 20 61 63 63 65 73 73 65 o is not accesse
3c2b0 64 20 62 79 20 61 6e 79 20 63 6f 6e 6e 65 63 74 d by any connect
3c2c0 69 6f 6e 20 77 69 74 68 69 6e 20 74 68 65 20 70 ion within the p
3c2d0 72 6f 63 65 73 73 2c 0a 2a 2a 20 6e 6f 74 20 6a rocess,.** not j
3c2e0 75 73 74 20 74 68 65 20 73 70 65 63 69 66 69 63 ust the specific
3c2f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 connection that
3c300 20 77 61 73 20 70 61 73 73 65 64 20 74 6f 20 73 was passed to s
3c310 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 69 6e qlite3_backup_in
3c320 69 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 it()..**.** The
3c330 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d [sqlite3_backup]
3c340 20 6f 62 6a 65 63 74 20 69 74 73 65 6c 66 20 69 object itself i
3c350 73 20 70 61 72 74 69 61 6c 6c 79 20 74 68 72 65 s partially thre
3c360 61 64 73 61 66 65 2e 20 4d 75 6c 74 69 70 6c 65 adsafe. Multiple
3c370 20 0a 2a 2a 20 74 68 72 65 61 64 73 20 6d 61 79 .** threads may
3c380 20 73 61 66 65 6c 79 20 6d 61 6b 65 20 6d 75 6c safely make mul
3c390 74 69 70 6c 65 20 63 6f 6e 63 75 72 72 65 6e 74 tiple concurrent
3c3a0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 calls to sqlite
3c3b0 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 2e 3_backup_step().
3c3c0 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 .** However, the
3c3d0 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f sqlite3_backup_
3c3e0 72 65 6d 61 69 6e 69 6e 67 28 29 20 61 6e 64 20 remaining() and
3c3f0 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 70 sqlite3_backup_p
3c400 61 67 65 63 6f 75 6e 74 28 29 0a 2a 2a 20 41 50 agecount().** AP
3c410 49 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 Is are not stric
3c420 74 6c 79 20 73 70 65 61 6b 69 6e 67 20 74 68 72 tly speaking thr
3c430 65 61 64 73 61 66 65 2e 20 49 66 20 74 68 65 79 eadsafe. If they
3c440 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 61 74 20 are invoked at
3c450 74 68 65 0a 2a 2a 20 73 61 6d 65 20 74 69 6d 65 the.** same time
3c460 20 61 73 20 61 6e 6f 74 68 65 72 20 74 68 72 65 as another thre
3c470 61 64 20 69 73 20 69 6e 76 6f 6b 69 6e 67 20 73 ad is invoking s
3c480 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 qlite3_backup_st
3c490 65 70 28 29 20 69 74 20 69 73 0a 2a 2a 20 70 6f ep() it is.** po
3c4a0 73 73 69 62 6c 65 20 74 68 61 74 20 74 68 65 79 ssible that they
3c4b0 20 72 65 74 75 72 6e 20 69 6e 76 61 6c 69 64 20 return invalid
3c4c0 76 61 6c 75 65 73 2e 0a 2a 2f 0a 73 71 6c 69 74 values..*/.sqlit
3c4d0 65 33 5f 62 61 63 6b 75 70 20 2a 73 71 6c 69 74 e3_backup *sqlit
3c4e0 65 33 5f 62 61 63 6b 75 70 5f 69 6e 69 74 28 0a e3_backup_init(.
3c4f0 20 20 73 71 6c 69 74 65 33 20 2a 70 44 65 73 74 sqlite3 *pDest
3c500 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
3c510 20 20 20 20 20 20 20 20 20 2f 2a 20 44 65 73 74 /* Dest
3c520 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 73 65 ination database
3c530 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
3c540 73 74 20 63 68 61 72 20 2a 7a 44 65 73 74 4e 61 st char *zDestNa
3c550 6d 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 me,
3c560 20 20 20 20 2f 2a 20 44 65 73 74 69 6e 61 74 69 /* Destinati
3c570 6f 6e 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 on database name
3c580 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 70 */. sqlite3 *p
3c590 53 6f 75 72 63 65 2c 20 20 20 20 20 20 20 20 20 Source,
3c5a0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
3c5b0 53 6f 75 72 63 65 20 64 61 74 61 62 61 73 65 20 Source database
3c5c0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
3c5d0 74 20 63 68 61 72 20 2a 7a 53 6f 75 72 63 65 4e t char *zSourceN
3c5e0 61 6d 65 20 20 20 20 20 20 20 20 20 20 20 20 20 ame
3c5f0 20 20 20 2f 2a 20 53 6f 75 72 63 65 20 64 61 74 /* Source dat
3c600 61 62 61 73 65 20 6e 61 6d 65 20 2a 2f 0a 29 3b abase name */.);
3c610 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 61 63 .int sqlite3_bac
3c620 6b 75 70 5f 73 74 65 70 28 73 71 6c 69 74 65 33 kup_step(sqlite3
3c630 5f 62 61 63 6b 75 70 20 2a 70 2c 20 69 6e 74 20 _backup *p, int
3c640 6e 50 61 67 65 29 3b 0a 69 6e 74 20 73 71 6c 69 nPage);.int sqli
3c650 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 te3_backup_finis
3c660 68 28 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 h(sqlite3_backup
3c670 20 2a 70 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 *p);.int sqlite
3c680 33 5f 62 61 63 6b 75 70 5f 72 65 6d 61 69 6e 69 3_backup_remaini
3c690 6e 67 28 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 ng(sqlite3_backu
3c6a0 70 20 2a 70 29 3b 0a 69 6e 74 20 73 71 6c 69 74 p *p);.int sqlit
3c6b0 65 33 5f 62 61 63 6b 75 70 5f 70 61 67 65 63 6f e3_backup_pageco
3c6c0 75 6e 74 28 73 71 6c 69 74 65 33 5f 62 61 63 6b unt(sqlite3_back
3c6d0 75 70 20 2a 70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 up *p);../*.** C
3c6e0 41 50 49 33 52 45 46 3a 20 55 6e 6c 6f 63 6b 20 API3REF: Unlock
3c6f0 4e 6f 74 69 66 69 63 61 74 69 6f 6e 0a 2a 2a 20 Notification.**
3c700 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a EXPERIMENTAL.**.
3c710 2a 2a 20 57 68 65 6e 20 72 75 6e 6e 69 6e 67 20 ** When running
3c720 69 6e 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 in shared-cache
3c730 6d 6f 64 65 2c 20 61 20 64 61 74 61 62 61 73 65 mode, a database
3c740 20 6f 70 65 72 61 74 69 6f 6e 20 6d 61 79 20 66 operation may f
3c750 61 69 6c 20 77 69 74 68 0a 2a 2a 20 61 6e 20 5b ail with.** an [
3c760 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5d 20 65 SQLITE_LOCKED] e
3c770 72 72 6f 72 20 69 66 20 74 68 65 20 72 65 71 75 rror if the requ
3c780 69 72 65 64 20 6c 6f 63 6b 73 20 6f 6e 20 74 68 ired locks on th
3c790 65 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6f e shared-cache o
3c7a0 72 0a 2a 2a 20 69 6e 64 69 76 69 64 75 61 6c 20 r.** individual
3c7b0 74 61 62 6c 65 73 20 77 69 74 68 69 6e 20 74 68 tables within th
3c7c0 65 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 63 e shared-cache c
3c7d0 61 6e 6e 6f 74 20 62 65 20 6f 62 74 61 69 6e 65 annot be obtaine
3c7e0 64 2e 20 53 65 65 0a 2a 2a 20 5b 53 51 4c 69 74 d. See.** [SQLit
3c7f0 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 20 4d e Shared-Cache M
3c800 6f 64 65 5d 20 66 6f 72 20 61 20 64 65 73 63 72 ode] for a descr
3c810 69 70 74 69 6f 6e 20 6f 66 20 73 68 61 72 65 64 iption of shared
3c820 2d 63 61 63 68 65 20 6c 6f 63 6b 69 6e 67 2e 20 -cache locking.
3c830 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 6d 61 79 .** This API may
3c840 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 67 69 be used to regi
3c850 73 74 65 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 ster a callback
3c860 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c that SQLite will
3c870 20 69 6e 76 6f 6b 65 20 0a 2a 2a 20 77 68 65 6e invoke .** when
3c880 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 the connection
3c890 63 75 72 72 65 6e 74 6c 79 20 68 6f 6c 64 69 6e currently holdin
3c8a0 67 20 74 68 65 20 72 65 71 75 69 72 65 64 20 6c g the required l
3c8b0 6f 63 6b 20 72 65 6c 69 6e 71 75 69 73 68 65 73 ock relinquishes
3c8c0 20 69 74 2e 0a 2a 2a 20 54 68 69 73 20 41 50 49 it..** This API
3c8d0 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 is only availab
3c8e0 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 le if the librar
3c8f0 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 y was compiled w
3c900 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 ith the.** [SQLI
3c910 54 45 5f 45 4e 41 42 4c 45 5f 55 4e 4c 4f 43 4b TE_ENABLE_UNLOCK
3c920 5f 4e 4f 54 49 46 59 5d 20 43 2d 70 72 65 70 72 _NOTIFY] C-prepr
3c930 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 ocessor symbol d
3c940 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 efined..**.** Se
3c950 65 20 41 6c 73 6f 3a 20 5b 55 73 69 6e 67 20 74 e Also: [Using t
3c960 68 65 20 53 51 4c 69 74 65 20 55 6e 6c 6f 63 6b he SQLite Unlock
3c970 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 46 65 Notification Fe
3c980 61 74 75 72 65 5d 2e 0a 2a 2a 0a 2a 2a 20 53 68 ature]..**.** Sh
3c990 61 72 65 64 2d 63 61 63 68 65 20 6c 6f 63 6b 73 ared-cache locks
3c9a0 20 61 72 65 20 72 65 6c 65 61 73 65 64 20 77 68 are released wh
3c9b0 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f en a database co
3c9c0 6e 6e 65 63 74 69 6f 6e 20 63 6f 6e 63 6c 75 64 nnection conclud
3c9d0 65 73 0a 2a 2a 20 69 74 73 20 63 75 72 72 65 6e es.** its curren
3c9e0 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 65 t transaction, e
3c9f0 69 74 68 65 72 20 62 79 20 63 6f 6d 6d 69 74 74 ither by committ
3ca00 69 6e 67 20 69 74 20 6f 72 20 72 6f 6c 6c 69 6e ing it or rollin
3ca10 67 20 69 74 20 62 61 63 6b 2e 20 0a 2a 2a 0a 2a g it back. .**.*
3ca20 2a 20 57 68 65 6e 20 61 20 63 6f 6e 6e 65 63 74 * When a connect
3ca30 69 6f 6e 20 28 6b 6e 6f 77 6e 20 61 73 20 74 68 ion (known as th
3ca40 65 20 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e 65 63 e blocked connec
3ca50 74 69 6f 6e 29 20 66 61 69 6c 73 20 74 6f 20 6f tion) fails to o
3ca60 62 74 61 69 6e 20 61 0a 2a 2a 20 73 68 61 72 65 btain a.** share
3ca70 64 2d 63 61 63 68 65 20 6c 6f 63 6b 20 61 6e 64 d-cache lock and
3ca80 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 69 SQLITE_LOCKED i
3ca90 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 s returned to th
3caa0 65 20 63 61 6c 6c 65 72 2c 20 74 68 65 0a 2a 2a e caller, the.**
3cab0 20 69 64 65 6e 74 69 74 79 20 6f 66 20 74 68 65 identity of the
3cac0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
3cad0 74 69 6f 6e 20 28 74 68 65 20 62 6c 6f 63 6b 69 tion (the blocki
3cae0 6e 67 20 63 6f 6e 6e 65 63 74 69 6f 6e 29 20 74 ng connection) t
3caf0 68 61 74 0a 2a 2a 20 68 61 73 20 6c 6f 63 6b 65 hat.** has locke
3cb00 64 20 74 68 65 20 72 65 71 75 69 72 65 64 20 72 d the required r
3cb10 65 73 6f 75 72 63 65 20 69 73 20 73 74 6f 72 65 esource is store
3cb20 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 20 41 66 d internally. Af
3cb30 74 65 72 20 61 6e 20 0a 2a 2a 20 61 70 70 6c 69 ter an .** appli
3cb40 63 61 74 69 6f 6e 20 72 65 63 65 69 76 65 73 20 cation receives
3cb50 61 6e 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 an SQLITE_LOCKED
3cb60 20 65 72 72 6f 72 2c 20 69 74 20 6d 61 79 20 63 error, it may c
3cb70 61 6c 6c 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 all the.** sqlit
3cb80 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 e3_unlock_notify
3cb90 28 29 20 6d 65 74 68 6f 64 20 77 69 74 68 20 74 () method with t
3cba0 68 65 20 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e 65 he blocked conne
3cbb0 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 61 73 20 ction handle as
3cbc0 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 61 72 .** the first ar
3cbd0 67 75 6d 65 6e 74 20 74 6f 20 72 65 67 69 73 74 gument to regist
3cbe0 65 72 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 er for a callbac
3cbf0 6b 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 69 k that will be i
3cc00 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 nvoked.** when t
3cc10 68 65 20 62 6c 6f 63 6b 69 6e 67 20 63 6f 6e 6e he blocking conn
3cc20 65 63 74 69 6f 6e 73 20 63 75 72 72 65 6e 74 20 ections current
3cc30 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 transaction is c
3cc40 6f 6e 63 6c 75 64 65 64 2e 20 54 68 65 0a 2a 2a oncluded. The.**
3cc50 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
3cc60 6f 6b 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e oked from within
3cc70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 the [sqlite3_st
3cc80 65 70 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ep] or [sqlite3_
3cc90 63 6c 6f 73 65 5d 0a 2a 2a 20 63 61 6c 6c 20 74 close].** call t
3cca0 68 61 74 20 63 6f 6e 63 6c 75 64 65 73 20 74 68 hat concludes th
3ccb0 65 20 62 6c 6f 63 6b 69 6e 67 20 63 6f 6e 6e 65 e blocking conne
3ccc0 63 74 69 6f 6e 73 20 74 72 61 6e 73 61 63 74 69 ctions transacti
3ccd0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c on..**.** If sql
3cce0 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 ite3_unlock_noti
3ccf0 66 79 28 29 20 69 73 20 63 61 6c 6c 65 64 20 69 fy() is called i
3cd00 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 n a multi-thread
3cd10 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 0a ed application,.
3cd20 2a 2a 20 74 68 65 72 65 20 69 73 20 61 20 63 68 ** there is a ch
3cd30 61 6e 63 65 20 74 68 61 74 20 74 68 65 20 62 6c ance that the bl
3cd40 6f 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 69 6f ocking connectio
3cd50 6e 20 77 69 6c 6c 20 68 61 76 65 20 61 6c 72 65 n will have alre
3cd60 61 64 79 0a 2a 2a 20 63 6f 6e 63 6c 75 64 65 64 ady.** concluded
3cd70 20 69 74 73 20 74 72 61 6e 73 61 63 74 69 6f 6e its transaction
3cd80 20 62 79 20 74 68 65 20 74 69 6d 65 20 73 71 6c by the time sql
3cd90 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 ite3_unlock_noti
3cda0 66 79 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 2e fy() is invoked.
3cdb0 0a 2a 2a 20 49 66 20 74 68 69 73 20 68 61 70 70 .** If this happ
3cdc0 65 6e 73 2c 20 74 68 65 6e 20 74 68 65 20 73 70 ens, then the sp
3cdd0 65 63 69 66 69 65 64 20 63 61 6c 6c 62 61 63 6b ecified callback
3cde0 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6d 6d 65 is invoked imme
3cdf0 64 69 61 74 65 6c 79 2c 0a 2a 2a 20 66 72 6f 6d diately,.** from
3ce00 20 77 69 74 68 69 6e 20 74 68 65 20 63 61 6c 6c within the call
3ce10 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f to sqlite3_unlo
3ce20 63 6b 5f 6e 6f 74 69 66 79 28 29 2e 0a 2a 2a 0a ck_notify()..**.
3ce30 2a 2a 20 49 66 20 74 68 65 20 62 6c 6f 63 6b 65 ** If the blocke
3ce40 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 d connection is
3ce50 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 6f 62 attempting to ob
3ce60 74 61 69 6e 20 61 20 77 72 69 74 65 2d 6c 6f 63 tain a write-loc
3ce70 6b 20 6f 6e 20 61 0a 2a 2a 20 73 68 61 72 65 64 k on a.** shared
3ce80 2d 63 61 63 68 65 20 74 61 62 6c 65 2c 20 61 6e -cache table, an
3ce90 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 d more than one
3cea0 6f 74 68 65 72 20 63 6f 6e 6e 65 63 74 69 6f 6e other connection
3ceb0 20 63 75 72 72 65 6e 74 6c 79 20 68 6f 6c 64 73 currently holds
3cec0 0a 2a 2a 20 61 20 72 65 61 64 2d 6c 6f 63 6b 20 .** a read-lock
3ced0 6f 6e 20 74 68 65 20 73 61 6d 65 20 74 61 62 6c on the same tabl
3cee0 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 e, then SQLite a
3cef0 72 62 69 74 72 61 72 69 6c 79 20 73 65 6c 65 63 rbitrarily selec
3cf00 74 73 20 6f 6e 65 20 6f 66 20 0a 2a 2a 20 74 68 ts one of .** th
3cf10 65 20 6f 74 68 65 72 20 63 6f 6e 6e 65 63 74 69 e other connecti
3cf20 6f 6e 73 20 74 6f 20 75 73 65 20 61 73 20 74 68 ons to use as th
3cf30 65 20 62 6c 6f 63 6b 69 6e 67 20 63 6f 6e 6e 65 e blocking conne
3cf40 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ction..**.** The
3cf50 72 65 20 6d 61 79 20 62 65 20 61 74 20 6d 6f 73 re may be at mos
3cf60 74 20 6f 6e 65 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 t one unlock-not
3cf70 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 67 ify callback reg
3cf80 69 73 74 65 72 65 64 20 62 79 20 61 20 0a 2a 2a istered by a .**
3cf90 20 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e 65 63 74 blocked connect
3cfa0 69 6f 6e 2e 20 49 66 20 73 71 6c 69 74 65 33 5f ion. If sqlite3_
3cfb0 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 20 unlock_notify()
3cfc0 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 is called when t
3cfd0 68 65 0a 2a 2a 20 62 6c 6f 63 6b 65 64 20 63 6f he.** blocked co
3cfe0 6e 6e 65 63 74 69 6f 6e 20 61 6c 72 65 61 64 79 nnection already
3cff0 20 68 61 73 20 61 20 72 65 67 69 73 74 65 72 65 has a registere
3d000 64 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 d unlock-notify
3d010 63 61 6c 6c 62 61 63 6b 2c 0a 2a 2a 20 74 68 65 callback,.** the
3d020 6e 20 74 68 65 20 6e 65 77 20 63 61 6c 6c 62 61 n the new callba
3d030 63 6b 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 ck replaces the
3d040 6f 6c 64 2e 20 49 66 20 73 71 6c 69 74 65 33 5f old. If sqlite3_
3d050 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 20 unlock_notify()
3d060 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 77 69 74 is.** called wit
3d070 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 h a NULL pointer
3d080 20 61 73 20 69 74 73 20 73 65 63 6f 6e 64 20 61 as its second a
3d090 72 67 75 6d 65 6e 74 2c 20 74 68 65 6e 20 61 6e rgument, then an
3d0a0 79 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 75 6e y existing.** un
3d0b0 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c 6c lock-notify call
3d0c0 62 61 63 6b 20 69 73 20 63 61 6e 63 65 6c 6c 65 back is cancelle
3d0d0 64 2e 20 54 68 65 20 62 6c 6f 63 6b 65 64 20 63 d. The blocked c
3d0e0 6f 6e 6e 65 63 74 69 6f 6e 73 20 0a 2a 2a 20 75 onnections .** u
3d0f0 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c nlock-notify cal
3d100 6c 62 61 63 6b 20 6d 61 79 20 61 6c 73 6f 20 62 lback may also b
3d110 65 20 63 61 6e 63 65 6c 65 64 20 62 79 20 63 6c e canceled by cl
3d120 6f 73 69 6e 67 20 74 68 65 20 62 6c 6f 63 6b 65 osing the blocke
3d130 64 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 d.** connection
3d140 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 using [sqlite3_c
3d150 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 lose()]..**.** T
3d160 68 65 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 he unlock-notify
3d170 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 callback is not
3d180 20 72 65 65 6e 74 72 61 6e 74 2e 20 49 66 20 61 reentrant. If a
3d190 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e n application in
3d1a0 76 6f 6b 65 73 0a 2a 2a 20 61 6e 79 20 73 71 6c vokes.** any sql
3d1b0 69 74 65 33 5f 78 78 78 20 41 50 49 20 66 75 6e ite3_xxx API fun
3d1c0 63 74 69 6f 6e 73 20 66 72 6f 6d 20 77 69 74 68 ctions from with
3d1d0 69 6e 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 in an unlock-not
3d1e0 69 66 79 20 63 61 6c 6c 62 61 63 6b 2c 20 61 0a ify callback, a.
3d1f0 2a 2a 20 63 72 61 73 68 20 6f 72 20 64 65 61 64 ** crash or dead
3d200 6c 6f 63 6b 20 6d 61 79 20 62 65 20 74 68 65 20 lock may be the
3d210 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 55 6e result..**.** Un
3d220 6c 65 73 73 20 64 65 61 64 6c 6f 63 6b 20 69 73 less deadlock is
3d230 20 64 65 74 65 63 74 65 64 20 28 73 65 65 20 62 detected (see b
3d240 65 6c 6f 77 29 2c 20 73 71 6c 69 74 65 33 5f 75 elow), sqlite3_u
3d250 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 20 61 nlock_notify() a
3d260 6c 77 61 79 73 0a 2a 2a 20 72 65 74 75 72 6e 73 lways.** returns
3d270 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a SQLITE_OK..**.*
3d280 2a 20 3c 62 3e 43 61 6c 6c 62 61 63 6b 20 49 6e * <b>Callback In
3d290 76 6f 63 61 74 69 6f 6e 20 44 65 74 61 69 6c 73 vocation Details
3d2a0 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 </b>.**.** When
3d2b0 61 6e 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 an unlock-notify
3d2c0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 72 65 67 callback is reg
3d2d0 69 73 74 65 72 65 64 2c 20 74 68 65 20 61 70 70 istered, the app
3d2e0 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65 lication provide
3d2f0 73 20 61 20 0a 2a 2a 20 73 69 6e 67 6c 65 20 76 s a .** single v
3d300 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 74 68 61 oid* pointer tha
3d310 74 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 74 t is passed to t
3d320 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 68 65 6e he callback when
3d330 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a it is invoked..
3d340 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 ** However, the
3d350 73 69 67 6e 61 74 75 72 65 20 6f 66 20 74 68 65 signature of the
3d360 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
3d370 6f 6e 20 61 6c 6c 6f 77 73 20 53 51 4c 69 74 65 on allows SQLite
3d380 20 74 6f 20 70 61 73 73 0a 2a 2a 20 69 74 20 61 to pass.** it a
3d390 6e 20 61 72 72 61 79 20 6f 66 20 76 6f 69 64 2a n array of void*
3d3a0 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 context pointer
3d3b0 73 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67 s. The first arg
3d3c0 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a ument passed to.
3d3d0 2a 2a 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 ** an unlock-not
3d3e0 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 ify callback is
3d3f0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
3d400 61 72 72 61 79 20 6f 66 20 76 6f 69 64 2a 20 70 array of void* p
3d410 6f 69 6e 74 65 72 73 2c 0a 2a 2a 20 61 6e 64 20 ointers,.** and
3d420 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 the second is th
3d430 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6e 74 72 e number of entr
3d440 69 65 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 ies in the array
3d450 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 62 ..**.** When a b
3d460 6c 6f 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 69 locking connecti
3d470 6f 6e 73 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 ons transaction
3d480 69 73 20 63 6f 6e 63 6c 75 64 65 64 2c 20 74 68 is concluded, th
3d490 65 72 65 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f ere may be.** mo
3d4a0 72 65 20 74 68 61 6e 20 6f 6e 65 20 62 6c 6f 63 re than one bloc
3d4b0 6b 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 ked connection t
3d4c0 68 61 74 20 68 61 73 20 72 65 67 69 73 74 65 72 hat has register
3d4d0 65 64 20 66 6f 72 20 61 6e 20 75 6e 6c 6f 63 6b ed for an unlock
3d4e0 2d 6e 6f 74 69 66 79 0a 2a 2a 20 63 61 6c 6c 62 -notify.** callb
3d4f0 61 63 6b 2e 20 49 66 20 74 77 6f 20 6f 72 20 6d ack. If two or m
3d500 6f 72 65 20 73 75 63 68 20 62 6c 6f 63 6b 65 64 ore such blocked
3d510 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 68 61 76 connections hav
3d520 65 20 73 70 65 63 69 66 69 65 64 20 74 68 65 0a e specified the.
3d530 2a 2a 20 73 61 6d 65 20 63 61 6c 6c 62 61 63 6b ** same callback
3d540 20 66 75 6e 63 74 69 6f 6e 2c 20 74 68 65 6e 20 function, then
3d550 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b instead of invok
3d560 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b ing the callback
3d570 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 6c function.** mul
3d580 74 69 70 6c 65 20 74 69 6d 65 73 2c 20 69 74 20 tiple times, it
3d590 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 is invoked once
3d5a0 77 69 74 68 20 74 68 65 20 73 65 74 20 6f 66 20 with the set of
3d5b0 76 6f 69 64 2a 20 63 6f 6e 74 65 78 74 20 70 6f void* context po
3d5c0 69 6e 74 65 72 73 0a 2a 2a 20 73 70 65 63 69 66 inters.** specif
3d5d0 69 65 64 20 62 79 20 74 68 65 20 62 6c 6f 63 6b ied by the block
3d5e0 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 ed connections b
3d5f0 75 6e 64 6c 65 64 20 74 6f 67 65 74 68 65 72 20 undled together
3d600 69 6e 74 6f 20 61 6e 20 61 72 72 61 79 2e 0a 2a into an array..*
3d610 2a 20 54 68 69 73 20 67 69 76 65 73 20 74 68 65 * This gives the
3d620 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 61 6e 20 application an
3d630 6f 70 70 6f 72 74 75 6e 69 74 79 20 74 6f 20 70 opportunity to p
3d640 72 69 6f 72 69 74 69 7a 65 20 61 6e 79 20 61 63 rioritize any ac
3d650 74 69 6f 6e 73 20 0a 2a 2a 20 72 65 6c 61 74 65 tions .** relate
3d660 64 20 74 6f 20 74 68 65 20 73 65 74 20 6f 66 20 d to the set of
3d670 75 6e 62 6c 6f 63 6b 65 64 20 64 61 74 61 62 61 unblocked databa
3d680 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a se connections..
3d690 2a 2a 0a 2a 2a 20 3c 62 3e 44 65 61 64 6c 6f 63 **.** <b>Deadloc
3d6a0 6b 20 44 65 74 65 63 74 69 6f 6e 3c 2f 62 3e 0a k Detection</b>.
3d6b0 2a 2a 0a 2a 2a 20 41 73 73 75 6d 69 6e 67 20 74 **.** Assuming t
3d6c0 68 61 74 20 61 66 74 65 72 20 72 65 67 69 73 74 hat after regist
3d6d0 65 72 69 6e 67 20 66 6f 72 20 61 6e 20 75 6e 6c ering for an unl
3d6e0 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c 6c 62 ock-notify callb
3d6f0 61 63 6b 20 61 20 0a 2a 2a 20 64 61 74 61 62 61 ack a .** databa
3d700 73 65 20 77 61 69 74 73 20 66 6f 72 20 74 68 65 se waits for the
3d710 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 callback to be
3d720 69 73 73 75 65 64 20 62 65 66 6f 72 65 20 74 61 issued before ta
3d730 6b 69 6e 67 20 61 6e 79 20 66 75 72 74 68 65 72 king any further
3d740 0a 2a 2a 20 61 63 74 69 6f 6e 20 28 61 20 72 65 .** action (a re
3d750 61 73 6f 6e 61 62 6c 65 20 61 73 73 75 6d 70 74 asonable assumpt
3d760 69 6f 6e 29 2c 20 74 68 65 6e 20 75 73 69 6e 67 ion), then using
3d770 20 74 68 69 73 20 41 50 49 20 6d 61 79 20 63 61 this API may ca
3d780 75 73 65 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 use the.** appli
3d790 63 61 74 69 6f 6e 20 74 6f 20 64 65 61 64 6c 6f cation to deadlo
3d7a0 63 6b 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c ck. For example,
3d7b0 20 69 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 58 if connection X
3d7c0 20 69 73 20 77 61 69 74 69 6e 67 20 66 6f 72 0a is waiting for.
3d7d0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 59 27 ** connection Y'
3d7e0 73 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f s transaction to
3d7f0 20 62 65 20 63 6f 6e 63 6c 75 64 65 64 2c 20 61 be concluded, a
3d800 6e 64 20 73 69 6d 69 6c 61 72 6c 79 20 63 6f 6e nd similarly con
3d810 6e 65 63 74 69 6f 6e 0a 2a 2a 20 59 20 69 73 20 nection.** Y is
3d820 77 61 69 74 69 6e 67 20 6f 6e 20 63 6f 6e 6e 65 waiting on conne
3d830 63 74 69 6f 6e 20 58 27 73 20 74 72 61 6e 73 61 ction X's transa
3d840 63 74 69 6f 6e 2c 20 74 68 65 6e 20 6e 65 69 74 ction, then neit
3d850 68 65 72 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a her connection.*
3d860 2a 20 77 69 6c 6c 20 70 72 6f 63 65 65 64 20 61 * will proceed a
3d870 6e 64 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 nd the system ma
3d880 79 20 72 65 6d 61 69 6e 20 64 65 61 64 6c 6f 63 y remain deadloc
3d890 6b 65 64 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 ked indefinitely
3d8a0 2e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 ..**.** To avoid
3d8b0 20 74 68 69 73 20 73 63 65 6e 61 72 69 6f 2c 20 this scenario,
3d8c0 74 68 65 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f the sqlite3_unlo
3d8d0 63 6b 5f 6e 6f 74 69 66 79 28 29 20 70 65 72 66 ck_notify() perf
3d8e0 6f 72 6d 73 20 64 65 61 64 6c 6f 63 6b 0a 2a 2a orms deadlock.**
3d8f0 20 64 65 74 65 63 74 69 6f 6e 2e 20 49 66 20 61 detection. If a
3d900 20 67 69 76 65 6e 20 63 61 6c 6c 20 74 6f 20 73 given call to s
3d910 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f qlite3_unlock_no
3d920 74 69 66 79 28 29 20 77 6f 75 6c 64 20 70 75 74 tify() would put
3d930 20 74 68 65 0a 2a 2a 20 73 79 73 74 65 6d 20 69 the.** system i
3d940 6e 20 61 20 64 65 61 64 6c 6f 63 6b 65 64 20 73 n a deadlocked s
3d950 74 61 74 65 2c 20 74 68 65 6e 20 53 51 4c 49 54 tate, then SQLIT
3d960 45 5f 4c 4f 43 4b 45 44 20 69 73 20 72 65 74 75 E_LOCKED is retu
3d970 72 6e 65 64 20 61 6e 64 20 6e 6f 0a 2a 2a 20 75 rned and no.** u
3d980 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c nlock-notify cal
3d990 6c 62 61 63 6b 20 69 73 20 72 65 67 69 73 74 65 lback is registe
3d9a0 72 65 64 2e 20 54 68 65 20 73 79 73 74 65 6d 20 red. The system
3d9b0 69 73 20 73 61 69 64 20 74 6f 20 62 65 20 69 6e is said to be in
3d9c0 0a 2a 2a 20 61 20 64 65 61 64 6c 6f 63 6b 65 64 .** a deadlocked
3d9d0 20 73 74 61 74 65 20 69 66 20 63 6f 6e 6e 65 63 state if connec
3d9e0 74 69 6f 6e 20 41 20 68 61 73 20 72 65 67 69 73 tion A has regis
3d9f0 74 65 72 65 64 20 66 6f 72 20 61 6e 20 75 6e 6c tered for an unl
3da00 6f 63 6b 2d 6e 6f 74 69 66 79 0a 2a 2a 20 63 61 ock-notify.** ca
3da10 6c 6c 62 61 63 6b 20 6f 6e 20 74 68 65 20 63 6f llback on the co
3da20 6e 63 6c 75 73 69 6f 6e 20 6f 66 20 63 6f 6e 6e nclusion of conn
3da30 65 63 74 69 6f 6e 20 42 27 73 20 74 72 61 6e 73 ection B's trans
3da40 61 63 74 69 6f 6e 2c 20 61 6e 64 20 63 6f 6e 6e action, and conn
3da50 65 63 74 69 6f 6e 0a 2a 2a 20 42 20 68 61 73 20 ection.** B has
3da60 69 74 73 65 6c 66 20 72 65 67 69 73 74 65 72 65 itself registere
3da70 64 20 66 6f 72 20 61 6e 20 75 6e 6c 6f 63 6b 2d d for an unlock-
3da80 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 notify callback
3da90 77 68 65 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a when connection.
3daa0 2a 2a 20 41 27 73 20 74 72 61 6e 73 61 63 74 69 ** A's transacti
3dab0 6f 6e 20 69 73 20 63 6f 6e 63 6c 75 64 65 64 2e on is concluded.
3dac0 20 49 6e 64 69 72 65 63 74 20 64 65 61 64 6c 6f Indirect deadlo
3dad0 63 6b 20 69 73 20 61 6c 73 6f 20 64 65 74 65 63 ck is also detec
3dae0 74 65 64 2c 20 73 6f 0a 2a 2a 20 74 68 65 20 73 ted, so.** the s
3daf0 79 73 74 65 6d 20 69 73 20 61 6c 73 6f 20 63 6f ystem is also co
3db00 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20 64 nsidered to be d
3db10 65 61 64 6c 6f 63 6b 65 64 20 69 66 20 63 6f 6e eadlocked if con
3db20 6e 65 63 74 69 6f 6e 20 42 20 68 61 73 0a 2a 2a nection B has.**
3db30 20 72 65 67 69 73 74 65 72 65 64 20 66 6f 72 20 registered for
3db40 61 6e 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 an unlock-notify
3db50 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 74 68 65 callback on the
3db60 20 63 6f 6e 63 6c 75 73 69 6f 6e 20 6f 66 20 63 conclusion of c
3db70 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 27 73 onnection.** C's
3db80 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 77 68 transaction, wh
3db90 65 72 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 43 ere connection C
3dba0 20 69 73 20 77 61 69 74 69 6e 67 20 6f 6e 20 63 is waiting on c
3dbb0 6f 6e 6e 65 63 74 69 6f 6e 20 41 2e 20 41 6e 79 onnection A. Any
3dbc0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 6c 65 .** number of le
3dbd0 76 65 6c 73 20 6f 66 20 69 6e 64 69 72 65 63 74 vels of indirect
3dbe0 69 6f 6e 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e ion are allowed.
3dbf0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 22 44 .**.** <b>The "D
3dc00 52 4f 50 20 54 41 42 4c 45 22 20 45 78 63 65 70 ROP TABLE" Excep
3dc10 74 69 6f 6e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 57 tion</b>.**.** W
3dc20 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 hen a call to [s
3dc30 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 qlite3_step()] r
3dc40 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4c 4f eturns SQLITE_LO
3dc50 43 4b 45 44 2c 20 69 74 20 69 73 20 61 6c 6d 6f CKED, it is almo
3dc60 73 74 20 0a 2a 2a 20 61 6c 77 61 79 73 20 61 70 st .** always ap
3dc70 70 72 6f 70 72 69 61 74 65 20 74 6f 20 63 61 6c propriate to cal
3dc80 6c 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b l sqlite3_unlock
3dc90 5f 6e 6f 74 69 66 79 28 29 2e 20 54 68 65 72 65 _notify(). There
3dca0 20 69 73 20 68 6f 77 65 76 65 72 2c 0a 2a 2a 20 is however,.**
3dcb0 6f 6e 65 20 65 78 63 65 70 74 69 6f 6e 2e 20 57 one exception. W
3dcc0 68 65 6e 20 65 78 65 63 75 74 69 6e 67 20 61 20 hen executing a
3dcd0 22 44 52 4f 50 20 54 41 42 4c 45 22 20 6f 72 20 "DROP TABLE" or
3dce0 22 44 52 4f 50 20 49 4e 44 45 58 22 20 73 74 61 "DROP INDEX" sta
3dcf0 74 65 6d 65 6e 74 2c 0a 2a 2a 20 53 51 4c 69 74 tement,.** SQLit
3dd00 65 20 63 68 65 63 6b 73 20 69 66 20 74 68 65 72 e checks if ther
3dd10 65 20 61 72 65 20 61 6e 79 20 63 75 72 72 65 6e e are any curren
3dd20 74 6c 79 20 65 78 65 63 75 74 69 6e 67 20 53 45 tly executing SE
3dd30 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 73 0a LECT statements.
3dd40 2a 2a 20 74 68 61 74 20 62 65 6c 6f 6e 67 20 74 ** that belong t
3dd50 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6e 6e 65 o the same conne
3dd60 63 74 69 6f 6e 2e 20 49 66 20 74 68 65 72 65 20 ction. If there
3dd70 61 72 65 2c 20 53 51 4c 49 54 45 5f 4c 4f 43 4b are, SQLITE_LOCK
3dd80 45 44 20 69 73 0a 2a 2a 20 72 65 74 75 72 6e 65 ED is.** returne
3dd90 64 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 20 d. In this case
3dda0 74 68 65 72 65 20 69 73 20 6e 6f 20 22 62 6c 6f there is no "blo
3ddb0 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 69 6f 6e cking connection
3ddc0 22 2c 20 73 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a ", so invoking.*
3ddd0 2a 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b * sqlite3_unlock
3dde0 5f 6e 6f 74 69 66 79 28 29 20 72 65 73 75 6c 74 _notify() result
3ddf0 73 20 69 6e 20 74 68 65 20 75 6e 6c 6f 63 6b 2d s in the unlock-
3de00 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 notify callback
3de10 62 65 69 6e 67 0a 2a 2a 20 69 6e 76 6f 6b 65 64 being.** invoked
3de20 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 20 49 66 immediately. If
3de30 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
3de40 20 74 68 65 6e 20 72 65 2d 61 74 74 65 6d 70 74 then re-attempt
3de50 73 20 74 68 65 20 22 44 52 4f 50 20 54 41 42 4c s the "DROP TABL
3de60 45 22 0a 2a 2a 20 6f 72 20 22 44 52 4f 50 20 49 E".** or "DROP I
3de70 4e 44 45 58 22 20 71 75 65 72 79 2c 20 61 6e 20 NDEX" query, an
3de80 69 6e 66 69 6e 69 74 65 20 6c 6f 6f 70 20 6d 69 infinite loop mi
3de90 67 68 74 20 62 65 20 74 68 65 20 72 65 73 75 6c ght be the resul
3dea0 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 77 61 79 t..**.** One way
3deb0 20 61 72 6f 75 6e 64 20 74 68 69 73 20 70 72 6f around this pro
3dec0 62 6c 65 6d 20 69 73 20 74 6f 20 63 68 65 63 6b blem is to check
3ded0 20 74 68 65 20 65 78 74 65 6e 64 65 64 20 65 72 the extended er
3dee0 72 6f 72 20 63 6f 64 65 20 72 65 74 75 72 6e 65 ror code returne
3def0 64 0a 2a 2a 20 62 79 20 61 6e 20 73 71 6c 69 74 d.** by an sqlit
3df00 65 33 5f 73 74 65 70 28 29 20 63 61 6c 6c 2e 20 e3_step() call.
3df10 49 66 20 74 68 65 72 65 20 69 73 20 61 20 62 6c If there is a bl
3df20 6f 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 69 6f ocking connectio
3df30 6e 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 65 n, then the.** e
3df40 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f xtended error co
3df50 64 65 20 69 73 20 73 65 74 20 74 6f 20 53 51 4c de is set to SQL
3df60 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 ITE_LOCKED_SHARE
3df70 44 43 41 43 48 45 2e 20 4f 74 68 65 72 77 69 73 DCACHE. Otherwis
3df80 65 2c 20 69 6e 0a 2a 2a 20 74 68 65 20 73 70 65 e, in.** the spe
3df90 63 69 61 6c 20 22 44 52 4f 50 20 54 41 42 4c 45 cial "DROP TABLE
3dfa0 2f 49 4e 44 45 58 22 20 63 61 73 65 2c 20 74 68 /INDEX" case, th
3dfb0 65 20 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 e extended error
3dfc0 20 63 6f 64 65 20 69 73 20 6a 75 73 74 20 0a 2a code is just .*
3dfd0 2a 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 2e * SQLITE_LOCKED.
3dfe0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
3dff0 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 0a 20 unlock_notify(.
3e000 20 73 71 6c 69 74 65 33 20 2a 70 42 6c 6f 63 6b sqlite3 *pBlock
3e010 65 64 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 ed,
3e020 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
3e030 57 61 69 74 69 6e 67 20 63 6f 6e 6e 65 63 74 69 Waiting connecti
3e040 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 on */. void (*x
3e050 4e 6f 74 69 66 79 29 28 76 6f 69 64 20 2a 2a 61 Notify)(void **a
3e060 70 41 72 67 2c 20 69 6e 74 20 6e 41 72 67 29 2c pArg, int nArg),
3e070 20 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 /* Callback
3e080 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f function to invo
3e090 6b 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 4e ke */. void *pN
3e0a0 6f 74 69 66 79 41 72 67 20 20 20 20 20 20 20 20 otifyArg
3e0b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3e0c0 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 /* Argument
3e0d0 74 6f 20 70 61 73 73 20 74 6f 20 78 4e 6f 74 69 to pass to xNoti
3e0e0 66 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 fy */.);../*.**
3e0f0 55 6e 64 6f 20 74 68 65 20 68 61 63 6b 20 74 68 Undo the hack th
3e100 61 74 20 63 6f 6e 76 65 72 74 73 20 66 6c 6f 61 at converts floa
3e110 74 69 6e 67 20 70 6f 69 6e 74 20 74 79 70 65 73 ting point types
3e120 20 74 6f 20 69 6e 74 65 67 65 72 20 66 6f 72 0a to integer for.
3e130 2a 2a 20 62 75 69 6c 64 73 20 6f 6e 20 70 72 6f ** builds on pro
3e140 63 65 73 73 6f 72 73 20 77 69 74 68 6f 75 74 20 cessors without
3e150 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 floating point s
3e160 75 70 70 6f 72 74 2e 0a 2a 2f 0a 23 69 66 64 65 upport..*/.#ifde
3e170 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c f SQLITE_OMIT_FL
3e180 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 75 OATING_POINT.# u
3e190 6e 64 65 66 20 64 6f 75 62 6c 65 0a 23 65 6e 64 ndef double.#end
3e1a0 69 66 0a 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c if..#ifdef __cpl
3e1b0 75 73 70 6c 75 73 0a 7d 20 20 2f 2a 20 45 6e 64 usplus.} /* End
3e1c0 20 6f 66 20 74 68 65 20 27 65 78 74 65 72 6e 20 of the 'extern
3e1d0 22 43 22 27 20 62 6c 6f 63 6b 20 2a 2f 0a 23 65 "C"' block */.#e
3e1e0 6e 64 69 66 0a 23 65 6e 64 69 66 0a ndif.#endif.