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: 2e 32 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .2".#define SQLI
0ea0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 TE_VERSION_NUMBE
0eb0: 52 20 20 33 30 30 36 30 31 34 0a 0a 2f 2a 0a 2a R 3006014../*.*
0ec0: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d * CAPI3REF: Run-
0ed0: 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 Time Library Ver
0ee0: 73 69 6f 6e 20 4e 75 6d 62 65 72 73 20 7b 48 31 sion Numbers {H1
0ef0: 30 30 32 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 0020} <S60100>.*
0f00: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 * KEYWORDS: sqli
0f10: 74 65 33 5f 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a te3_version.**.*
0f20: 2a 20 54 68 65 73 65 20 66 65 61 74 75 72 65 73 * These features
0f30: 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d provide the sam
0f40: 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 e information as
0f50: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 the [SQLITE_VER
0f60: 53 49 4f 4e 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51 SION].** and [SQ
0f70: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d LITE_VERSION_NUM
0f80: 42 45 52 5d 20 23 64 65 66 69 6e 65 73 20 69 6e BER] #defines in
0f90: 20 74 68 65 20 68 65 61 64 65 72 2c 20 62 75 74 the header, but
0fa0: 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64 0a are associated.
0fb0: 2a 2a 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 ** with the libr
0fc0: 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74 ary instead of t
0fd0: 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20 he header file.
0fe0: 20 43 61 75 74 69 6f 75 73 20 70 72 6f 67 72 61 Cautious progra
0ff0: 6d 6d 65 72 73 20 6d 69 67 68 74 0a 2a 2a 20 69 mmers might.** i
1000: 6e 63 6c 75 64 65 20 61 20 63 68 65 63 6b 20 69 nclude a check i
1010: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 n their applicat
1020: 69 6f 6e 20 74 6f 20 76 65 72 69 66 79 20 74 68 ion to verify th
1030: 61 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 at.** sqlite3_li
1040: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 bversion_number(
1050: 29 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 ) always returns
1060: 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 5b 53 the value.** [S
1070: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 QLITE_VERSION_NU
1080: 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 MBER]..**.** The
1090: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 sqlite3_libvers
10a0: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 ion() function r
10b0: 65 74 75 72 6e 73 20 74 68 65 20 73 61 6d 65 20 eturns the same
10c0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 information as i
10d0: 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 71 6c 69 s.** in the sqli
10e0: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 te3_version[] st
10f0: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 ring constant.
1100: 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 The function is
1110: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 provided.** for
1120: 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 use in DLLs sinc
1130: 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61 e DLL users usua
1140: 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 lly do not have
1150: 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74 6f direct access to
1160: 20 73 74 72 69 6e 67 0a 2a 2a 20 63 6f 6e 73 74 string.** const
1170: 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 ants within the
1180: 44 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 DLL..**.** Requi
1190: 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 30 32 31 rements: [H10021
11a0: 5d 20 5b 48 31 30 30 32 32 5d 20 5b 48 31 30 30 ] [H10022] [H100
11b0: 32 33 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 23].*/.SQLITE_EX
11c0: 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 TERN const char
11d0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b sqlite3_version[
11e0: 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 ];.const char *s
11f0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
1200: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c n(void);.int sql
1210: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f ite3_libversion_
1220: 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f number(void);../
1230: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
1240: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68 est To See If Th
1250: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72 e Library Is Thr
1260: 65 61 64 73 61 66 65 20 7b 48 31 30 31 30 30 7d eadsafe {H10100}
1270: 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S60100>.**.**
1280: 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f SQLite can be co
1290: 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 mpiled with or w
12a0: 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 ithout mutexes.
12b0: 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 When.** the [SQ
12c0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d LITE_THREADSAFE]
12d0: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 C preprocessor
12e0: 6d 61 63 72 6f 20 31 20 6f 72 20 32 2c 20 6d 75 macro 1 or 2, mu
12f0: 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 texes.** are ena
1300: 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 bled and SQLite
1310: 69 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 is threadsafe.
1320: 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c When the.** [SQL
1330: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 ITE_THREADSAFE]
1340: 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 macro is 0, .**
1350: 74 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 the mutexes are
1360: 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 omitted. Withou
1370: 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 t the mutexes, i
1380: 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a t is not safe.**
1390: 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 to use SQLite c
13a0: 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d oncurrently from
13b0: 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 more than one t
13c0: 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 hread..**.** Ena
13d0: 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e bling mutexes in
13e0: 63 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c curs a measurabl
13f0: 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 e performance pe
1400: 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 nalty..** So if
1410: 73 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f speed is of utmo
1420: 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 st importance, i
1430: 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f t makes sense to
1440: 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 disable.** the
1450: 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f mutexes. But fo
1460: 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 r maximum safety
1470: 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 , mutexes should
1480: 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 be enabled..**
1490: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 The default beha
14a0: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 vior is for mute
14b0: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 xes to be enable
14c0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e d..**.** This in
14d0: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 terface can be u
14e0: 73 65 64 20 62 79 20 61 20 70 72 6f 67 72 61 6d sed by a program
14f0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 to make sure th
1500: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f at the.** versio
1510: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 n of SQLite that
1520: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 it is linking a
1530: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 gainst was compi
1540: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 led with.** the
1550: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 desired setting
1560: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 of the [SQLITE_T
1570: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f HREADSAFE] macro
1580: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 ..**.** This int
1590: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f erface only repo
15a0: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 rts on the compi
15b0: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 le-time mutex se
15c0: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 tting.** of the
15d0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
15e0: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 FE] flag. If SQ
15f0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
1600: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f with.** SQLITE_
1610: 54 48 52 45 41 44 53 41 46 45 3d 31 20 74 68 65 THREADSAFE=1 the
1620: 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e n mutexes are en
1630: 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 abled by default
1640: 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 but.** can be f
1650: 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c ully or partiall
1660: 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 y disabled using
1670: 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 a call to [sqli
1680: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a te3_config()].**
1690: 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73 20 with the verbs
16a0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
16b0: 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 INGLETHREAD], [S
16c0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c QLITE_CONFIG_MUL
16d0: 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 TITHREAD],.** or
16e0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
16f0: 4d 55 54 45 58 5d 2e 20 20 54 68 65 20 72 65 74 MUTEX]. The ret
1700: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 urn value of thi
1710: 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 s function shows
1720: 0a 2a 2a 20 6f 6e 6c 79 20 74 68 65 20 64 65 66 .** only the def
1730: 61 75 6c 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d ault compile-tim
1740: 65 20 73 65 74 74 69 6e 67 2c 20 6e 6f 74 20 61 e setting, not a
1750: 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e ny run-time chan
1760: 67 65 73 0a 2a 2a 20 74 6f 20 74 68 61 74 20 73 ges.** to that s
1770: 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 53 65 etting..**.** Se
1780: 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 e the [threading
1790: 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 mode] documenta
17a0: 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f tion for additio
17b0: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e nal information.
17c0: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
17d0: 6e 74 73 3a 20 5b 48 31 30 31 30 31 5d 20 5b 48 nts: [H10101] [H
17e0: 31 30 31 30 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 10102].*/.int sq
17f0: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 lite3_threadsafe
1800: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 (void);../*.** C
1810: 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 API3REF: Databas
1820: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e e Connection Han
1830: 64 6c 65 20 7b 48 31 32 30 30 30 7d 20 3c 53 34 dle {H12000} <S4
1840: 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 0200>.** KEYWORD
1850: 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e S: {database con
1860: 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 nection} {databa
1870: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a se connections}.
1880: 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 **.** Each open
1890: 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 SQLite database
18a0: 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 is represented b
18b0: 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 y a pointer to a
18c0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a n instance of.**
18d0: 20 74 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 the opaque stru
18e0: 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c cture named "sql
18f0: 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 ite3". It is us
1900: 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 eful to think of
1910: 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 an sqlite3.** p
1920: 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a ointer as an obj
1930: 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 ect. The [sqlit
1940: 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c e3_open()], [sql
1950: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 ite3_open16()],
1960: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
1970: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 open_v2()] inter
1980: 66 61 63 65 73 20 61 72 65 20 69 74 73 20 63 6f faces are its co
1990: 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 nstructors, and
19a0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 [sqlite3_close()
19b0: 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64 65 73 74 ].** is its dest
19c0: 72 75 63 74 6f 72 2e 20 20 54 68 65 72 65 20 61 ructor. There a
19d0: 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e re many other in
19e0: 74 65 72 66 61 63 65 73 20 28 73 75 63 68 20 61 terfaces (such a
19f0: 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 s.** [sqlite3_pr
1a00: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 epare_v2()], [sq
1a10: 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
1a20: 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a ction()], and.**
1a30: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 [sqlite3_busy_t
1a40: 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d imeout()] to nam
1a50: 65 20 62 75 74 20 74 68 72 65 65 29 20 74 68 61 e but three) tha
1a60: 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e t are methods on
1a70: 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f an.** sqlite3 o
1a80: 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 bject..*/.typede
1a90: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
1aa0: 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a sqlite3;../*.**
1ab0: 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 CAPI3REF: 64-Bi
1ac0: 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 20 t Integer Types
1ad0: 7b 48 31 30 32 30 30 7d 20 3c 53 31 30 31 31 30 {H10200} <S10110
1ae0: 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 >.** KEYWORDS: s
1af0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 qlite_int64 sqli
1b00: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 te_uint64.**.**
1b10: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73 Because there is
1b20: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f no cross-platfo
1b30: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 rm way to specif
1b40: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 y 64-bit integer
1b50: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 types.** SQLite
1b60: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 includes typede
1b70: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 fs for 64-bit si
1b80: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 gned and unsigne
1b90: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a d integers..**.*
1ba0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e * The sqlite3_in
1bb0: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f t64 and sqlite3_
1bc0: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 uint64 are the p
1bd0: 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65 referred type de
1be0: 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 finitions..** Th
1bf0: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 e sqlite_int64 a
1c00: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 nd sqlite_uint64
1c10: 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f types are suppo
1c20: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 rted for backwar
1c30: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c ds.** compatibil
1c40: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 ity only..**.**
1c50: 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 Requirements: [H
1c60: 31 30 32 30 31 5d 20 5b 48 31 30 32 30 32 5d 0a 10201] [H10202].
1c70: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 */.#ifdef SQLITE
1c80: 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 _INT64_TYPE. ty
1c90: 70 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 pedef SQLITE_INT
1ca0: 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 64_TYPE sqlite_i
1cb0: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 nt64;. typedef
1cc0: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f unsigned SQLITE_
1cd0: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 INT64_TYPE sqlit
1ce0: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 e_uint64;.#elif
1cf0: 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 defined(_MSC_VER
1d00: 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 ) || defined(__B
1d10: 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 ORLANDC__). typ
1d20: 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c edef __int64 sql
1d30: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 ite_int64;. typ
1d40: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f edef unsigned __
1d50: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e int64 sqlite_uin
1d60: 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 t64;.#else. typ
1d70: 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 edef long long i
1d80: 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b nt sqlite_int64;
1d90: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 . typedef unsig
1da0: 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e ned long long in
1db0: 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b t sqlite_uint64;
1dc0: 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 .#endif.typedef
1dd0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c sqlite_int64 sql
1de0: 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 ite3_int64;.type
1df0: 64 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 def sqlite_uint6
1e00: 34 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 4 sqlite3_uint64
1e10: 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 ;../*.** If comp
1e20: 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 iling for a proc
1e30: 65 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 essor that lacks
1e40: 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 floating point
1e50: 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 support,.** subs
1e60: 74 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 titute integer f
1e70: 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e or floating-poin
1e80: 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c t..*/.#ifdef SQL
1e90: 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e ITE_OMIT_FLOATIN
1ea0: 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 G_POINT.# define
1eb0: 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f double sqlite3_
1ec0: 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a int64.#endif../*
1ed0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c .** CAPI3REF: Cl
1ee0: 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 osing A Database
1ef0: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 32 Connection {H12
1f00: 30 31 30 7d 20 3c 53 33 30 31 30 30 3e 3c 53 34 010} <S30100><S4
1f10: 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 0200>.**.** This
1f20: 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20 routine is the
1f30: 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 destructor for t
1f40: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a he [sqlite3] obj
1f50: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 ect..**.** Appli
1f60: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b cations should [
1f70: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
1f80: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c | finalize] all
1f90: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
1fa0: 6d 65 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 ments].** and [s
1fb0: 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 qlite3_blob_clos
1fc0: 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b e | close] all [
1fd0: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73 BLOB handles] as
1fe0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a sociated with.**
1ff0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f the [sqlite3] o
2000: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 bject prior to a
2010: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f ttempting to clo
2020: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 0a 2a se the object..*
2030: 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6e * The [sqlite3_n
2040: 65 78 74 5f 73 74 6d 74 28 29 5d 20 69 6e 74 65 ext_stmt()] inte
2050: 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 rface can be use
2060: 64 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 0a d to locate all.
2070: 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
2080: 74 65 6d 65 6e 74 73 5d 20 61 73 73 6f 63 69 61 tements] associa
2090: 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 ted with a [data
20a0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
20b0: 20 69 66 20 64 65 73 69 72 65 64 2e 0a 2a 2a 20 if desired..**
20c0: 54 79 70 69 63 61 6c 20 63 6f 64 65 20 6d 69 67 Typical code mig
20d0: 68 74 20 6c 6f 6f 6b 20 6c 69 6b 65 20 74 68 69 ht look like thi
20e0: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 s:.**.** <blockq
20f0: 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 73 71 uote><pre>.** sq
2100: 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d lite3_stmt *pStm
2110: 74 3b 0a 2a 2a 20 77 68 69 6c 65 28 20 28 70 53 t;.** while( (pS
2120: 74 6d 74 20 3d 20 73 71 6c 69 74 65 33 5f 6e 65 tmt = sqlite3_ne
2130: 78 74 5f 73 74 6d 74 28 64 62 2c 20 30 29 29 21 xt_stmt(db, 0))!
2140: 3d 30 20 29 7b 0a 2a 2a 20 26 6e 62 73 70 3b 20 =0 ){.**
2150: 20 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 sqlite3_finali
2160: 7a 65 28 70 53 74 6d 74 29 3b 0a 2a 2a 20 7d 0a ze(pStmt);.** }.
2170: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
2180: 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 quote>.**.** If
2190: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 [sqlite3_close()
21a0: 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 69 ] is invoked whi
21b0: 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e le a transaction
21c0: 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 is open,.** the
21d0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 transaction is
21e0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f automatically ro
21f0: 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a lled back..**.**
2200: 20 54 68 65 20 43 20 70 61 72 61 6d 65 74 65 72 The C parameter
2210: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f to [sqlite3_clo
2220: 73 65 28 43 29 5d 20 6d 75 73 74 20 62 65 20 65 se(C)] must be e
2230: 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 ither a NULL.**
2240: 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 pointer or an [s
2250: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 qlite3] object p
2260: 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a ointer obtained.
2270: 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ** from [sqlite3
2280: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 _open()], [sqlit
2290: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 e3_open16()], or
22a0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 .** [sqlite3_ope
22b0: 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 n_v2()], and not
22c0: 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 previously clos
22d0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 ed..**.** Requir
22e0: 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 30 ements:.** [H120
22f0: 31 31 5d 20 5b 48 31 32 30 31 32 5d 20 5b 48 31 11] [H12012] [H1
2300: 32 30 31 33 5d 20 5b 48 31 32 30 31 34 5d 20 5b 2013] [H12014] [
2310: 48 31 32 30 31 35 5d 20 5b 48 31 32 30 31 39 5d H12015] [H12019]
2320: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
2330: 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 2a 29 close(sqlite3 *)
2340: 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 ;../*.** The typ
2350: 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b e for a callback
2360: 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 function..** Th
2370: 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 is is legacy and
2380: 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 74 deprecated. It
2390: 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 is included for
23a0: 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 historical.** c
23b0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64 ompatibility and
23c0: 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 is not document
23d0: 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 ed..*/.typedef i
23e0: 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c nt (*sqlite3_cal
23f0: 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 lback)(void*,int
2400: 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 ,char**, char**)
2410: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2420: 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 F: One-Step Quer
2430: 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 y Execution Inte
2440: 72 66 61 63 65 20 7b 48 31 32 31 30 30 7d 20 3c rface {H12100} <
2450: 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S10000>.**.** Th
2460: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 e sqlite3_exec()
2470: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 interface is a
2480: 63 6f 6e 76 65 6e 69 65 6e 74 20 77 61 79 20 6f convenient way o
2490: 66 20 72 75 6e 6e 69 6e 67 20 6f 6e 65 20 6f 72 f running one or
24a0: 20 6d 6f 72 65 0a 2a 2a 20 53 51 4c 20 73 74 61 more.** SQL sta
24b0: 74 65 6d 65 6e 74 73 20 77 69 74 68 6f 75 74 20 tements without
24c0: 68 61 76 69 6e 67 20 74 6f 20 77 72 69 74 65 20 having to write
24d0: 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e a lot of C code.
24e0: 20 20 54 68 65 20 55 54 46 2d 38 20 65 6e 63 6f The UTF-8 enco
24f0: 64 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 ded.** SQL state
2500: 6d 65 6e 74 73 20 61 72 65 20 70 61 73 73 65 64 ments are passed
2510: 20 69 6e 20 61 73 20 74 68 65 20 73 65 63 6f 6e in as the secon
2520: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 d parameter to s
2530: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2e 0a 2a qlite3_exec()..*
2540: 2a 20 54 68 65 20 73 74 61 74 65 6d 65 6e 74 73 * The statements
2550: 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 6f are evaluated o
2560: 6e 65 20 62 79 20 6f 6e 65 20 75 6e 74 69 6c 20 ne by one until
2570: 65 69 74 68 65 72 20 61 6e 20 65 72 72 6f 72 20 either an error
2580: 6f 72 0a 2a 2a 20 61 6e 20 69 6e 74 65 72 72 75 or.** an interru
2590: 70 74 20 69 73 20 65 6e 63 6f 75 6e 74 65 72 65 pt is encountere
25a0: 64 2c 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 79 d, or until they
25b0: 20 61 72 65 20 61 6c 6c 20 64 6f 6e 65 2e 20 20 are all done.
25c0: 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 The 3rd paramete
25d0: 72 0a 2a 2a 20 69 73 20 61 6e 20 6f 70 74 69 6f r.** is an optio
25e0: 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 74 68 61 nal callback tha
25f0: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 t is invoked onc
2600: 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f e for each row o
2610: 66 20 61 6e 79 20 71 75 65 72 79 0a 2a 2a 20 72 f any query.** r
2620: 65 73 75 6c 74 73 20 70 72 6f 64 75 63 65 64 20 esults produced
2630: 62 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 by the SQL state
2640: 6d 65 6e 74 73 2e 20 20 54 68 65 20 35 74 68 20 ments. The 5th
2650: 70 61 72 61 6d 65 74 65 72 20 74 65 6c 6c 73 20 parameter tells
2660: 77 68 65 72 65 0a 2a 2a 20 74 6f 20 77 72 69 74 where.** to writ
2670: 65 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 e any error mess
2680: 61 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ages..**.** The
2690: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 70 61 error message pa
26a0: 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67 ssed back throug
26b0: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 h the 5th parame
26c0: 74 65 72 20 69 73 20 68 65 6c 64 0a 2a 2a 20 69 ter is held.** i
26d0: 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 n memory obtaine
26e0: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
26f0: 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 6f 20 61 malloc()]. To a
2700: 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 void a memory le
2710: 61 6b 2c 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 69 ak,.** the calli
2720: 6e 67 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 ng application s
2730: 68 6f 75 6c 64 20 63 61 6c 6c 20 5b 73 71 6c 69 hould call [sqli
2740: 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 61 te3_free()] on a
2750: 6e 79 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 ny error.** mess
2760: 61 67 65 20 72 65 74 75 72 6e 65 64 20 74 68 72 age returned thr
2770: 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 ough the 5th par
2780: 61 6d 65 74 65 72 20 77 68 65 6e 20 69 74 20 68 ameter when it h
2790: 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e as finished usin
27a0: 67 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d g.** the error m
27b0: 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 essage..**.** If
27c0: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
27d0: 6e 74 20 69 6e 20 74 68 65 20 32 6e 64 20 70 61 nt in the 2nd pa
27e0: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 rameter is NULL
27f0: 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 or an empty stri
2800: 6e 67 0a 2a 2a 20 6f 72 20 61 20 73 74 72 69 6e ng.** or a strin
2810: 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 6f 6e 6c g containing onl
2820: 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 y whitespace and
2830: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 comments, then
2840: 6e 6f 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d no SQL.** statem
2850: 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 ents are evaluat
2860: 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 ed and the datab
2870: 61 73 65 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 ase is not chang
2880: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ed..**.** The sq
2890: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 lite3_exec() int
28a0: 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d erface is implem
28b0: 65 6e 74 65 64 20 69 6e 20 74 65 72 6d 73 20 6f ented in terms o
28c0: 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 f.** [sqlite3_pr
28d0: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 epare_v2()], [sq
28e0: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 lite3_step()], a
28f0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 nd [sqlite3_fina
2900: 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 lize()]..** The
2910: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 72 sqlite3_exec() r
2920: 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 68 outine does noth
2930: 69 6e 67 20 74 6f 20 74 68 65 20 64 61 74 61 62 ing to the datab
2940: 61 73 65 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 ase that cannot
2950: 62 65 20 64 6f 6e 65 0a 2a 2a 20 62 79 20 5b 73 be done.** by [s
2960: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
2970: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 2()], [sqlite3_s
2980: 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c tep()], and [sql
2990: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
29a0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 ..**.** The firs
29b0: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b t parameter to [
29c0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 sqlite3_exec()]
29d0: 6d 75 73 74 20 62 65 20 61 6e 20 76 61 6c 69 64 must be an valid
29e0: 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20 5b 64 61 and open.** [da
29f0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2a00: 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 61 n]..**.** The da
2a10: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2a20: 6e 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 63 6c n must not be cl
2a30: 6f 73 65 64 20 77 68 69 6c 65 0a 2a 2a 20 5b 73 osed while.** [s
2a40: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 qlite3_exec()] i
2a50: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a s running..**.**
2a60: 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e The calling fun
2a70: 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 ction should use
2a80: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
2a90: 5d 20 74 6f 20 66 72 65 65 0a 2a 2a 20 74 68 65 ] to free.** the
2aa0: 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 2a 65 72 memory that *er
2ab0: 72 6d 73 67 20 69 73 20 6c 65 66 74 20 70 6f 69 rmsg is left poi
2ac0: 6e 74 69 6e 67 20 61 74 20 6f 6e 63 65 20 74 68 nting at once th
2ad0: 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 e error.** messa
2ae0: 67 65 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 ge is no longer
2af0: 6e 65 65 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 needed..**.** Th
2b00: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
2b10: 74 65 78 74 20 69 6e 20 74 68 65 20 32 6e 64 20 text in the 2nd
2b20: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 parameter to [sq
2b30: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a lite3_exec()].**
2b40: 20 6d 75 73 74 20 72 65 6d 61 69 6e 20 75 6e 63 must remain unc
2b50: 68 61 6e 67 65 64 20 77 68 69 6c 65 20 5b 73 71 hanged while [sq
2b60: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 lite3_exec()] is
2b70: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 running..**.**
2b80: 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
2b90: 20 5b 48 31 32 31 30 31 5d 20 5b 48 31 32 31 30 [H12101] [H1210
2ba0: 32 5d 20 5b 48 31 32 31 30 34 5d 20 5b 48 31 32 2] [H12104] [H12
2bb0: 31 30 35 5d 20 5b 48 31 32 31 30 37 5d 20 5b 48 105] [H12107] [H
2bc0: 31 32 31 31 30 5d 20 5b 48 31 32 31 31 33 5d 20 12110] [H12113]
2bd0: 5b 48 31 32 31 31 36 5d 0a 2a 2a 20 5b 48 31 32 [H12116].** [H12
2be0: 31 31 39 5d 20 5b 48 31 32 31 32 32 5d 20 5b 48 119] [H12122] [H
2bf0: 31 32 31 32 35 5d 20 5b 48 31 32 31 33 31 5d 20 12125] [H12131]
2c00: 5b 48 31 32 31 33 34 5d 20 5b 48 31 32 31 33 37 [H12134] [H12137
2c10: 5d 20 5b 48 31 32 31 33 38 5d 0a 2a 2f 0a 69 6e ] [H12138].*/.in
2c20: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a t sqlite3_exec(.
2c30: 20 20 73 71 6c 69 74 65 33 2a 2c 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 20 20 2f 2a 20 /*
2c60: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 An open database
2c70: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
2c80: 20 2a 73 71 6c 2c 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 20
2ca0: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 /* SQL to be ev
2cb0: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 aluated */. int
2cc0: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 (*callback)(voi
2cd0: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 d*,int,char**,ch
2ce0: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 ar**), /* Callb
2cf0: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a ack function */.
2d00: 20 20 76 6f 69 64 20 2a 2c 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 20 20 2f 2a 20 /*
2d30: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 1st argument to
2d40: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 callback */. ch
2d50: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 ar **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 20 20 2f 2a 20 45 72 72 6f /* Erro
2d80: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 r msg written he
2d90: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 re */.);../*.**
2da0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 CAPI3REF: Result
2db0: 20 43 6f 64 65 73 20 7b 48 31 30 32 31 30 7d 20 Codes {H10210}
2dc0: 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 <S10700>.** KEYW
2dd0: 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 ORDS: SQLITE_OK
2de0: 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 {error code} {er
2df0: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 ror codes}.** KE
2e00: 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 YWORDS: {result
2e10: 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f code} {result co
2e20: 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 des}.**.** Many
2e30: 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 SQLite functions
2e40: 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 return an integ
2e50: 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 er result code f
2e60: 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 rom the set show
2e70: 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 n.** here in ord
2e80: 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 er to indicates
2e90: 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 success or failu
2ea0: 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 re..**.** New er
2eb0: 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 ror codes may be
2ec0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 added in future
2ed0: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
2ee0: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ite..**.** See a
2ef0: 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 lso: [SQLITE_IOE
2f00: 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 RR_READ | extend
2f10: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d ed result codes]
2f20: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
2f30: 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 TE_OK
2f40: 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 0 /* Successfu
2f50: 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 l result */./* b
2f60: 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f eginning-of-erro
2f70: 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 r-codes */.#defi
2f80: 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 ne SQLITE_ERROR
2f90: 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 1 /* SQ
2fa0: 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 L error or missi
2fb0: 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 ng database */.#
2fc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e define SQLITE_IN
2fd0: 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f TERNAL 2 /
2fe0: 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 * Internal logic
2ff0: 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 error in SQLite
3000: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
3010: 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 TE_PERM
3020: 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 3 /* Access pe
3030: 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 rmission denied
3040: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
3050: 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 E_ABORT 4
3060: 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 /* Callback r
3070: 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 outine requested
3080: 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 an abort */.#de
3090: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 fine SQLITE_BUSY
30a0: 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 5 /*
30b0: 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c The database fil
30c0: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 e is locked */.#
30d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f define SQLITE_LO
30e0: 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20 2f CKED 6 /
30f0: 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 * A table in the
3100: 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 database is loc
3110: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ked */.#define S
3120: 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 QLITE_NOMEM
3130: 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 7 /* A mall
3140: 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 oc() failed */.#
3150: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 define SQLITE_RE
3160: 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f ADONLY 8 /
3170: 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 * Attempt to wri
3180: 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 te a readonly da
3190: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e tabase */.#defin
31a0: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 e SQLITE_INTERRU
31b0: 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 PT 9 /* Ope
31c0: 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 ration terminate
31d0: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 d by sqlite3_int
31e0: 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 errupt()*/.#defi
31f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 ne SQLITE_IOERR
3200: 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 10 /* So
3210: 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 me kind of disk
3220: 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 I/O error occurr
3230: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ed */.#define SQ
3240: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 LITE_CORRUPT
3250: 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 11 /* The dat
3260: 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 abase disk image
3270: 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f is malformed */
3280: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3290: 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 NOTFOUND 12
32a0: 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 /* NOT USED. Ta
32b0: 62 6c 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f ble or record no
32c0: 74 20 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 t found */.#defi
32d0: 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 ne SQLITE_FULL
32e0: 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 13 /* In
32f0: 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 sertion failed b
3300: 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65 20 ecause database
3310: 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 is full */.#defi
3320: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 ne SQLITE_CANTOP
3330: 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e EN 14 /* Un
3340: 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 able to open the
3350: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a database file *
3360: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
3370: 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 _PROTOCOL 15
3380: 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 44 /* NOT USED. D
3390: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f atabase lock pro
33a0: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 tocol error */.#
33b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d define SQLITE_EM
33c0: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f PTY 16 /
33d0: 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d * Database is em
33e0: 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 pty */.#define S
33f0: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 QLITE_SCHEMA
3400: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 17 /* The da
3410: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 tabase schema ch
3420: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 anged */.#define
3430: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 SQLITE_TOOBIG
3440: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 18 /* Stri
3450: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 ng or BLOB excee
3460: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f ds size limit */
3470: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3480: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 CONSTRAINT 19
3490: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f /* Abort due to
34a0: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c constraint viol
34b0: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 ation */.#define
34c0: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 SQLITE_MISMATCH
34d0: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 /* Data
34e0: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a type mismatch *
34f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
3500: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 _MISUSE 21
3510: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 /* Library use
3520: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f d incorrectly */
3530: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3540: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 NOLFS 22
3550: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 /* Uses OS feat
3560: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 ures not support
3570: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 ed on host */.#d
3580: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 efine SQLITE_AUT
3590: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a H 23 /*
35a0: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 Authorization d
35b0: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 enied */.#define
35c0: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 SQLITE_FORMAT
35d0: 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 24 /* Auxi
35e0: 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 liary database f
35f0: 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 ormat error */.#
3600: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 define SQLITE_RA
3610: 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f NGE 25 /
3620: 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 * 2nd parameter
3630: 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 to sqlite3_bind
3640: 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a out of range */.
3650: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e #define SQLITE_N
3660: 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 OTADB 26
3670: 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 /* File opened t
3680: 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 hat is not a dat
3690: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 abase file */.#d
36a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 efine SQLITE_ROW
36b0: 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 100 /*
36c0: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
36d0: 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 has another row
36e0: 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 ready */.#define
36f0: 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 SQLITE_DONE
3700: 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 101 /* sqli
3710: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 te3_step() has f
3720: 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e inished executin
3730: 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 g */./* end-of-e
3740: 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f rror-codes */../
3750: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 *.** CAPI3REF: E
3760: 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 xtended Result C
3770: 6f 64 65 73 20 7b 48 31 30 32 32 30 7d 20 3c 53 odes {H10220} <S
3780: 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 10700>.** KEYWOR
3790: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 65 72 DS: {extended er
37a0: 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e ror code} {exten
37b0: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 7d ded error codes}
37c0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 .** KEYWORDS: {e
37d0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
37e0: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 72 ode} {extended r
37f0: 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a esult codes}.**.
3800: 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c ** In its defaul
3810: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c t configuration,
3820: 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 SQLite API rout
3830: 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 ines return one
3840: 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a of 26 integer.**
3850: 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 [SQLITE_OK | re
3860: 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f sult codes]. Ho
3870: 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 wever, experienc
3880: 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 e has shown that
3890: 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 many of.** thes
38a0: 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 e result codes a
38b0: 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 re too coarse-gr
38c0: 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 ained. They do
38d0: 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a not provide as.*
38e0: 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 * much informati
38f0: 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d on about problem
3900: 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 s as programmers
3910: 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e might like. In
3920: 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a an effort to.**
3930: 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e address this, n
3940: 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 ewer versions of
3950: 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e SQLite (version
3960: 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 3.3.8 and later
3970: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 ) include.** sup
3980: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f port for additio
3990: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 nal result codes
39a0: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f that provide mo
39b0: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f re detailed info
39c0: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 rmation.** about
39d0: 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65 78 74 errors. The ext
39e0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
39f0: 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f es are enabled o
3a00: 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e r disabled.** on
3a10: 20 61 20 70 65 72 20 64 61 74 61 62 61 73 65 20 a per database
3a20: 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 connection basis
3a30: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 using the.** [s
3a40: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f qlite3_extended_
3a50: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 result_codes()]
3a60: 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 API..**.** Some
3a70: 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 of the available
3a80: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 extended result
3a90: 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65 codes are liste
3aa0: 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d d here..** One m
3ab0: 61 79 20 65 78 70 65 63 74 20 74 68 65 20 6e 75 ay expect the nu
3ac0: 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65 64 mber of extended
3ad0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77 69 result codes wi
3ae0: 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20 ll be expand.**
3af0: 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 74 over time. Soft
3b00: 77 61 72 65 20 74 68 61 74 20 75 73 65 73 20 65 ware that uses e
3b10: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
3b20: 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70 65 odes should expe
3b30: 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77 ct.** to see new
3b40: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69 6e result codes in
3b50: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
3b60: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a of SQLite..**.*
3b70: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20 * The SQLITE_OK
3b80: 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c result code will
3b90: 20 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e 64 never be extend
3ba0: 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c 77 ed. It will alw
3bb0: 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c ays.** be exactl
3bc0: 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 y zero..*/.#defi
3bd0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
3be0: 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 READ
3bf0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
3c00: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (1<<8)).#defin
3c10: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 e SQLITE_IOERR_S
3c20: 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20 HORT_READ
3c30: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
3c40: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (2<<8)).#define
3c50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 SQLITE_IOERR_WR
3c60: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 ITE
3c70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
3c80: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (3<<8)).#define
3c90: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 SQLITE_IOERR_FSY
3ca0: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28 NC (
3cb0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
3cc0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 4<<8)).#define S
3cd0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f QLITE_IOERR_DIR_
3ce0: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 FSYNC (S
3cf0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 QLITE_IOERR | (5
3d00: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
3d10: 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 LITE_IOERR_TRUNC
3d20: 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51 ATE (SQ
3d30: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c LITE_IOERR | (6<
3d40: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
3d50: 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 ITE_IOERR_FSTAT
3d60: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
3d70: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c ITE_IOERR | (7<<
3d80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
3d90: 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 TE_IOERR_UNLOCK
3da0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
3db0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 TE_IOERR | (8<<8
3dc0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
3dd0: 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 E_IOERR_RDLOCK
3de0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
3df0: 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 E_IOERR | (9<<8)
3e00: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
3e10: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 _IOERR_DELETE
3e20: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
3e30: 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 _IOERR | (10<<8)
3e40: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
3e50: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 _IOERR_BLOCKED
3e60: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
3e70: 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 _IOERR | (11<<8)
3e80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
3e90: 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 _IOERR_NOMEM
3ea0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
3eb0: 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 _IOERR | (12<<8)
3ec0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
3ed0: 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20 _IOERR_ACCESS
3ee0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
3ef0: 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 _IOERR | (13<<8)
3f00: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
3f10: 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45 _IOERR_CHECKRESE
3f20: 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 RVEDLOCK (SQLITE
3f30: 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 _IOERR | (14<<8)
3f40: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
3f50: 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 _IOERR_LOCK
3f60: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
3f70: 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 _IOERR | (15<<8)
3f80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
3f90: 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 _IOERR_CLOSE
3fa0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
3fb0: 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 _IOERR | (16<<8)
3fc0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
3fd0: 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 _IOERR_DIR_CLOSE
3fe0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
3ff0: 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 _IOERR | (17<<8)
4000: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
4010: 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41 _LOCKED_SHAREDCA
4020: 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45 CHE (SQLITE
4030: 5f 4c 4f 43 4b 45 44 20 7c 20 28 31 3c 3c 38 29 _LOCKED | (1<<8)
4040: 20 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 )../*.** CAPI3R
4050: 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 EF: Flags For Fi
4060: 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f le Open Operatio
4070: 6e 73 20 7b 48 31 30 32 33 30 7d 20 3c 48 31 31 ns {H10230} <H11
4080: 31 32 30 3e 20 3c 48 31 32 37 30 30 3e 0a 2a 2a 120> <H12700>.**
4090: 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 .** These bit va
40a0: 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 lues are intende
40b0: 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 d for use in the
40c0: 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 .** 3rd paramete
40d0: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 r to the [sqlite
40e0: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 3_open_v2()] int
40f0: 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e erface and.** in
4100: 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 the 4th paramet
4110: 65 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 er to the xOpen
4120: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a 2a method of the.**
4130: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f [sqlite3_vfs] o
4140: 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e bject..*/.#defin
4150: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 e SQLITE_OPEN_RE
4160: 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 ADONLY 0
4170: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e x00000001.#defin
4180: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 e SQLITE_OPEN_RE
4190: 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20 30 ADWRITE 0
41a0: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e x00000002.#defin
41b0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 e SQLITE_OPEN_CR
41c0: 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20 30 EATE 0
41d0: 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e x00000004.#defin
41e0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 e SQLITE_OPEN_DE
41f0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 LETEONCLOSE 0
4200: 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e x00000008.#defin
4210: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 e SQLITE_OPEN_EX
4220: 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 30 CLUSIVE 0
4230: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e x00000010.#defin
4240: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 e SQLITE_OPEN_MA
4250: 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 IN_DB 0
4260: 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e x00000100.#defin
4270: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 e SQLITE_OPEN_TE
4280: 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 MP_DB 0
4290: 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e x00000200.#defin
42a0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 e SQLITE_OPEN_TR
42b0: 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 ANSIENT_DB 0
42c0: 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e x00000400.#defin
42d0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 e SQLITE_OPEN_MA
42e0: 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 IN_JOURNAL 0
42f0: 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e x00000800.#defin
4300: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 e SQLITE_OPEN_TE
4310: 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 MP_JOURNAL 0
4320: 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e x00001000.#defin
4330: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 e SQLITE_OPEN_SU
4340: 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 BJOURNAL 0
4350: 78 30 30 30 30 32 30 30 30 0a 23 64 65 66 69 6e x00002000.#defin
4360: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 e SQLITE_OPEN_MA
4370: 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 STER_JOURNAL 0
4380: 78 30 30 30 30 34 30 30 30 0a 23 64 65 66 69 6e x00004000.#defin
4390: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f e SQLITE_OPEN_NO
43a0: 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20 30 MUTEX 0
43b0: 78 30 30 30 30 38 30 30 30 0a 23 64 65 66 69 6e x00008000.#defin
43c0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 e SQLITE_OPEN_FU
43d0: 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 LLMUTEX 0
43e0: 78 30 30 30 31 30 30 30 30 0a 0a 2f 2a 0a 2a 2a x00010000../*.**
43f0: 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 CAPI3REF: Devic
4400: 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63 e Characteristic
4410: 73 20 7b 48 31 30 32 34 30 7d 20 3c 48 31 31 31 s {H10240} <H111
4420: 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 20>.**.** The xD
4430: 65 76 69 63 65 43 61 70 61 62 69 6c 69 74 69 65 eviceCapabilitie
4440: 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 s method of the
4450: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
4460: 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 ods].** object r
4470: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 eturns an intege
4480: 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 r which is a vec
4490: 74 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73 65 tor of the these
44a0: 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 .** bit values e
44b0: 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 xpressing I/O ch
44c0: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 aracteristics of
44d0: 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 the mass storag
44e0: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 e.** device that
44f0: 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 holds the file
4500: 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 that the [sqlite
4510: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 3_io_methods].**
4520: 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a refers to..**.*
4530: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 * The SQLITE_IOC
4540: 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 AP_ATOMIC proper
4550: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c ty means that al
4560: 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 l writes of.** a
4570: 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d ny size are atom
4580: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f ic. The SQLITE_
4590: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 IOCAP_ATOMICnnn
45a0: 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 values.** mean t
45b0: 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c hat writes of bl
45c0: 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e ocks that are nn
45d0: 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 n bytes in size
45e0: 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e and.** are align
45f0: 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 ed to an address
4600: 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 which is an int
4610: 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 eger multiple of
4620: 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d .** nnn are atom
4630: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f ic. The SQLITE_
4640: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e IOCAP_SAFE_APPEN
4650: 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a D value means.**
4660: 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 that when data
4670: 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 is appended to a
4680: 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 file, the data
4690: 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 is appended.** f
46a0: 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 irst then the si
46b0: 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 ze of the file i
46c0: 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 s extended, neve
46d0: 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 r the other.** w
46e0: 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 ay around. The
46f0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 SQLITE_IOCAP_SEQ
4700: 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 UENTIAL property
4710: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 means that.** i
4720: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 nformation is wr
4730: 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e itten to disk in
4740: 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 the same order
4750: 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 as calls.** to x
4760: 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 Write()..*/.#def
4770: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
4780: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 _ATOMIC
4790: 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 0x00000001.#def
47a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
47b0: 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 _ATOMIC512
47c0: 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 0x00000002.#def
47d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
47e0: 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 _ATOMIC1K
47f0: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 0x00000004.#def
4800: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
4810: 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 _ATOMIC2K
4820: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 0x00000008.#def
4830: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
4840: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 _ATOMIC4K
4850: 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 0x00000010.#def
4860: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
4870: 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 _ATOMIC8K
4880: 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 0x00000020.#def
4890: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
48a0: 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 _ATOMIC16K
48b0: 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 0x00000040.#def
48c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
48d0: 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 _ATOMIC32K
48e0: 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 0x00000080.#def
48f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
4900: 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 _ATOMIC64K
4910: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 0x00000100.#def
4920: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
4930: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 _SAFE_APPEND
4940: 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 0x00000200.#def
4950: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
4960: 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 _SEQUENTIAL
4970: 20 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 0x00000400../*.
4980: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c ** CAPI3REF: Fil
4990: 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 e Locking Levels
49a0: 20 7b 48 31 30 32 35 30 7d 20 3c 48 31 31 31 32 {H10250} <H1112
49b0: 30 3e 20 3c 48 31 31 33 31 30 3e 0a 2a 2a 0a 2a 0> <H11310>.**.*
49c0: 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e * SQLite uses on
49d0: 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 e of these integ
49e0: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 er values as the
49f0: 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d second.** argum
4a00: 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 ent to calls it
4a10: 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f makes to the xLo
4a20: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b ck() and xUnlock
4a30: 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 () methods.** of
4a40: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f an [sqlite3_io_
4a50: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e methods] object.
4a60: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
4a70: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 TE_LOCK_NONE
4a80: 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 0.#define
4a90: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 SQLITE_LOCK_SHAR
4aa0: 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 ED 1.#def
4ab0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f ine SQLITE_LOCK_
4ac0: 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a RESERVED 2.
4ad0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
4ae0: 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 OCK_PENDING
4af0: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 3.#define SQLI
4b00: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 TE_LOCK_EXCLUSIV
4b10: 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 E 4../*.** C
4b20: 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f API3REF: Synchro
4b30: 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c nization Type Fl
4b40: 61 67 73 20 7b 48 31 30 32 36 30 7d 20 3c 48 31 ags {H10260} <H1
4b50: 31 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 1120>.**.** When
4b60: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 SQLite invokes
4b70: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 the xSync() meth
4b80: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c od of an.** [sql
4b90: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
4ba0: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 object it uses
4bb0: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 a combination of
4bc0: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 .** these intege
4bd0: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 r values as the
4be0: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e second argument.
4bf0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 .**.** When the
4c00: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 SQLITE_SYNC_DATA
4c10: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 ONLY flag is use
4c20: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 d, it means that
4c30: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 the.** sync ope
4c40: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 ration only need
4c50: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 s to flush data
4c60: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e to mass storage.
4c70: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 Inode.** infor
4c80: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 mation need not
4c90: 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 be flushed. If t
4ca0: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 he lower four bi
4cb0: 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a ts of the flag.*
4cc0: 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 * equal SQLITE_S
4cd0: 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 YNC_NORMAL, that
4ce0: 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f means to use no
4cf0: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d rmal fsync() sem
4d00: 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 antics..** If th
4d10: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 e lower four bit
4d20: 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 s equal SQLITE_S
4d30: 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d YNC_FULL, that m
4d40: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d eans.** to use M
4d50: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 ac OS X style fu
4d60: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f llsync instead o
4d70: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64 f fsync()..*/.#d
4d80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e efine SQLITE_SYN
4d90: 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 C_NORMAL
4da0: 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 0x00002.#define
4db0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c SQLITE_SYNC_FULL
4dc0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
4dd0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 3.#define SQLITE
4de0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 _SYNC_DATAONLY
4df0: 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 0x00010../*.
4e00: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 ** CAPI3REF: OS
4e10: 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 Interface Open F
4e20: 69 6c 65 20 48 61 6e 64 6c 65 20 7b 48 31 31 31 ile Handle {H111
4e30: 31 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 10} <S20110>.**.
4e40: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 ** An [sqlite3_f
4e50: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 ile] object repr
4e60: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 esents an open f
4e70: 69 6c 65 20 69 6e 20 74 68 65 20 4f 53 0a 2a 2a ile in the OS.**
4e80: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 interface layer
4e90: 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 . Individual OS
4ea0: 20 69 6e 74 65 72 66 61 63 65 20 69 6d 70 6c 65 interface imple
4eb0: 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a mentations will.
4ec0: 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c ** want to subcl
4ed0: 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 ass this object
4ee0: 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 by appending add
4ef0: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a itional fields.*
4f00: 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 * for their own
4f10: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f use. The pMetho
4f20: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f ds entry is a po
4f30: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b inter to an.** [
4f40: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
4f50: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 ds] object that
4f60: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 defines methods
4f70: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a for performing.*
4f80: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 * I/O operations
4f90: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c on the open fil
4fa0: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 e..*/.typedef st
4fb0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c ruct sqlite3_fil
4fc0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a e sqlite3_file;.
4fd0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 struct sqlite3_f
4fe0: 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 ile {. const st
4ff0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f ruct sqlite3_io_
5000: 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 methods *pMethod
5010: 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 s; /* Methods f
5020: 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 or an open file
5030: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.};../*.** CAP
5040: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 I3REF: OS Interf
5050: 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c ace File Virtual
5060: 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 20 Methods Object
5070: 7b 48 31 31 31 32 30 7d 20 3c 53 32 30 31 31 30 {H11120} <S20110
5080: 3e 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 >.**.** Every fi
5090: 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 le opened by the
50a0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 [sqlite3_vfs] x
50b0: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f 70 75 Open method popu
50c0: 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c lates an.** [sql
50d0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 ite3_file] objec
50e0: 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d t (or, more comm
50f0: 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 only, a subclass
5100: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 of the.** [sqli
5110: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 te3_file] object
5120: 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 ) with a pointer
5130: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 to an instance
5140: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a of this object..
5150: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 ** This object d
5160: 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f efines the metho
5170: 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f ds used to perfo
5180: 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 rm various opera
5190: 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 tions.** against
51a0: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 the open file r
51b0: 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 epresented by th
51c0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d e [sqlite3_file]
51d0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 object..**.** T
51e0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e he flags argumen
51f0: 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 t to xSync may b
5200: 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 e one of [SQLITE
5210: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 _SYNC_NORMAL] or
5220: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 .** [SQLITE_SYNC
5230: 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 _FULL]. The fir
5240: 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 st choice is the
5250: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e normal fsync().
5260: 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 .** The second c
5270: 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f hoice is a Mac O
5280: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 S X style fullsy
5290: 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 nc. The [SQLITE
52a0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a _SYNC_DATAONLY].
52b0: 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f ** flag may be O
52c0: 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 Red in to indica
52d0: 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 te that only the
52e0: 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c data of the fil
52f0: 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 e.** and not its
5300: 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 inode needs to
5310: 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a be synced..**.**
5320: 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c The integer val
5330: 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 ues to xLock() a
5340: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 nd xUnlock() are
5350: 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a one of.** <ul>.
5360: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
5370: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c LOCK_NONE],.** <
5380: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b li> [SQLITE_LOCK
5390: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 _SHARED],.** <li
53a0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 > [SQLITE_LOCK_R
53b0: 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 ESERVED],.** <li
53c0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 > [SQLITE_LOCK_P
53d0: 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c ENDING], or.** <
53e0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b li> [SQLITE_LOCK
53f0: 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 _EXCLUSIVE]..**
5400: 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 </ul>.** xLock()
5410: 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c increases the l
5420: 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 ock. xUnlock() d
5430: 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 ecreases the loc
5440: 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b k..** The xCheck
5450: 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d ReservedLock() m
5460: 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 ethod checks whe
5470: 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 ther any databas
5480: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a e connection,.**
5490: 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 either in this
54a0: 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f process or in so
54b0: 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 me other process
54c0: 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 , is holding a R
54d0: 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 ESERVED,.** PEND
54e0: 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 ING, or EXCLUSIV
54f0: 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 E lock on the fi
5500: 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 le. It returns
5510: 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 true.** if such
5520: 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e a lock exists an
5530: 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 d false otherwis
5540: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 e..**.** The xFi
5550: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 leControl() meth
5560: 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 od is a generic
5570: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 interface that a
5580: 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 llows custom.**
5590: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 VFS implementati
55a0: 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 ons to directly
55b0: 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 control an open
55c0: 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a file using the.*
55d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f * [sqlite3_file_
55e0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 control()] inter
55f0: 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e face. The secon
5600: 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 d "op" argument
5610: 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 is an.** integer
5620: 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 opcode. The th
5630: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ird argument is
5640: 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 a generic pointe
5650: 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a r intended to.**
5660: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 point to a stru
5670: 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 cture that may c
5680: 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 ontain arguments
5690: 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 or space in whi
56a0: 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 ch to.** write r
56b0: 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 eturn values. P
56c0: 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f otential uses fo
56d0: 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 r xFileControl()
56e0: 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e might be.** fun
56f0: 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 ctions to enable
5700: 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 blocking locks
5710: 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 with timeouts, t
5720: 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 o change the.**
5730: 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 locking strategy
5740: 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f (for example to
5750: 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f use dot-file lo
5760: 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 cks), to inquire
5770: 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 .** about the st
5780: 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 atus of a lock,
5790: 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c or to break stal
57a0: 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 e locks. The SQ
57b0: 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 Lite.** core res
57c0: 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 erves all opcode
57d0: 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 s less than 100
57e0: 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e for its own use.
57f0: 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 .** A [SQLITE_FC
5800: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 NTL_LOCKSTATE |
5810: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d list of opcodes]
5820: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 less than 100 i
5830: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 s available..**
5840: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 Applications tha
5850: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f t define a custo
5860: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d m xFileControl m
5870: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 ethod should use
5880: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 opcodes.** grea
5890: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 ter than 100 to
58a0: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e avoid conflicts.
58b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 .**.** The xSect
58c0: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 orSize() method
58d0: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 returns the sect
58e0: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a or size of the.*
58f0: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e * device that un
5900: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 derlies the file
5910: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 . The sector si
5920: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e ze is the.** min
5930: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 imum write that
5940: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 can be performed
5950: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 without disturb
5960: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 ing.** other byt
5970: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 es in the file.
5980: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 The xDeviceChar
5990: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a acteristics().**
59a0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 method returns
59b0: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 a bit vector des
59c0: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 cribing behavior
59d0: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 s of the.** unde
59e0: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a rlying device:.*
59f0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
5a00: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
5a10: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 ATOMIC].** <li>
5a20: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
5a30: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e OMIC512].** <li>
5a40: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
5a50: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e TOMIC1K].** <li>
5a60: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
5a70: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e TOMIC2K].** <li>
5a80: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
5a90: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e TOMIC4K].** <li>
5aa0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
5ab0: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e TOMIC8K].** <li>
5ac0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
5ad0: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 TOMIC16K].** <li
5ae0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
5af0: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c ATOMIC32K].** <l
5b00: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
5b10: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c _ATOMIC64K].** <
5b20: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
5b30: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a P_SAFE_APPEND].*
5b40: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
5b50: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d OCAP_SEQUENTIAL]
5b60: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
5b70: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
5b80: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 _ATOMIC property
5b90: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 means that all
5ba0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 writes of.** any
5bb0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 size are atomic
5bc0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
5bd0: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 CAP_ATOMICnnn va
5be0: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 lues.** mean tha
5bf0: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 t writes of bloc
5c00: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 ks that are nnn
5c10: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e bytes in size an
5c20: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 d.** are aligned
5c30: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 to an address w
5c40: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 hich is an integ
5c50: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a er multiple of.*
5c60: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 * nnn are atomic
5c70: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
5c80: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 CAP_SAFE_APPEND
5c90: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 value means.** t
5ca0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 hat when data is
5cb0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 appended to a f
5cc0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 ile, the data is
5cd0: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 appended.** fir
5ce0: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 st then the size
5cf0: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 of the file is
5d00: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 extended, never
5d10: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 the other.** way
5d20: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 around. The SQ
5d30: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 LITE_IOCAP_SEQUE
5d40: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d NTIAL property m
5d50: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 eans that.** inf
5d60: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 ormation is writ
5d70: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 ten to disk in t
5d80: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 he same order as
5d90: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 calls.** to xWr
5da0: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 ite()..**.** If
5db0: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 xRead() returns
5dc0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f SQLITE_IOERR_SHO
5dd0: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 RT_READ it must
5de0: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 also fill.** in
5df0: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 the unread porti
5e00: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 ons of the buffe
5e10: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 r with zeros. A
5e20: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 VFS that.** fai
5e30: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 ls to zero-fill
5e40: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 short reads migh
5e50: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 t seem to work.
5e60: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 However,.** fai
5e70: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c lure to zero-fil
5e80: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 l short reads wi
5e90: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 ll eventually le
5ea0: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 ad to.** databas
5eb0: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f e corruption..*/
5ec0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
5ed0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
5ee0: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 ds sqlite3_io_me
5ef0: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 thods;.struct sq
5f00: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
5f10: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f {. int iVersio
5f20: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 n;. int (*xClos
5f30: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a e)(sqlite3_file*
5f40: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 );. int (*xRead
5f50: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
5f60: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 void*, int iAmt
5f70: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
5f80: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a iOfst);. int (*
5f90: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f xWrite)(sqlite3_
5fa0: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 file*, const voi
5fb0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 d*, int iAmt, sq
5fc0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 lite3_int64 iOfs
5fd0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 t);. int (*xTru
5fe0: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 ncate)(sqlite3_f
5ff0: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e ile*, sqlite3_in
6000: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 t64 size);. int
6010: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 (*xSync)(sqlite
6020: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 3_file*, int fla
6030: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 gs);. int (*xFi
6040: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f leSize)(sqlite3_
6050: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 file*, sqlite3_i
6060: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 nt64 *pSize);.
6070: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c int (*xLock)(sql
6080: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 ite3_file*, int)
6090: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 ;. int (*xUnloc
60a0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a k)(sqlite3_file*
60b0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a , int);. int (*
60c0: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f xCheckReservedLo
60d0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ck)(sqlite3_file
60e0: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 *, int *pResOut)
60f0: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 ;. int (*xFileC
6100: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f ontrol)(sqlite3_
6110: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 file*, int op, v
6120: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e oid *pArg);. in
6130: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 t (*xSectorSize)
6140: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b (sqlite3_file*);
6150: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 . int (*xDevice
6160: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29 Characteristics)
6170: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b (sqlite3_file*);
6180: 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c . /* Additional
6190: 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 methods may be
61a0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 added in future
61b0: 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a releases */.};..
61c0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
61d0: 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f Standard File Co
61e0: 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 20 7b 48 ntrol Opcodes {H
61f0: 31 31 33 31 30 7d 20 3c 53 33 30 38 30 30 3e 0a 11310} <S30800>.
6200: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 **.** These inte
6210: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 ger constants ar
6220: 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 e opcodes for th
6230: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d e xFileControl m
6240: 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 ethod.** of the
6250: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
6260: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 ods] object and
6270: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 for the [sqlite3
6280: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d _file_control()]
6290: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a .** interface..*
62a0: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 *.** The [SQLITE
62b0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 _FCNTL_LOCKSTATE
62c0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 ] opcode is used
62d0: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 for debugging.
62e0: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 This.** opcode
62f0: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 causes the xFile
6300: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 Control method t
6310: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 o write the curr
6320: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 ent state of.**
6330: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 the lock (one of
6340: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f [SQLITE_LOCK_NO
6350: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 NE], [SQLITE_LOC
6360: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 K_SHARED],.** [S
6370: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 QLITE_LOCK_RESER
6380: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f VED], [SQLITE_LO
6390: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 CK_PENDING], or
63a0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 [SQLITE_LOCK_EXC
63b0: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f LUSIVE]).** into
63c0: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 an integer that
63d0: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 the pArg argume
63e0: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 nt points to. Th
63f0: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a is capability.**
6400: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 is used during
6410: 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 testing and only
6420: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 needs to be sup
6430: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 ported when SQLI
6440: 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 TE_TEST.** is de
6450: 66 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e fined..*/.#defin
6460: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c e SQLITE_FCNTL_L
6470: 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 OCKSTATE
6480: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
6490: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 _GET_LOCKPROXYFI
64a0: 4c 45 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e LE 2.#defin
64b0: 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 e SQLITE_SET_LOC
64c0: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 KPROXYFILE
64d0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 3.#define SQLITE
64e0: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 _LAST_ERRNO
64f0: 20 20 20 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 4../*.**
6500: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 CAPI3REF: Mutex
6510: 20 48 61 6e 64 6c 65 20 7b 48 31 37 31 31 30 7d Handle {H17110}
6520: 20 3c 53 32 30 31 33 30 3e 0a 2a 2a 0a 2a 2a 20 <S20130>.**.**
6530: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 The mutex module
6540: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 within SQLite d
6550: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f efines [sqlite3_
6560: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a mutex] to be an.
6570: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65 ** abstract type
6580: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a for a mutex obj
6590: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 ect. The SQLite
65a0: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b core never look
65b0: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 s.** at the inte
65c0: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 rnal representat
65d0: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 ion of an [sqlit
65e0: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f e3_mutex]. It o
65f0: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 nly.** deals wit
6600: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 h pointers to th
6610: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 e [sqlite3_mutex
6620: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 ] object..**.**
6630: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61 Mutexes are crea
6640: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ted using [sqlit
6650: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 e3_mutex_alloc()
6660: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 ]..*/.typedef st
6670: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 ruct sqlite3_mut
6680: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 ex sqlite3_mutex
6690: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
66a0: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 F: OS Interface
66b0: 4f 62 6a 65 63 74 20 7b 48 31 31 31 34 30 7d 20 Object {H11140}
66c0: 3c 53 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 <S20100>.**.** A
66d0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
66e0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 e sqlite3_vfs ob
66f0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 ject defines the
6700: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 interface betwe
6710: 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 en.** the SQLite
6720: 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e core and the un
6730: 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 derlying operati
6740: 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 ng system. The
6750: 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 "vfs".** in the
6760: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 name of the obje
6770: 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 ct stands for "v
6780: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 irtual file syst
6790: 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 em"..**.** The v
67a0: 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 alue of the iVer
67b0: 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e sion field is in
67c0: 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 itially 1 but ma
67d0: 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a y be larger in.*
67e0: 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e * future version
67f0: 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 s of SQLite. Ad
6800: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 ditional fields
6810: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 may be appended
6820: 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 to this.** objec
6830: 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 t when the iVers
6840: 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 ion value is inc
6850: 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 reased. Note th
6860: 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65 at the structure
6870: 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 .** of the sqlit
6880: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 e3_vfs object ch
6890: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 anges in the tra
68a0: 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e nsaction between
68b0: 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 .** SQLite versi
68c0: 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 on 3.5.9 and 3.6
68d0: 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 .0 and yet the i
68e0: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 Version field wa
68f0: 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 s not.** modifie
6900: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f d..**.** The szO
6910: 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 sFile field is t
6920: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 he size of the s
6930: 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 ubclassed [sqlit
6940: 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 e3_file].** stru
6950: 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 cture used by th
6960: 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e is VFS. mxPathn
6970: 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d ame is the maxim
6980: 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 um length of.**
6990: 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 a pathname in th
69a0: 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 is VFS..**.** Re
69b0: 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 gistered sqlite3
69c0: 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 _vfs objects are
69d0: 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 kept on a linke
69e0: 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 d list formed by
69f0: 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f .** the pNext po
6a00: 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c inter. The [sql
6a10: 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 ite3_vfs_registe
6a20: 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c r()].** and [sql
6a30: 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 ite3_vfs_unregis
6a40: 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ter()] interface
6a50: 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 s manage this li
6a60: 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 st.** in a threa
6a70: 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 d-safe way. The
6a80: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 [sqlite3_vfs_fi
6a90: 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a nd()] interface.
6aa0: 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 ** searches the
6ab0: 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 list. Neither t
6ac0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 he application c
6ad0: 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a ode nor the VFS.
6ae0: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
6af0: 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 n should use the
6b00: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a pNext pointer..
6b10: 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 **.** The pNext
6b20: 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c field is the onl
6b30: 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 y field in the s
6b40: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 qlite3_vfs.** st
6b50: 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c ructure that SQL
6b60: 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f ite will ever mo
6b70: 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 dify. SQLite wi
6b80: 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a ll only access.*
6b90: 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 * or modify this
6ba0: 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c field while hol
6bb0: 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 ding a particula
6bc0: 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a r static mutex..
6bd0: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
6be0: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 on should never
6bf0: 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 modify anything
6c00: 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 within the sqlit
6c10: 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 e3_vfs.** object
6c20: 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 once the object
6c30: 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 has been regist
6c40: 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ered..**.** The
6c50: 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 zName field hold
6c60: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
6c70: 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 e VFS module. T
6c80: 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 he name must.**
6c90: 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 be unique across
6ca0: 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 all VFS modules
6cb0: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 ..**.** SQLite w
6cc0: 69 6c 6c 20 67 75 61 72 61 6e 74 65 65 20 74 68 ill guarantee th
6cd0: 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 at the zFilename
6ce0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f parameter to xO
6cf0: 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 pen.** is either
6d00: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
6d10: 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e or string obtain
6d20: 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c ed.** from xFull
6d30: 50 61 74 68 6e 61 6d 65 28 29 2e 20 20 53 51 4c Pathname(). SQL
6d40: 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72 ite further guar
6d50: 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 antees that.** t
6d60: 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 he string will b
6d70: 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 e valid and unch
6d80: 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f anged until xClo
6d90: 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 se() is.** calle
6da0: 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 d. Because of th
6db0: 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 e previous sente
6dc0: 6e 73 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c nse,.** the [sql
6dd0: 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 ite3_file] can s
6de0: 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f afely store a po
6df0: 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 inter to the.**
6e00: 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e filename if it n
6e10: 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 eeds to remember
6e20: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f the filename fo
6e30: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a r some reason..*
6e40: 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 * If the zFilena
6e50: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 me parameter is
6e60: 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 xOpen is a NULL
6e70: 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 pointer then xOp
6e80: 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 69 74 en.** must invit
6e90: 65 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 e its own tempor
6ea0: 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 ary name for the
6eb0: 20 66 69 6c 65 2e 20 20 57 68 65 6e 65 76 65 72 file. Whenever
6ec0: 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 the .** xFilena
6ed0: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 me parameter is
6ee0: 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 NULL it will als
6ef0: 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 o be the case th
6f00: 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 at the.** flags
6f10: 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 parameter will i
6f20: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f nclude [SQLITE_O
6f30: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 PEN_DELETEONCLOS
6f40: 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c E]..**.** The fl
6f50: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ags argument to
6f60: 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 xOpen() includes
6f70: 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e all bits set in
6f80: 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 .** the flags ar
6f90: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 gument to [sqlit
6fa0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 e3_open_v2()].
6fb0: 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f Or if [sqlite3_o
6fc0: 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 pen()].** or [sq
6fd0: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 lite3_open16()]
6fe0: 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c is used, then fl
6ff0: 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 ags includes at
7000: 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 least.** [SQLITE
7010: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d _OPEN_READWRITE]
7020: 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f | [SQLITE_OPEN_
7030: 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 CREATE]. .** If
7040: 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 xOpen() opens a
7050: 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 file read-only t
7060: 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 hen it sets *pOu
7070: 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 tFlags to.** inc
7080: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 lude [SQLITE_OPE
7090: 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 N_READONLY]. Ot
70a0: 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 her bits in *pOu
70b0: 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 tFlags may be se
70c0: 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 t..**.** SQLite
70d0: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e will also add on
70e0: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 e of the followi
70f0: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 ng flags to the
7100: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c xOpen().** call,
7110: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 depending on th
7120: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f e object being o
7130: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c pened:.**.** <ul
7140: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 >.** <li> [SQLI
7150: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d TE_OPEN_MAIN_DB]
7160: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
7170: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 E_OPEN_MAIN_JOUR
7180: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 NAL].** <li> [S
7190: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
71a0: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 DB].** <li> [SQ
71b0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a LITE_OPEN_TEMP_J
71c0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 OURNAL].** <li>
71d0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 [SQLITE_OPEN_TR
71e0: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c ANSIENT_DB].** <
71f0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
7200: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a N_SUBJOURNAL].**
7210: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
7220: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e PEN_MASTER_JOURN
7230: 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a AL].** </ul>.**.
7240: 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 ** The file I/O
7250: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 implementation c
7260: 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 an use the objec
7270: 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a t type flags to.
7280: 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 ** change the wa
7290: 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 y it deals with
72a0: 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d files. For exam
72b0: 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 ple, an applicat
72c0: 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 ion.** that does
72d0: 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 not care about
72e0: 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f crash recovery o
72f0: 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 r rollback might
7300: 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 make.** the ope
7310: 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 n of a journal f
7320: 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 ile a no-op. Wr
7330: 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 ites to this jou
7340: 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c rnal would.** al
7350: 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e so be no-ops, an
7360: 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f d any attempt to
7370: 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 read the journa
7380: 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a l would return.*
7390: 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 * SQLITE_IOERR.
73a0: 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e Or the implemen
73b0: 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 tation might rec
73c0: 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 ognize that a da
73d0: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 tabase.** file w
73e0: 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 ill be doing pag
73f0: 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 e-aligned sector
7400: 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 reads and write
7410: 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a s in a random.**
7420: 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 order and set u
7430: 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 p its I/O subsys
7440: 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e tem accordingly.
7450: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 .**.** SQLite mi
7460: 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 ght also add one
7470: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e of the followin
7480: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 g flags to the x
7490: 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a Open method:.**.
74a0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
74b0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c [SQLITE_OPEN_DEL
74c0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c ETEONCLOSE].** <
74d0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e li> [SQLITE_OPEN
74e0: 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c _EXCLUSIVE].** <
74f0: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b /ul>.**.** The [
7500: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 SQLITE_OPEN_DELE
7510: 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 TEONCLOSE] flag
7520: 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 means the file s
7530: 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 hould be.** dele
7540: 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 ted when it is c
7550: 6c 6f 73 65 64 2e 20 20 54 68 65 20 5b 53 51 4c losed. The [SQL
7560: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f ITE_OPEN_DELETEO
7570: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 NCLOSE].** will
7580: 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 be set for TEMP
7590: 20 64 61 74 61 62 61 73 65 73 2c 20 6a 6f 75 72 databases, jour
75a0: 6e 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 62 nals and for sub
75b0: 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 journals..**.**
75c0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e The [SQLITE_OPEN
75d0: 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 _EXCLUSIVE] flag
75e0: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 means the file
75f0: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 should be opened
7600: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 .** for exclusiv
7610: 65 20 61 63 63 65 73 73 2e 20 20 54 68 69 73 20 e access. This
7620: 66 6c 61 67 20 69 73 20 73 65 74 20 66 6f 72 20 flag is set for
7630: 61 6c 6c 20 66 69 6c 65 73 20 65 78 63 65 70 74 all files except
7640: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 61 69 6e .** for the main
7650: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a database file..
7660: 2a 2a 0a 2a 2a 20 41 74 20 6c 65 61 73 74 20 73 **.** At least s
7670: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 zOsFile bytes of
7680: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f memory are allo
7690: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a cated by SQLite.
76a0: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 ** to hold the
76b0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 [sqlite3_file] s
76c0: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 tructure passed
76d0: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 as the third.**
76e0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 argument to xOpe
76f0: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 n. The xOpen me
7700: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 thod does not ha
7710: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 ve to.** allocat
7720: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b e the structure;
7730: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 it should just
7740: 66 69 6c 6c 20 69 74 20 69 6e 2e 0a 2a 2a 0a 2a fill it in..**.*
7750: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 * The flags argu
7760: 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 ment to xAccess(
7770: 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 ) may be [SQLITE
7780: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a _ACCESS_EXISTS].
7790: 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 ** to test for t
77a0: 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 he existence of
77b0: 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 a file, or [SQLI
77c0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 TE_ACCESS_READWR
77d0: 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 ITE] to.** test
77e0: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 whether a file i
77f0: 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 s readable and w
7800: 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c ritable, or [SQL
7810: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d ITE_ACCESS_READ]
7820: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 .** to test whet
7830: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 her a file is at
7840: 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e least readable.
7850: 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 The file can
7860: 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 be a.** director
7870: 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 y..**.** SQLite
7880: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f will always allo
7890: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 cate at least mx
78a0: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 Pathname+1 bytes
78b0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 for the.** outp
78c0: 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 ut buffer xFullP
78d0: 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 athname. The ex
78e0: 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 act size of the
78f0: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a output buffer.**
7900: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 is also passed
7910: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 as a parameter t
7920: 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e o both methods.
7930: 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 If the output b
7940: 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 uffer.** is not
7950: 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 large enough, [S
7960: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 QLITE_CANTOPEN]
7970: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e should be return
7980: 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 ed. Since this i
7990: 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 s.** handled as
79a0: 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 a fatal error by
79b0: 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 SQLite, vfs imp
79c0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f lementations sho
79d0: 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 uld endeavor.**
79e0: 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 to prevent this
79f0: 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 by setting mxPat
7a00: 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 hname to a suffi
7a10: 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 ciently large va
7a20: 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 lue..**.** The x
7a30: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 Randomness(), xS
7a40: 6c 65 65 70 28 29 2c 20 61 6e 64 20 78 43 75 72 leep(), and xCur
7a50: 72 65 6e 74 54 69 6d 65 28 29 20 69 6e 74 65 72 rentTime() inter
7a60: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 faces.** are not
7a70: 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 strictly a part
7a80: 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 of the filesyst
7a90: 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 em, but they are
7aa0: 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 .** included in
7ab0: 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72 the VFS structur
7ac0: 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 e for completene
7ad0: 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 ss..** The xRand
7ae0: 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f omness() functio
7af0: 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 n attempts to re
7b00: 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 turn nBytes byte
7b10: 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 s.** of good-qua
7b20: 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 lity randomness
7b30: 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 into zOut. The
7b40: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a return value is.
7b50: 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 ** the actual nu
7b60: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 mber of bytes of
7b70: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 randomness obta
7b80: 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c ined..** The xSl
7b90: 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 eep() method cau
7ba0: 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 ses the calling
7bb0: 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 thread to sleep
7bc0: 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 for at.** least
7bd0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 the number of mi
7be0: 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e croseconds given
7bf0: 2e 20 20 54 68 65 20 78 43 75 72 72 65 6e 74 54 . The xCurrentT
7c00: 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 ime().** method
7c10: 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e returns a Julian
7c20: 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 Day Number for
7c30: 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 the current date
7c40: 20 61 6e 64 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2f and time..**.*/
7c50: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
7c60: 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 sqlite3_vfs sqli
7c70: 74 65 33 5f 76 66 73 3b 0a 73 74 72 75 63 74 20 te3_vfs;.struct
7c80: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 sqlite3_vfs {.
7c90: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 int iVersion;
7ca0: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 /* Stru
7cb0: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 cture version nu
7cc0: 6d 62 65 72 20 2a 2f 0a 20 20 69 6e 74 20 73 7a mber */. int sz
7cd0: 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 OsFile;
7ce0: 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 /* Size of su
7cf0: 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 bclassed sqlite3
7d00: 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d _file */. int m
7d10: 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 xPathname;
7d20: 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 /* Maximum f
7d30: 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e ile pathname len
7d40: 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 gth */. sqlite3
7d50: 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 _vfs *pNext;
7d60: 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 /* Next regist
7d70: 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f ered VFS */. co
7d80: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b nst char *zName;
7d90: 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f /* Name o
7da0: 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 f this virtual f
7db0: 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 ile system */.
7dc0: 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 void *pAppData;
7dd0: 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e /* Poin
7de0: 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 ter to applicati
7df0: 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 on-specific data
7e00: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 */. int (*xOpe
7e10: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c n)(sqlite3_vfs*,
7e20: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
7e30: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 me, sqlite3_file
7e40: 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 *,.
7e50: 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 int flags, int
7e60: 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 *pOutFlags);.
7e70: 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 int (*xDelete)(s
7e80: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
7e90: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
7ea0: 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 int syncDir);.
7eb0: 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 int (*xAccess)(s
7ec0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
7ed0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
7ee0: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a int flags, int *
7ef0: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 pResOut);. int
7f00: 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 (*xFullPathname)
7f10: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
7f20: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
7f30: 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 , int nOut, char
7f40: 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 *zOut);. void
7f50: 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 *(*xDlOpen)(sqli
7f60: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
7f70: 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 char *zFilename)
7f80: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 ;. void (*xDlEr
7f90: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ror)(sqlite3_vfs
7fa0: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 *, int nByte, ch
7fb0: 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 ar *zErrMsg);.
7fc0: 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 void (*(*xDlSym)
7fd0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f (sqlite3_vfs*,vo
7fe0: 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 id*, const char
7ff0: 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 *zSymbol))(void)
8000: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c ;. void (*xDlCl
8010: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ose)(sqlite3_vfs
8020: 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 *, void*);. int
8030: 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 (*xRandomness)(
8040: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e sqlite3_vfs*, in
8050: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a t nByte, char *z
8060: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 Out);. int (*xS
8070: 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 leep)(sqlite3_vf
8080: 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 s*, int microsec
8090: 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 onds);. int (*x
80a0: 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c CurrentTime)(sql
80b0: 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c ite3_vfs*, doubl
80c0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 e*);. int (*xGe
80d0: 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 tLastError)(sqli
80e0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 te3_vfs*, int, c
80f0: 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 har *);. /* New
8100: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 fields may be a
8110: 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 ppended in figur
8120: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 e versions. The
8130: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 iVersion. ** v
8140: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d alue will increm
8150: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 ent whenever thi
8160: 73 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b s happens. */.};
8170: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
8180: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 : Flags for the
8190: 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 xAccess VFS meth
81a0: 6f 64 20 7b 48 31 31 31 39 30 7d 20 3c 48 31 31 od {H11190} <H11
81b0: 31 34 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 140>.**.** These
81c0: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e integer constan
81d0: 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 ts can be used a
81e0: 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 s the third para
81f0: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 meter to.** the
8200: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f xAccess method o
8210: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 f an [sqlite3_vf
8220: 73 5d 20 6f 62 6a 65 63 74 2e 20 7b 45 4e 44 7d s] object. {END}
8230: 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 They determine
8240: 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 .** what kind of
8250: 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 permissions the
8260: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 xAccess method
8270: 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a is looking for..
8280: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 ** With SQLITE_A
8290: 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 CCESS_EXISTS, th
82a0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 e xAccess method
82b0: 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b .** simply check
82c0: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 s whether the fi
82d0: 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 le exists..** Wi
82e0: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 th SQLITE_ACCESS
82f0: 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 _READWRITE, the
8300: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a xAccess method.*
8310: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 * checks whether
8320: 20 74 68 65 20 66 69 6c 65 20 69 73 20 62 6f 74 the file is bot
8330: 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 h readable and w
8340: 72 69 74 61 62 6c 65 2e 0a 2a 2a 20 57 69 74 68 ritable..** With
8350: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 SQLITE_ACCESS_R
8360: 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 EAD, the xAccess
8370: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b method.** check
8380: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 s whether the fi
8390: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 0a le is readable..
83a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
83b0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 E_ACCESS_EXISTS
83c0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0.#define SQL
83d0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 ITE_ACCESS_READW
83e0: 52 49 54 45 20 31 0a 23 64 65 66 69 6e 65 20 53 RITE 1.#define S
83f0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
8400: 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 D 2../*.**
8410: 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 CAPI3REF: Initia
8420: 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 lize The SQLite
8430: 4c 69 62 72 61 72 79 20 7b 48 31 30 31 33 30 7d Library {H10130}
8440: 20 3c 53 32 30 30 30 30 3e 3c 53 33 30 31 30 30 <S20000><S30100
8450: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 >.**.** The sqli
8460: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
8470: 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c routine initial
8480: 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 izes the.** SQLi
8490: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 te library. The
84a0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
84b0: 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 n() routine.** d
84c0: 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 eallocates any r
84d0: 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 esources that we
84e0: 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 re allocated by
84f0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
8500: 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 ze()..**.** A ca
8510: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e ll to sqlite3_in
8520: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e itialize() is an
8530: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c "effective" cal
8540: 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 l if it is.** th
8550: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c e first time sql
8560: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
8570: 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 ) is invoked dur
8580: 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 ing the lifetime
8590: 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 of.** the proce
85a0: 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 ss, or if it is
85b0: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 the first time s
85c0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
85d0: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a e() is invoked.*
85e0: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 * following a ca
85f0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 ll to sqlite3_sh
8600: 75 74 64 6f 77 6e 28 29 2e 20 20 4f 6e 6c 79 20 utdown(). Only
8610: 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c an effective cal
8620: 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f l.** of sqlite3_
8630: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 initialize() doe
8640: 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 s any initializa
8650: 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 tion. All other
8660: 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 calls.** are ha
8670: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 0a 2a rmless no-ops..*
8680: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 *.** A call to s
8690: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
86a0: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 ) is an "effecti
86b0: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 ve" call if it i
86c0: 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 s the first.** c
86d0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 all to sqlite3_s
86e0: 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 hutdown() since
86f0: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 the last sqlite3
8700: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 _initialize().
8710: 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 Only.** an effec
8720: 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c tive call to sql
8730: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 ite3_shutdown()
8740: 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 does any deiniti
8750: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c alization..** Al
8760: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 20 74 6f l other calls to
8770: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
8780: 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 n() are harmless
8790: 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 41 no-ops..**.** A
87a0: 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 mong other thing
87b0: 73 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 s, sqlite3_initi
87c0: 61 6c 69 7a 65 28 29 20 73 68 61 6c 6c 20 69 6e alize() shall in
87d0: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f voke.** sqlite3_
87e0: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 os_init(). Simi
87f0: 6c 61 72 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 larly, sqlite3_s
8800: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 73 68 61 hutdown().** sha
8810: 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 ll invoke sqlite
8820: 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 3_os_end()..**.*
8830: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e * The sqlite3_in
8840: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 itialize() routi
8850: 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ne returns [SQLI
8860: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 TE_OK] on succes
8870: 73 2e 0a 2a 2a 20 49 66 20 66 6f 72 20 73 6f 6d s..** If for som
8880: 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 e reason, sqlite
8890: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 3_initialize() i
88a0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 s unable to init
88b0: 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 ialize.** the li
88c0: 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69 brary (perhaps i
88d0: 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 t is unable to a
88e0: 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 llocate a needed
88f0: 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a resource such.*
8900: 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 * as a mutex) it
8910: 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 returns an [err
8920: 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 or code] other t
8930: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e han [SQLITE_OK].
8940: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
8950: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
8960: 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 routine is calle
8970: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 d internally by
8980: 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 many other.** SQ
8990: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 Lite interfaces
89a0: 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 so that an appli
89b0: 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 cation usually d
89c0: 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a oes not need to.
89d0: 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 ** invoke sqlite
89e0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 3_initialize() d
89f0: 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 irectly. For ex
8a00: 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f ample, [sqlite3_
8a10: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 open()].** calls
8a20: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
8a30: 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c ize() so the SQL
8a40: 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c ite library will
8a50: 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c be automaticall
8a60: 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 y.** initialized
8a70: 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f when [sqlite3_o
8a80: 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 pen()] is called
8a90: 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 if it has not b
8aa0: 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a e initialized.**
8ab0: 20 61 6c 72 65 61 64 79 2e 20 20 48 6f 77 65 76 already. Howev
8ac0: 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 er, if SQLite is
8ad0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 compiled with t
8ae0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f he [SQLITE_OMIT_
8af0: 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d AUTOINIT].** com
8b00: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
8b10: 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d , then the autom
8b20: 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 atic calls to sq
8b30: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
8b40: 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 ().** are omitte
8b50: 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 d and the applic
8b60: 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 ation must call
8b70: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
8b80: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a ze() directly.**
8b90: 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 prior to using
8ba0: 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 any other SQLite
8bb0: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 interface. For
8bc0: 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 maximum portabi
8bd0: 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 lity,.** it is r
8be0: 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 ecommended that
8bf0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 applications alw
8c00: 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 ays invoke sqlit
8c10: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a e3_initialize().
8c20: 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f ** directly prio
8c30: 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f r to using any o
8c40: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 ther SQLite inte
8c50: 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 rface. Future r
8c60: 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 eleases.** of SQ
8c70: 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 Lite may require
8c80: 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 this. In other
8c90: 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 words, the beha
8ca0: 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a vior exhibited.*
8cb0: 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 * when SQLite is
8cc0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b compiled with [
8cd0: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f SQLITE_OMIT_AUTO
8ce0: 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f INIT] might beco
8cf0: 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c me the.** defaul
8d00: 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f t behavior in so
8d10: 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 me future releas
8d20: 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a e of SQLite..**.
8d30: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f ** The sqlite3_o
8d40: 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 s_init() routine
8d50: 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d does operating-
8d60: 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a system specific.
8d70: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f ** initializatio
8d80: 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 n of the SQLite
8d90: 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 library. The sq
8da0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a lite3_os_end().*
8db0: 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 * routine undoes
8dc0: 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 the effect of s
8dd0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
8de0: 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 . Typical tasks
8df0: 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 .** performed by
8e00: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
8e10: 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 include allocati
8e20: 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 on or deallocati
8e30: 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 on.** of static
8e40: 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 resources, initi
8e50: 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f alization of glo
8e60: 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a bal variables,.*
8e70: 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 * setting up a d
8e80: 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f efault [sqlite3_
8e90: 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 vfs] module, or
8ea0: 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 setting up.** a
8eb0: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 default configur
8ec0: 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c ation using [sql
8ed0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a ite3_config()]..
8ee0: 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 **.** The applic
8ef0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 ation should nev
8f00: 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 er invoke either
8f10: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
8f20: 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 ().** or sqlite3
8f30: 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 _os_end() direct
8f40: 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 ly. The applica
8f50: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 tion should only
8f60: 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 invoke.** sqlit
8f70: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
8f80: 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 and sqlite3_shut
8f90: 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c down(). The sql
8fa0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a ite3_os_init().*
8fb0: 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 * interface is c
8fc0: 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 alled automatica
8fd0: 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 lly by sqlite3_i
8fe0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a nitialize() and.
8ff0: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e ** sqlite3_os_en
9000: 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 d() is called by
9010: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
9020: 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 n(). Appropriat
9030: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e.** implementat
9040: 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 ions for sqlite3
9050: 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 _os_init() and s
9060: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a qlite3_os_end().
9070: 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 ** are built int
9080: 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 o SQLite when it
9090: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 is compiled for
90a0: 20 75 6e 69 78 2c 20 77 69 6e 64 6f 77 73 2c 20 unix, windows,
90b0: 6f 72 20 6f 73 2f 32 2e 0a 2a 2a 20 57 68 65 6e or os/2..** When
90c0: 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 built for other
90d0: 20 70 6c 61 74 66 6f 72 6d 73 20 28 75 73 69 6e platforms (usin
90e0: 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 g the [SQLITE_OS
90f0: 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c _OTHER=1] compil
9100: 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e e-time.** option
9110: 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f ) the applicatio
9120: 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 n must supply a
9130: 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 suitable impleme
9140: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 ntation for.** s
9150: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
9160: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f and sqlite3_os_
9170: 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 end(). An appli
9180: 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a cation-supplied.
9190: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
91a0: 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f n of sqlite3_os_
91b0: 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 init() or sqlite
91c0: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 3_os_end().** mu
91d0: 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 st return [SQLIT
91e0: 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 E_OK] on success
91f0: 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 and some other
9200: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f [error code] upo
9210: 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f n.** failure..*/
9220: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 .int sqlite3_ini
9230: 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 tialize(void);.i
9240: 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 nt sqlite3_shutd
9250: 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 own(void);.int s
9260: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 qlite3_os_init(v
9270: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 oid);.int sqlite
9280: 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 3_os_end(void);.
9290: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
92a0: 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 Configuring The
92b0: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 SQLite Library
92c0: 7b 48 31 34 31 30 30 7d 20 3c 53 32 30 30 30 30 {H14100} <S20000
92d0: 3e 3c 53 33 30 32 30 30 3e 0a 2a 2a 20 45 58 50 ><S30200>.** EXP
92e0: 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 ERIMENTAL.**.**
92f0: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 The sqlite3_conf
9300: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 ig() interface i
9310: 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 s used to make g
9320: 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 lobal configurat
9330: 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 ion.** changes t
9340: 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 o SQLite in orde
9350: 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 r to tune SQLite
9360: 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 to the specific
9370: 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 needs of.** the
9380: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 application. T
9390: 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 he default confi
93a0: 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f guration is reco
93b0: 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 mmended for most
93c0: 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 .** applications
93d0: 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 and so this rou
93e0: 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 tine is usually
93f0: 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 not necessary.
9400: 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 It is.** provide
9410: 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 d to support rar
9420: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 e applications w
9430: 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 ith unusual need
9440: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c s..**.** The sql
9450: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e ite3_config() in
9460: 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 terface is not t
9470: 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 hreadsafe. The
9480: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d application.** m
9490: 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 ust insure that
94a0: 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 no other SQLite
94b0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 interfaces are i
94c0: 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a nvoked by other.
94d0: 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 ** threads while
94e0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
94f0: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 ) is running. F
9500: 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 urthermore, sqli
9510: 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 te3_config().**
9520: 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f may only be invo
9530: 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 ked prior to lib
9540: 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 rary initializat
9550: 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 ion using.** [sq
9560: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
9570: 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 ()] or after shu
9580: 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 tdown by [sqlite
9590: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 3_shutdown()]..*
95a0: 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c * Note, however,
95b0: 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 63 6f that sqlite3_co
95c0: 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 nfig() can be ca
95d0: 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 lled as part of
95e0: 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 the.** implement
95f0: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c ation of an appl
9600: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
9610: 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 [sqlite3_os_init
9620: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 ()]..**.** The f
9630: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
9640: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
9650: 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a ) is an integer.
9660: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ** [SQLITE_CONFI
9670: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c G_SINGLETHREAD |
9680: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
9690: 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 ption] that dete
96a0: 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 rmines.** what p
96b0: 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 roperty of SQLit
96c0: 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 e is to be confi
96d0: 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 gured. Subseque
96e0: 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 nt arguments.**
96f0: 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f vary depending o
9700: 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f n the [SQLITE_CO
9710: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 NFIG_SINGLETHREA
9720: 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f D | configuratio
9730: 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 n option].** in
9740: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
9750: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 nt..**.** When a
9760: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
9770: 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 ption is set, sq
9780: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 lite3_config() r
9790: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
97a0: 4b 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 K]..** If the op
97b0: 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 tion is unknown
97c0: 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 or SQLite is una
97d0: 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f ble to set the o
97e0: 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 ption.** then th
97f0: 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 is routine retur
9800: 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 ns a non-zero [e
9810: 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a rror code]..**.*
9820: 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
9830: 2a 2a 20 5b 48 31 34 31 30 33 5d 20 5b 48 31 34 ** [H14103] [H14
9840: 31 30 36 5d 20 5b 48 31 34 31 32 30 5d 20 5b 48 106] [H14120] [H
9850: 31 34 31 32 33 5d 20 5b 48 31 34 31 32 36 5d 20 14123] [H14126]
9860: 5b 48 31 34 31 32 39 5d 20 5b 48 31 34 31 33 32 [H14129] [H14132
9870: 5d 20 5b 48 31 34 31 33 35 5d 0a 2a 2a 20 5b 48 ] [H14135].** [H
9880: 31 34 31 33 38 5d 20 5b 48 31 34 31 34 31 5d 20 14138] [H14141]
9890: 5b 48 31 34 31 34 34 5d 20 5b 48 31 34 31 34 37 [H14144] [H14147
98a0: 5d 20 5b 48 31 34 31 35 30 5d 20 5b 48 31 34 31 ] [H14150] [H141
98b0: 35 33 5d 20 5b 48 31 34 31 35 36 5d 20 5b 48 31 53] [H14156] [H1
98c0: 34 31 35 39 5d 0a 2a 2a 20 5b 48 31 34 31 36 32 4159].** [H14162
98d0: 5d 20 5b 48 31 34 31 36 35 5d 20 5b 48 31 34 31 ] [H14165] [H141
98e0: 36 38 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 68].*/.SQLITE_EX
98f0: 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 PERIMENTAL int s
9900: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e qlite3_config(in
9910: 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 t, ...);../*.**
9920: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 CAPI3REF: Config
9930: 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e ure database con
9940: 6e 65 63 74 69 6f 6e 73 20 20 7b 48 31 34 32 30 nections {H1420
9950: 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 0} <S20000>.** E
9960: 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a XPERIMENTAL.**.*
9970: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 * The sqlite3_db
9980: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 _config() interf
9990: 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d ace is used to m
99a0: 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ake configuratio
99b0: 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 n.** changes to
99c0: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a [database conn
99d0: 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e ection]. The in
99e0: 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c terface is simil
99f0: 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ar to.** [sqlite
9a00: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 3_config()] exce
9a10: 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e pt that the chan
9a20: 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 ges apply to a s
9a30: 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 ingle.** [databa
9a40: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 se connection] (
9a50: 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 specified in the
9a60: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 first argument)
9a70: 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 . The.** sqlite
9a80: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 3_db_config() in
9a90: 74 65 72 66 61 63 65 20 63 61 6e 20 6f 6e 6c 79 terface can only
9aa0: 20 62 65 20 75 73 65 64 20 69 6d 6d 65 64 69 61 be used immedia
9ab0: 74 65 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74 68 tely after.** th
9ac0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
9ad0: 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64 ction is created
9ae0: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
9af0: 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c open()],.** [sql
9b00: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 ite3_open16()],
9b10: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e or [sqlite3_open
9b20: 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 _v2()]. .**.**
9b30: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d The second argum
9b40: 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 ent to sqlite3_d
9b50: 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e b_config(D,V,...
9b60: 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6e ) is the.** con
9b70: 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 20 figuration verb
9b80: 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 - an integer cod
9b90: 65 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 e that indicates
9ba0: 20 77 68 61 74 0a 2a 2a 20 61 73 70 65 63 74 20 what.** aspect
9bb0: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 of the [database
9bc0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 connection] is
9bd0: 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 being configured
9be0: 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63 68 ..** The only ch
9bf0: 6f 69 63 65 20 66 6f 72 20 74 68 69 73 20 76 61 oice for this va
9c00: 6c 75 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 lue is [SQLITE_D
9c10: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 BCONFIG_LOOKASID
9c20: 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62 73 E]..** New verbs
9c30: 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62 are likely to b
9c40: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
9c50: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 e releases of SQ
9c60: 4c 69 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69 6f Lite..** Additio
9c70: 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 64 65 nal arguments de
9c80: 70 65 6e 64 20 6f 6e 20 74 68 65 20 76 65 72 62 pend on the verb
9c90: 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
9ca0: 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 34 32 30 33 ents:.** [H14203
9cb0: 5d 20 5b 48 31 34 32 30 36 5d 20 5b 48 31 34 32 ] [H14206] [H142
9cc0: 30 39 5d 20 5b 48 31 34 32 31 32 5d 20 5b 48 31 09] [H14212] [H1
9cd0: 34 32 31 35 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 4215].*/.SQLITE_
9ce0: 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 EXPERIMENTAL int
9cf0: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 sqlite3_db_conf
9d00: 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 ig(sqlite3*, int
9d10: 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a op, ...);../*.*
9d20: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f * CAPI3REF: Memo
9d30: 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f ry Allocation Ro
9d40: 75 74 69 6e 65 73 20 7b 48 31 30 31 35 35 7d 20 utines {H10155}
9d50: 3c 53 32 30 31 32 30 3e 0a 2a 2a 20 45 58 50 45 <S20120>.** EXPE
9d60: 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 RIMENTAL.**.** A
9d70: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
9d80: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 is object define
9d90: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 s the interface
9da0: 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a between SQLite.*
9db0: 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 * and low-level
9dc0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
9dd0: 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a n routines..**.*
9de0: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 * This object is
9df0: 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e used in only on
9e00: 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 e place in the S
9e10: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e QLite interface.
9e20: 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f .** A pointer to
9e30: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 an instance of
9e40: 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 this object is t
9e50: 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a he argument to.*
9e60: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 * [sqlite3_confi
9e70: 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f g()] when the co
9e80: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
9e90: 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 on is.** [SQLITE
9ea0: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e _CONFIG_MALLOC].
9eb0: 20 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e By creating an
9ec0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 instance of thi
9ed0: 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 s object.** and
9ee0: 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 passing it to [s
9ef0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
9f00: 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 during configur
9f10: 61 74 69 6f 6e 2c 20 61 6e 0a 2a 2a 20 61 70 70 ation, an.** app
9f20: 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 lication can spe
9f30: 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 cify an alternat
9f40: 69 76 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ive memory alloc
9f50: 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 0a ation subsystem.
9f60: 2a 2a 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f ** for SQLite to
9f70: 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 use for all of
9f80: 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f its dynamic memo
9f90: 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 ry needs..**.**
9fa0: 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 Note that SQLite
9fb0: 20 63 6f 6d 65 73 20 77 69 74 68 20 61 20 62 75 comes with a bu
9fc0: 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c ilt-in memory al
9fd0: 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 69 73 0a locator that is.
9fe0: 2a 2a 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 ** perfectly ade
9ff0: 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 quate for the ov
a000: 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 erwhelming major
a010: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 ity of applicati
a020: 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 ons.** and that
a030: 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f this object is o
a040: 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 nly useful to a
a050: 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 tiny minority of
a060: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a applications.**
a070: 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 with specialize
a080: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 d memory allocat
a090: 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 ion requirements
a0a0: 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 . This object i
a0b0: 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 s.** also used d
a0c0: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 uring testing of
a0d0: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 SQLite in order
a0e0: 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 to specify an a
a0f0: 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 lternative.** me
a100: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 mory allocator t
a110: 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 hat simulates me
a120: 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f mory out-of-memo
a130: 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e ry conditions in
a140: 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 .** order to ver
a150: 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 ify that SQLite
a160: 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 recovers gracefu
a170: 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a lly from such.**
a180: 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a conditions..**.
a190: 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 ** The xMalloc,
a1a0: 78 46 72 65 65 2c 20 61 6e 64 20 78 52 65 61 6c xFree, and xReal
a1b0: 6c 6f 63 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 loc methods must
a1c0: 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a work like the.*
a1d0: 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 66 72 65 65 * malloc(), free
a1e0: 28 29 2c 20 61 6e 64 20 72 65 61 6c 6c 6f 63 28 (), and realloc(
a1f0: 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d ) functions from
a200: 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 6c 69 the standard li
a210: 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 brary..**.** xSi
a220: 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e ze should return
a230: 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 the allocated s
a240: 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 ize of a memory
a250: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 allocation.** pr
a260: 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 eviously obtaine
a270: 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f d from xMalloc o
a280: 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 r xRealloc. The
a290: 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a allocated size.
a2a0: 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 ** is always at
a2b0: 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20 least as big as
a2c0: 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69 the requested si
a2d0: 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 ze but may be la
a2e0: 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 rger..**.** The
a2f0: 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 xRoundup method
a300: 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 returns what wou
a310: 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 ld be the alloca
a320: 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 ted size of.** a
a330: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
a340: 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 on given a parti
a350: 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 cular requested
a360: 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f size. Most memo
a370: 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 ry.** allocators
a380: 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 round up memory
a390: 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 allocations at
a3a0: 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 least to the nex
a3b0: 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 t multiple.** of
a3c0: 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 8. Some alloca
a3d0: 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f tors round up to
a3e0: 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 a larger multip
a3f0: 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 le or to a power
a400: 20 6f 66 20 32 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 of 2..**.** The
a410: 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e xInit method in
a420: 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 itializes the me
a430: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 mory allocator.
a440: 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a (For example,.*
a450: 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 * it might alloc
a460: 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 ate any require
a470: 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 mutexes or initi
a480: 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 alize internal d
a490: 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 ata.** structure
a4a0: 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 s. The xShutdow
a4b0: 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f n method is invo
a4c0: 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 ked (indirectly)
a4d0: 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f by.** [sqlite3_
a4e0: 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 shutdown()] and
a4f0: 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 should deallocat
a500: 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 e any resources
a510: 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 acquired.** by x
a520: 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 Init. The pAppD
a530: 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 ata pointer is u
a540: 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 sed as the only
a550: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 parameter to.**
a560: 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 xInit and xShutd
a570: 6f 77 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 own..*/.typedef
a580: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d struct sqlite3_m
a590: 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 em_methods sqlit
a5a0: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a e3_mem_methods;.
a5b0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d struct sqlite3_m
a5c0: 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 em_methods {. v
a5d0: 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 oid *(*xMalloc)(
a5e0: 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a int); /*
a5f0: 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 Memory allocati
a600: 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 on function */.
a610: 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 void (*xFree)(v
a620: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 oid*);
a630: 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 /* Free a prior
a640: 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 allocation */.
a650: 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 void *(*xRealloc
a660: 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f )(void*,int); /
a670: 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f * Resize an allo
a680: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 cation */. int
a690: 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b (*xSize)(void*);
a6a0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 /* Re
a6b0: 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 turn the size of
a6c0: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a an allocation *
a6d0: 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 /. int (*xRound
a6e0: 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 up)(int);
a6f0: 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 /* Round up r
a700: 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 equest size to a
a710: 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a llocation size *
a720: 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 /. int (*xInit)
a730: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 (void*);
a740: 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 /* Initialize
a750: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f the memory allo
a760: 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 cator */. void
a770: 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 (*xShutdown)(voi
a780: 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 d*); /* Dei
a790: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 nitialize the me
a7a0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a mory allocator *
a7b0: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 /. void *pAppDa
a7c0: 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 ta;
a7d0: 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 /* Argument t
a7e0: 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 o xInit() and xS
a7f0: 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a hutdown() */.};.
a800: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
a810: 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f Configuration O
a820: 70 74 69 6f 6e 73 20 7b 48 31 30 31 36 30 7d 20 ptions {H10160}
a830: 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45 <S20000>.** EXPE
a840: 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 RIMENTAL.**.** T
a850: 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 hese constants a
a860: 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 re the available
a870: 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 integer configu
a880: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 ration options t
a890: 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 hat.** can be pa
a8a0: 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 ssed as the firs
a8b0: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 t argument to th
a8c0: 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 e [sqlite3_confi
a8d0: 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a g()] interface..
a8e0: 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 **.** New config
a8f0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 uration options
a900: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 may be added in
a910: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 future releases
a920: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 of SQLite..** Ex
a930: 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 isting configura
a940: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 tion options mig
a950: 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 ht be discontinu
a960: 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e ed. Application
a970: 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 s.** should chec
a980: 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 k the return cod
a990: 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f e from [sqlite3_
a9a0: 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b config()] to mak
a9b0: 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 e sure that.** t
a9c0: 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 he call worked.
a9d0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f The [sqlite3_co
a9e0: 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 nfig()] interfac
a9f0: 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a e will return a.
aa00: 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 ** non-zero [err
aa10: 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 or code] if a di
aa20: 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e scontinued or un
aa30: 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 supported config
aa40: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a uration option.*
aa50: 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a * is invoked..**
aa60: 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e .** <dl>.** <dt>
aa70: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 SQLITE_CONFIG_SI
aa80: 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a NGLETHREAD</dt>.
aa90: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 ** <dd>There are
aaa0: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f no arguments to
aab0: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 this option. T
aac0: 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 his option disab
aad0: 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 les.** all mutex
aae0: 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c ing and puts SQL
aaf0: 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 ite into a mode
ab00: 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c where it can onl
ab10: 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 y be used.** by
ab20: 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e a single thread.
ab30: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
ab40: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
ab50: 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a LTITHREAD</dt>.*
ab60: 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 * <dd>There are
ab70: 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 no arguments to
ab80: 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 this option. Th
ab90: 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c is option disabl
aba0: 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f es.** mutexing o
abb0: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e n [database conn
abc0: 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 ection] and [pre
abd0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
abe0: 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 objects..** The
abf0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 application is
ac00: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 responsible for
ac10: 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 serializing acce
ac20: 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 ss to.** [databa
ac30: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 se connections]
ac40: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 and [prepared st
ac50: 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 atements]. But
ac60: 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a other mutexes.**
ac70: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 are enabled so
ac80: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c that SQLite will
ac90: 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 be safe to use
aca0: 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 in a multi-threa
acb0: 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 ded.** environme
acc0: 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f nt as long as no
acd0: 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 two threads att
ace0: 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 empt to use the
acf0: 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 same.** [databas
ad00: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 e connection] at
ad10: 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 the same time.
ad20: 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 See the [thread
ad30: 69 6e 67 20 6d 6f 64 65 5d 0a 2a 2a 20 64 6f 63 ing mode].** doc
ad40: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 umentation for a
ad50: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d dditional inform
ad60: 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a ation.</dd>.**.*
ad70: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
ad80: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f FIG_SERIALIZED</
ad90: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 dt>.** <dd>There
ada0: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 are no argument
adb0: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e s to this option
adc0: 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 65 . This option e
add0: 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 nables.** all mu
ade0: 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 texes including
adf0: 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a the recursive.**
ae00: 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 mutexes on [dat
ae10: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
ae20: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 ] and [prepared
ae30: 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 statement] objec
ae40: 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d ts..** In this m
ae50: 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68 ode (which is th
ae60: 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 e default when S
ae70: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
ae80: 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 d with.** [SQLIT
ae90: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 E_THREADSAFE=1])
aea0: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 the SQLite libr
aeb0: 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 ary will itself
aec0: 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 serialize access
aed0: 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 .** to [database
aee0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e connections] an
aef0: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
af00: 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 ements] so that
af10: 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 the.** applicati
af20: 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 on is free to us
af30: 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 e the same [data
af40: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
af50: 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 or the.** same
af60: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
af70: 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e ent] in differen
af80: 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 t threads at the
af90: 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 53 same time..** S
afa0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e ee the [threadin
afb0: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 g mode] document
afc0: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 ation for additi
afd0: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
afe0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
aff0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d >SQLITE_CONFIG_M
b000: 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ALLOC</dt>.** <d
b010: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 d>This option ta
b020: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 kes a single arg
b030: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 ument which is a
b040: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a pointer to an.*
b050: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 * instance of th
b060: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d e [sqlite3_mem_m
b070: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 ethods] structur
b080: 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 e. The argument
b090: 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c specifies.** al
b0a0: 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 ternative low-le
b0b0: 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 vel memory alloc
b0c0: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 ation routines t
b0d0: 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 o be used in pla
b0e0: 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d ce of.** the mem
b0f0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
b100: 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e outines built in
b110: 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a to SQLite.</dd>.
b120: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
b130: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f _CONFIG_GETMALLO
b140: 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 C</dt>.** <dd>Th
b150: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 is option takes
b160: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
b170: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 t which is a poi
b180: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e nter to an.** in
b190: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 stance of the [s
b1a0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
b1b0: 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 ds] structure.
b1c0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d The [sqlite3_mem
b1d0: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 _methods].** str
b1e0: 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 ucture is filled
b1f0: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e with the curren
b200: 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f tly defined memo
b210: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f ry allocation ro
b220: 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20 utines..** This
b230: 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 option can be us
b240: 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 ed to overload t
b250: 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 he default memor
b260: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 y allocation.**
b270: 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 routines with a
b280: 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d wrapper that sim
b290: 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 ulations memory
b2a0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 allocation failu
b2b0: 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 re or.** tracks
b2c0: 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f memory usage, fo
b2d0: 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a r example.</dd>.
b2e0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
b2f0: 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 _CONFIG_MEMSTATU
b300: 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 S</dt>.** <dd>Th
b310: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 is option takes
b320: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
b330: 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 of type int, int
b340: 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a erpreted as a .*
b350: 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 * boolean, which
b360: 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 enables or disa
b370: 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 bles the collect
b380: 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c ion of memory al
b390: 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 location .** sta
b3a0: 74 69 73 74 69 63 73 2e 20 57 68 65 6e 20 64 69 tistics. When di
b3b0: 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c sabled, the foll
b3c0: 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 owing SQLite int
b3d0: 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 0a erfaces become .
b3e0: 2a 2a 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e ** non-operation
b3f0: 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a al:.** <ul>.**
b400: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 <li> [sqlite3
b410: 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a _memory_used()].
b420: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 ** <li> [sqlit
b430: 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
b440: 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e ter()].** <li>
b450: 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 [sqlite3_soft_h
b460: 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 eap_limit()].**
b470: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f <li> [sqlite3_
b480: 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c status()].** <
b490: 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a /ul>.** </dd>.**
b4a0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
b4b0: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 ONFIG_SCRATCH</d
b4c0: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f t>.** <dd>This o
b4d0: 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 ption specifies
b4e0: 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 a static memory
b4f0: 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 buffer that SQLi
b500: 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a te can use for.*
b510: 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 * scratch memory
b520: 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72 . There are thr
b530: 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 ee arguments: A
b540: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
b550: 6d 65 6d 6f 72 79 2c 20 74 68 65 0a 2a 2a 20 73 memory, the.** s
b560: 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 ize of each scra
b570: 74 63 68 20 62 75 66 66 65 72 20 28 73 7a 29 2c tch buffer (sz),
b580: 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 and the number
b590: 6f 66 20 62 75 66 66 65 72 73 20 28 4e 29 2e 20 of buffers (N).
b5a0: 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d The sz.** argum
b5b0: 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 ent must be a mu
b5c0: 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 20 54 68 ltiple of 16. Th
b5d0: 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 73 e sz parameter s
b5e0: 68 6f 75 6c 64 20 62 65 20 61 20 66 65 77 20 62 hould be a few b
b5f0: 79 74 65 73 0a 2a 2a 20 6c 61 72 67 65 72 20 74 ytes.** larger t
b600: 68 61 6e 20 74 68 65 20 61 63 74 75 61 6c 20 73 han the actual s
b610: 63 72 61 74 63 68 20 73 70 61 63 65 20 72 65 71 cratch space req
b620: 75 69 72 65 64 20 64 75 65 20 69 6e 74 65 72 6e uired due intern
b630: 61 6c 20 6f 76 65 72 68 65 61 64 2e 0a 2a 2a 20 al overhead..**
b640: 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 The first.** arg
b650: 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 ument should poi
b660: 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 nt to an allocat
b670: 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 ion of at least
b680: 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 sz*N bytes of me
b690: 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 mory..** SQLite
b6a0: 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 will use no more
b6b0: 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 than one scratc
b6c0: 68 20 62 75 66 66 65 72 20 61 74 20 6f 6e 63 65 h buffer at once
b6d0: 20 70 65 72 20 74 68 72 65 61 64 2c 20 73 6f 0a per thread, so.
b6e0: 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 ** N should be s
b6f0: 65 74 20 74 6f 20 74 68 65 20 65 78 70 65 63 74 et to the expect
b700: 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 ed maximum numbe
b710: 72 20 6f 66 20 74 68 72 65 61 64 73 2e 20 20 54 r of threads. T
b720: 68 65 20 73 7a 0a 2a 2a 20 70 61 72 61 6d 65 74 he sz.** paramet
b730: 65 72 20 73 68 6f 75 6c 64 20 62 65 20 36 20 74 er should be 6 t
b740: 69 6d 65 73 20 74 68 65 20 73 69 7a 65 20 6f 66 imes the size of
b750: 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 the largest dat
b760: 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e abase page size.
b770: 0a 2a 2a 20 53 63 72 61 74 63 68 20 62 75 66 66 .** Scratch buff
b780: 65 72 73 20 61 72 65 20 75 73 65 64 20 61 73 20 ers are used as
b790: 70 61 72 74 20 6f 66 20 74 68 65 20 62 74 72 65 part of the btre
b7a0: 65 20 62 61 6c 61 6e 63 65 20 6f 70 65 72 61 74 e balance operat
b7b0: 69 6f 6e 2e 20 20 49 66 0a 2a 2a 20 54 68 65 20 ion. If.** The
b7c0: 62 74 72 65 65 20 62 61 6c 61 6e 63 65 72 20 6e btree balancer n
b7d0: 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 20 eeds additional
b7e0: 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 memory beyond wh
b7f0: 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 at is provided b
b800: 79 0a 2a 2a 20 73 63 72 61 74 63 68 20 62 75 66 y.** scratch buf
b810: 66 65 72 73 20 6f 72 20 69 66 20 6e 6f 20 73 63 fers or if no sc
b820: 72 61 74 63 68 20 62 75 66 66 65 72 20 73 70 61 ratch buffer spa
b830: 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64 2c ce is specified,
b840: 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 then SQLite.**
b850: 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 goes to [sqlite3
b860: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 74 6f 20 6f 62 _malloc()] to ob
b870: 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 tain the memory
b880: 69 74 20 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a 2a it needs.</dd>.*
b890: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
b8a0: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 CONFIG_PAGECACHE
b8b0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 </dt>.** <dd>Thi
b8c0: 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 s option specifi
b8d0: 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f es a static memo
b8e0: 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 ry buffer that S
b8f0: 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f QLite can use fo
b900: 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 r.** the databas
b910: 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74 e page cache wit
b920: 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 h the default pa
b930: 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 ge cache impleme
b940: 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 nation. .** Thi
b950: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 s configuration
b960: 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 should not be us
b970: 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 ed if an applica
b980: 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 tion-define page
b990: 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d .** cache implem
b9a0: 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 entation is load
b9b0: 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c ed using the SQL
b9c0: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 ITE_CONFIG_PCACH
b9d0: 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 E option..** The
b9e0: 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 re are three arg
b9f0: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f uments to this o
ba00: 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 ption: A pointer
ba10: 20 74 6f 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 to the.** memor
ba20: 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 y, the size of e
ba30: 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20 ach page buffer
ba40: 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 (sz), and the nu
ba50: 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e mber of pages (N
ba60: 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 )..** The sz arg
ba70: 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 ument must be a
ba80: 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 power of two bet
ba90: 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 ween 512 and 327
baa0: 36 38 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 68. The first.*
bab0: 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c * argument shoul
bac0: 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c d point to an al
bad0: 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c location of at l
bae0: 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 east sz*N bytes
baf0: 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 of memory..** SQ
bb00: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 Lite will use th
bb10: 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 e memory provide
bb20: 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 d by the first a
bb30: 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 rgument to satis
bb40: 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 fy its.** memory
bb50: 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 needs for the f
bb60: 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 irst N pages tha
bb70: 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 t it adds to cac
bb80: 68 65 2e 20 20 49 66 20 61 64 64 69 74 69 6f 6e he. If addition
bb90: 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 al.** page cache
bba0: 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 memory is neede
bbb0: 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 d beyond what is
bbc0: 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 provided by thi
bbd0: 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a s option, then.*
bbe0: 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f * SQLite goes to
bbf0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
bc00: 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 ()] for the addi
bc10: 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 tional storage s
bc20: 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6d 70 pace..** The imp
bc30: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 lementation migh
bc40: 74 20 75 73 65 20 6f 6e 65 20 6f 72 20 6d 6f 72 t use one or mor
bc50: 65 20 6f 66 20 74 68 65 20 4e 20 62 75 66 66 65 e of the N buffe
bc60: 72 73 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a 20 6d rs to hold .** m
bc70: 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 emory accounting
bc80: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20 3c 2f information. </
bc90: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
bca0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 LITE_CONFIG_HEAP
bcb0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 </dt>.** <dd>Thi
bcc0: 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 s option specifi
bcd0: 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f es a static memo
bce0: 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 ry buffer that S
bcf0: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a QLite will use.*
bd00: 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 * for all of its
bd10: 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 dynamic memory
bd20: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 allocation needs
bd30: 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 beyond those pr
bd40: 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 ovided.** for by
bd50: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
bd60: 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 SCRATCH] and [SQ
bd70: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 LITE_CONFIG_PAGE
bd80: 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 CACHE]..** There
bd90: 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d are three argum
bda0: 65 6e 74 73 3a 20 41 20 70 6f 69 6e 74 65 72 20 ents: A pointer
bdb0: 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20 74 to the memory, t
bdc0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 he number of.**
bdd0: 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d bytes in the mem
bde0: 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 ory buffer, and
bdf0: 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f the minimum allo
be00: 63 61 74 69 6f 6e 20 73 69 7a 65 2e 20 20 49 66 cation size. If
be10: 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 6f .** the first po
be20: 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 inter (the memor
be30: 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 y pointer) is NU
be40: 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 LL, then SQLite
be50: 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 reverts.** to us
be60: 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 ing its default
be70: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
be80: 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c (the system mal
be90: 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 loc() implementa
bea0: 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e tion),.** undoin
beb0: 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f g any prior invo
bec0: 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 cation of [SQLIT
bed0: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d E_CONFIG_MALLOC]
bee0: 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d . If the.** mem
bef0: 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e ory pointer is n
bf00: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 ot NULL and eith
bf10: 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c er [SQLITE_ENABL
bf20: 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a E_MEMSYS3] or.**
bf30: 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f [SQLITE_ENABLE_
bf40: 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 MEMSYS5] are def
bf50: 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 ined, then the a
bf60: 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 lternative memor
bf70: 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 y.** allocator i
bf80: 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e s engaged to han
bf90: 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 dle all of SQLit
bfa0: 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 es memory alloca
bfb0: 74 69 6f 6e 20 6e 65 65 64 73 2e 3c 2f 64 64 3e tion needs.</dd>
bfc0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
bfd0: 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f E_CONFIG_MUTEX</
bfe0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
bff0: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
c000: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 ingle argument w
c010: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 hich is a pointe
c020: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 r to an.** insta
c030: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 nce of the [sqli
c040: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 te3_mutex_method
c050: 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 s] structure. T
c060: 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 he argument spec
c070: 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 ifies.** alterna
c080: 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d tive low-level m
c090: 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f utex routines to
c0a0: 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 be used in plac
c0b0: 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 e.** the mutex r
c0c0: 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e outines built in
c0d0: 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a to SQLite.</dd>.
c0e0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
c0f0: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 _CONFIG_GETMUTEX
c100: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 </dt>.** <dd>Thi
c110: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 s option takes a
c120: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
c130: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e which is a poin
c140: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 ter to an.** ins
c150: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 tance of the [sq
c160: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 lite3_mutex_meth
c170: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 ods] structure.
c180: 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 The.** [sqlite3
c190: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a _mutex_methods].
c1a0: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 ** structure is
c1b0: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 filled with the
c1c0: 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 currently define
c1d0: 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 d mutex routines
c1e0: 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e ..** This option
c1f0: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
c200: 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 overload the def
c210: 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 ault mutex alloc
c220: 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 ation.** routine
c230: 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 s with a wrapper
c240: 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d used to track m
c250: 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 utex usage for p
c260: 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 erformance.** pr
c270: 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 ofiling or testi
c280: 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e ng, for example.
c290: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
c2a0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f SQLITE_CONFIG_LO
c2b0: 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 OKASIDE</dt>.**
c2c0: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 <dd>This option
c2d0: 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 takes two argume
c2e0: 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 nts that determi
c2f0: 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a ne the default.*
c300: 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 63 61 74 69 * memory allcati
c310: 6f 6e 20 6c 6f 6f 6b 61 73 69 64 65 20 6f 70 74 on lookaside opt
c320: 69 6d 69 7a 61 74 69 6f 6e 2e 20 20 54 68 65 20 imization. The
c330: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 first argument i
c340: 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 s the.** size of
c350: 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 each lookaside
c360: 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 buffer slot and
c370: 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 the second is th
c380: 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 e number of.** s
c390: 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 lots allocated t
c3a0: 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 o each database
c3b0: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 3c 2f 64 64 3e connection.</dd>
c3c0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
c3d0: 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 3c E_CONFIG_PCACHE<
c3e0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 /dt>.** <dd>This
c3f0: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
c400: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
c410: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 which is a point
c420: 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c er to.** an [sql
c430: 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 ite3_pcache_meth
c440: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 ods] object. Th
c450: 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 is object specif
c460: 69 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 ies the interfac
c470: 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d e.** to a custom
c480: 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c page cache impl
c490: 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 53 51 4c ementation. SQL
c4a0: 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 ite makes a copy
c4b0: 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 of the.** objec
c4c0: 74 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f t and uses it fo
c4d0: 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d r page cache mem
c4e0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e ory allocations.
c4f0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
c500: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
c510: 54 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 TPCACHE</dt>.**
c520: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 <dd>This option
c530: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
c540: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
c550: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
c560: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 .** [sqlite3_pca
c570: 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a che_methods] obj
c580: 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 ect. SQLite cop
c590: 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 ies of the curre
c5a0: 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 nt.** page cache
c5b0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
c5c0: 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 into that object
c5d0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 .</dd>.**.** </d
c5e0: 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 l>.*/.#define SQ
c5f0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 LITE_CONFIG_SING
c600: 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 LETHREAD 1 /*
c610: 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nil */.#define S
c620: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c QLITE_CONFIG_MUL
c630: 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a TITHREAD 2 /*
c640: 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nil */.#define
c650: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 SQLITE_CONFIG_SE
c660: 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f RIALIZED 3 /
c670: 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 * nil */.#define
c680: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
c690: 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 ALLOC 4
c6a0: 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d /* sqlite3_mem_m
c6b0: 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 ethods* */.#defi
c6c0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
c6d0: 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 _GETMALLOC 5
c6e0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d /* sqlite3_mem
c6f0: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 _methods* */.#de
c700: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
c710: 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 IG_SCRATCH
c720: 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 6 /* void*, in
c730: 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 t sz, int N */.#
c740: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
c750: 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 NFIG_PAGECACHE
c760: 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 7 /* void*,
c770: 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f int sz, int N */
c780: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
c790: 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 CONFIG_HEAP
c7a0: 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 8 /* void*
c7b0: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 , int nByte, int
c7c0: 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 min */.#define
c7d0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 SQLITE_CONFIG_ME
c7e0: 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f MSTATUS 9 /
c7f0: 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 * boolean */.#de
c800: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
c810: 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 IG_MUTEX
c820: 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 10 /* sqlite3_m
c830: 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f utex_methods* */
c840: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
c850: 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 CONFIG_GETMUTEX
c860: 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 11 /* sqlit
c870: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 e3_mutex_methods
c880: 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 * */./* previous
c890: 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ly SQLITE_CONFIG
c8a0: 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 _CHUNKALLOC 12 w
c8b0: 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 hich is now unus
c8c0: 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 ed. */ .#define
c8d0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f SQLITE_CONFIG_LO
c8e0: 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f OKASIDE 13 /
c8f0: 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 * int int */.#de
c900: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
c910: 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 IG_PCACHE
c920: 31 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 14 /* sqlite3_p
c930: 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a cache_methods* *
c940: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
c950: 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 _CONFIG_GETPCACH
c960: 45 20 20 20 20 31 35 20 20 2f 2a 20 73 71 6c 69 E 15 /* sqli
c970: 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f te3_pcache_metho
c980: 64 73 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 ds* */../*.** CA
c990: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 PI3REF: Configur
c9a0: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 48 ation Options {H
c9b0: 31 30 31 37 30 7d 20 3c 53 32 30 30 30 30 3e 0a 10170} <S20000>.
c9c0: 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a ** EXPERIMENTAL.
c9d0: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
c9e0: 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 tants are the av
c9f0: 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 ailable integer
ca00: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
ca10: 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 tions that.** ca
ca20: 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 n be passed as t
ca30: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
ca40: 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 nt to the [sqlit
ca50: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 e3_db_config()]
ca60: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a interface..**.**
ca70: 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 New configurati
ca80: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 on options may b
ca90: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
caa0: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 e releases of SQ
cab0: 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e Lite..** Existin
cac0: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 g configuration
cad0: 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 options might be
cae0: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 discontinued.
caf0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 Applications.**
cb00: 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 should check the
cb10: 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f return code fro
cb20: 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f m [sqlite3_db_co
cb30: 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 nfig()] to make
cb40: 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 sure that.** the
cb50: 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 call worked. T
cb60: 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 he [sqlite3_db_c
cb70: 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 onfig()] interfa
cb80: 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 ce will return a
cb90: 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 .** non-zero [er
cba0: 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 ror code] if a d
cbb0: 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 iscontinued or u
cbc0: 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 nsupported confi
cbd0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a guration option.
cbe0: 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a ** is invoked..*
cbf0: 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 *.** <dl>.** <dt
cc00: 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 >SQLITE_DBCONFIG
cc10: 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a _LOOKASIDE</dt>.
cc20: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 ** <dd>This opti
cc30: 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 on takes three a
cc40: 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 dditional argume
cc50: 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 nts that determi
cc60: 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b ne the .** [look
cc70: 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c aside memory all
cc80: 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 ocator] configur
cc90: 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 ation for the [d
cca0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
ccb0: 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 on]..** The firs
ccc0: 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 t argument (the
ccd0: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
cce0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 to [sqlite3_db_c
ccf0: 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a onfig()] is a.**
cd00: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 pointer to a me
cd10: 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 mory buffer to u
cd20: 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 se for lookaside
cd30: 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 20 66 69 memory. The fi
cd40: 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 rst.** argument
cd50: 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 may be NULL in w
cd60: 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 hich case SQLite
cd70: 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 will allocate t
cd80: 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 he lookaside.**
cd90: 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 buffer itself us
cda0: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c ing [sqlite3_mal
cdb0: 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 73 65 63 loc()]. The sec
cdc0: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ond argument is
cdd0: 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 the.** size of e
cde0: 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 ach lookaside bu
cdf0: 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 ffer slot and th
ce00: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 e third argument
ce10: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
ce20: 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 f.** slots. The
ce30: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 size of the buf
ce40: 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 fer in the first
ce50: 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 argument must b
ce60: 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a e greater than.*
ce70: 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 * or equal to th
ce80: 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 e product of the
ce90: 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 second and thir
cea0: 64 20 61 72 67 75 6d 65 6e 74 73 2e 3c 2f 64 64 d arguments.</dd
ceb0: 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f >.**.** </dl>.*/
cec0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
ced0: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 DBCONFIG_LOOKASI
cee0: 44 45 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 DE 1001 /* v
cef0: 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a oid* int int */.
cf00: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
cf10: 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 : Enable Or Disa
cf20: 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 ble Extended Res
cf30: 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 32 32 30 ult Codes {H1220
cf40: 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 0} <S10700>.**.*
cf50: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 * The sqlite3_ex
cf60: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f tended_result_co
cf70: 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e des() routine en
cf80: 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 ables or disable
cf90: 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 s the.** [extend
cfa0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d ed result codes]
cfb0: 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 feature of SQLi
cfc0: 74 65 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 te. The extended
cfd0: 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 result.** codes
cfe0: 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 are disabled by
cff0: 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 default for his
d000: 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 torical compatib
d010: 69 6c 69 74 79 20 63 6f 6e 73 69 64 65 72 61 74 ility considerat
d020: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 ions..**.** Requ
d030: 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
d040: 32 32 30 31 5d 20 5b 48 31 32 32 30 32 5d 0a 2a 2201] [H12202].*
d050: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 /.int sqlite3_ex
d060: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f tended_result_co
d070: 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e des(sqlite3*, in
d080: 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a t onoff);../*.**
d090: 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 CAPI3REF: Last
d0a0: 49 6e 73 65 72 74 20 52 6f 77 69 64 20 7b 48 31 Insert Rowid {H1
d0b0: 32 32 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2220} <S10700>.*
d0c0: 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72 79 20 *.** Each entry
d0d0: 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 in an SQLite tab
d0e0: 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 le has a unique
d0f0: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 64-bit signed.**
d100: 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c integer key cal
d110: 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c led the [ROWID |
d120: 20 22 72 6f 77 69 64 22 5d 2e 20 54 68 65 20 72 "rowid"]. The r
d130: 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 owid is always a
d140: 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 vailable.** as a
d150: 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c n undeclared col
d160: 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c umn named ROWID,
d170: 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f OID, or _ROWID_
d180: 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 as long as thos
d190: 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e e.** names are n
d1a0: 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 ot also used by
d1b0: 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 explicitly decla
d1c0: 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 49 66 0a red columns. If.
d1d0: 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 ** the table has
d1e0: 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 a column of typ
d1f0: 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 e [INTEGER PRIMA
d200: 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 RY KEY] then tha
d210: 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 t column.** is a
d220: 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 nother alias for
d230: 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a the rowid..**.*
d240: 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 * This routine r
d250: 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 eturns the [rowi
d260: 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 d] of the most r
d270: 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 ecent.** success
d280: 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 ful [INSERT] int
d290: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 o the database f
d2a0: 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73 rom the [databas
d2b0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a e connection].**
d2c0: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
d2d0: 67 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f 20 73 gument. If no s
d2e0: 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 uccessful [INSER
d2f0: 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 T]s.** have ever
d300: 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 occurred on tha
d310: 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 t database conne
d320: 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 ction, zero is r
d330: 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 eturned..**.** I
d340: 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 f an [INSERT] oc
d350: 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 curs within a tr
d360: 69 67 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20 igger, then the
d370: 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 [rowid] of the i
d380: 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 69 nserted.** row i
d390: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 s returned by th
d3a0: 69 73 20 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f is routine as lo
d3b0: 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65 ng as the trigge
d3c0: 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a r is running..**
d3d0: 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 But once the tr
d3e0: 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74 65 73 igger terminates
d3f0: 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 , the value retu
d400: 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 rned by this rou
d410: 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72 74 73 20 tine.** reverts
d420: 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61 6c 75 to the last valu
d430: 65 20 69 6e 73 65 72 74 65 64 20 62 65 66 6f 72 e inserted befor
d440: 65 20 74 68 65 20 74 72 69 67 67 65 72 20 66 69 e the trigger fi
d450: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 49 red..**.** An [I
d460: 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c NSERT] that fail
d470: 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 s due to a const
d480: 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 raint violation
d490: 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 is not a.** succ
d4a0: 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 essful [INSERT]
d4b0: 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 and does not cha
d4c0: 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 nge the value re
d4d0: 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a turned by this.*
d4e0: 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54 68 75 73 * routine. Thus
d4f0: 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c INSERT OR FAIL,
d500: 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 INSERT OR IGNOR
d510: 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c E, INSERT OR ROL
d520: 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e LBACK,.** and IN
d530: 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 SERT OR ABORT ma
d540: 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f ke no changes to
d550: 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
d560: 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 e of this.** rou
d570: 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 tine when their
d580: 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e insertion fails.
d590: 20 20 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 When INSERT OR
d5a0: 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f REPLACE.** enco
d5b0: 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 unters a constra
d5c0: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 int violation, i
d5d0: 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e t does not fail.
d5e0: 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 The.** INSERT
d5f0: 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d continues to com
d600: 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 pletion after de
d610: 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 leting rows that
d620: 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 caused.** the c
d630: 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 onstraint proble
d640: 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 m so INSERT OR R
d650: 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 EPLACE will alwa
d660: 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 ys change.** the
d670: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 return value of
d680: 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e this interface.
d690: 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 .**.** For the p
d6a0: 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 urposes of this
d6b0: 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 routine, an [INS
d6c0: 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 ERT] is consider
d6d0: 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 ed to.** be succ
d6e0: 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 essful even if i
d6f0: 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c t is subsequentl
d700: 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a y rolled back..*
d710: 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
d720: 73 3a 0a 2a 2a 20 5b 48 31 32 32 32 31 5d 20 5b s:.** [H12221] [
d730: 48 31 32 32 32 33 5d 0a 2a 2a 0a 2a 2a 20 49 66 H12223].**.** If
d740: 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 a separate thre
d750: 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 ad performs a ne
d760: 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 w [INSERT] on th
d770: 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 e same.** databa
d780: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 se connection wh
d790: 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 ile the [sqlite3
d7a0: 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 _last_insert_row
d7b0: 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f id()].** functio
d7c0: 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 n is running and
d7d0: 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 thus changes th
d7e0: 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 e last insert [r
d7f0: 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 owid],.** then t
d800: 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
d810: 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 d by [sqlite3_la
d820: 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 st_insert_rowid(
d830: 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 )] is.** unpredi
d840: 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 ctable and might
d850: 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 not equal eithe
d860: 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 r the old or the
d870: 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 new.** last ins
d880: 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a ert [rowid]..*/.
d890: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 sqlite3_int64 sq
d8a0: 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 lite3_last_inser
d8b0: 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a t_rowid(sqlite3*
d8c0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
d8d0: 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 EF: Count The Nu
d8e0: 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 mber Of Rows Mod
d8f0: 69 66 69 65 64 20 7b 48 31 32 32 34 30 7d 20 3c ified {H12240} <
d900: 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S10600>.**.** Th
d910: 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 is function retu
d920: 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
d930: 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 f database rows
d940: 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 that were change
d950: 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 d.** or inserted
d960: 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 or deleted by t
d970: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 he most recently
d980: 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 completed SQL s
d990: 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 tatement.** on t
d9a0: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
d9b0: 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 nection] specifi
d9c0: 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 ed by the first
d9d0: 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 4f 6e parameter..** On
d9e0: 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 ly changes that
d9f0: 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 are directly spe
da00: 63 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 cified by the [I
da10: 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d NSERT], [UPDATE]
da20: 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d ,.** or [DELETE]
da30: 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 statement are c
da40: 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 ounted. Auxilia
da50: 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 ry changes cause
da60: 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 d by.** triggers
da70: 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 are not counted
da80: 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 . Use the [sqlit
da90: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
daa0: 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 ()] function.**
dab0: 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61 to find the tota
dac0: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e l number of chan
dad0: 67 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 ges including ch
dae0: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 anges caused by
daf0: 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 triggers..**.**
db00: 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 Changes to a vie
db10: 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c w that are simul
db20: 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 ated by an [INST
db30: 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a EAD OF trigger].
db40: 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 ** are not count
db50: 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 ed. Only real t
db60: 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 able changes are
db70: 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 counted..**.**
db80: 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 A "row change" i
db90: 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 s a change to a
dba0: 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 single row of a
dbb0: 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 single table.**
dbc0: 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 caused by an INS
dbd0: 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 ERT, DELETE, or
dbe0: 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 UPDATE statement
dbf0: 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 . Rows that.**
dc00: 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 are changed as s
dc10: 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b ide effects of [
dc20: 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 REPLACE] constra
dc30: 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a int resolution,.
dc40: 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f ** rollback, ABO
dc50: 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b RT processing, [
dc60: 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 DROP TABLE], or
dc70: 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 by any other.**
dc80: 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f mechanisms do no
dc90: 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 t count as direc
dca0: 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a t row changes..*
dcb0: 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20 *.** A "trigger
dcc0: 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73 63 context" is a sc
dcd0: 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e ope of execution
dce0: 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64 that begins and
dcf0: 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68 .** ends with th
dd00: 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 5b 43 e script of a [C
dd10: 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 REATE TRIGGER |
dd20: 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f trigger]. .** Mo
dd30: 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 st SQL statement
dd40: 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 s are.** evaluat
dd50: 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e ed outside of an
dd60: 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69 73 y trigger. This
dd70: 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76 is the "top lev
dd80: 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 el".** trigger c
dd90: 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74 72 ontext. If a tr
dda0: 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d igger fires from
ddb0: 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 the top level,
ddc0: 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72 a.** new trigger
ddd0: 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65 context is ente
dde0: 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72 61 red for the dura
ddf0: 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 tion of that one
de00: 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75 .** trigger. Su
de10: 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74 65 btriggers create
de20: 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 subcontexts for
de30: 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e their duration.
de40: 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 5b .**.** Calling [
de50: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 sqlite3_exec()]
de60: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 or [sqlite3_step
de70: 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 ()] recursively
de80: 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 does.** not crea
de90: 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 te a new trigger
dea0: 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 context..**.**
deb0: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 This function re
dec0: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
ded0: 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 of direct row c
dee0: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a hanges in the.**
def0: 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 most recent INS
df00: 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 ERT, UPDATE, or
df10: 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 DELETE statement
df20: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 within the same
df30: 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 .** trigger cont
df40: 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 75 73 2c ext..**.** Thus,
df50: 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f when called fro
df60: 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c m the top level,
df70: 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 this function r
df80: 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 eturns the.** nu
df90: 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 mber of changes
dfa0: 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 in the most rece
dfb0: 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 nt INSERT, UPDAT
dfc0: 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 E, or DELETE.**
dfd0: 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 that also occurr
dfe0: 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 ed at the top le
dff0: 76 65 6c 2e 20 20 57 69 74 68 69 6e 20 74 68 65 vel. Within the
e000: 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 body of a trigg
e010: 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 er,.** the sqlit
e020: 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 e3_changes() int
e030: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 erface can be ca
e040: 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 lled to find the
e050: 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 number of.** ch
e060: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 anges in the mos
e070: 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c t recently compl
e080: 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 eted INSERT, UPD
e090: 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a ATE, or DELETE.*
e0a0: 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 * statement with
e0b0: 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 in the body of t
e0c0: 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e he same trigger.
e0d0: 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 .** However, the
e0e0: 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 number returned
e0f0: 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 does not includ
e100: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 e changes.** cau
e110: 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65 sed by subtrigge
e120: 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 rs since those h
e130: 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f ave their own co
e140: 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 ntext..**.** See
e150: 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 also the [sqlit
e160: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
e170: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e ()] interface an
e180: 64 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f d the.** [count_
e190: 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2e changes pragma].
e1a0: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
e1b0: 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 34 31 5d nts:.** [H12241]
e1c0: 20 5b 48 31 32 32 34 33 5d 0a 2a 2a 0a 2a 2a 20 [H12243].**.**
e1d0: 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 If a separate th
e1e0: 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 read makes chang
e1f0: 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 es on the same d
e200: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
e210: 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c on.** while [sql
e220: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 ite3_changes()]
e230: 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 is running then
e240: 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
e250: 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 ed.** is unpredi
e260: 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d ctable and not m
e270: 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e eaningful..*/.in
e280: 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 t sqlite3_change
e290: 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a s(sqlite3*);../*
e2a0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f .** CAPI3REF: To
e2b0: 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f tal Number Of Ro
e2c0: 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 48 31 32 ws Modified {H12
e2d0: 32 36 30 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 260} <S10600>.**
e2e0: 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f .** This functio
e2f0: 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 n returns the nu
e300: 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e mber of row chan
e310: 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 ges caused by [I
e320: 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 NSERT],.** [UPDA
e330: 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 TE] or [DELETE]
e340: 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 statements since
e350: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
e360: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f onnection] was o
e370: 70 65 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 63 6f pened..** The co
e380: 75 6e 74 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c unt includes all
e390: 20 63 68 61 6e 67 65 73 20 66 72 6f 6d 20 61 6c changes from al
e3a0: 6c 20 0a 2a 2a 20 5b 43 52 45 41 54 45 20 54 52 l .** [CREATE TR
e3b0: 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d IGGER | trigger]
e3c0: 20 63 6f 6e 74 65 78 74 73 2e 20 20 48 6f 77 65 contexts. Howe
e3d0: 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e ver,.** the coun
e3e0: 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 t does not inclu
e3f0: 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 de changes used
e400: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 to implement [RE
e410: 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e PLACE] constrain
e420: 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 ts,.** do rollba
e430: 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f cks or ABORT pro
e440: 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f cessing, or [DRO
e450: 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 P TABLE] process
e460: 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 ing. The.** cou
e470: 6e 74 20 64 6f 65 73 20 6e 6f 74 20 72 6f 77 73 nt does not rows
e480: 20 6f 66 20 76 69 65 77 73 20 74 68 61 74 20 66 of views that f
e490: 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 ire an [INSTEAD
e4a0: 4f 46 20 74 72 69 67 67 65 72 5d 2c 20 74 68 6f OF trigger], tho
e4b0: 75 67 68 20 69 66 0a 2a 2a 20 74 68 65 20 49 4e ugh if.** the IN
e4c0: 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 STEAD OF trigger
e4d0: 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f makes changes o
e4e0: 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 f its own, those
e4f0: 20 63 68 61 6e 67 65 73 20 61 72 65 0a 2a 2a 20 changes are.**
e500: 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 54 68 65 20 counted..** The
e510: 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e changes are coun
e520: 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 ted as soon as t
e530: 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 he statement tha
e540: 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 0a t makes them is.
e550: 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 ** completed (wh
e560: 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 en the statement
e570: 20 68 61 6e 64 6c 65 20 69 73 20 70 61 73 73 65 handle is passe
e580: 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 d to [sqlite3_re
e590: 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 set()] or.** [sq
e5a0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
e5b0: 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c ])..**.** See al
e5c0: 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f so the [sqlite3_
e5d0: 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 changes()] inter
e5e0: 66 61 63 65 20 61 6e 64 20 74 68 65 0a 2a 2a 20 face and the.**
e5f0: 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 [count_changes p
e600: 72 61 67 6d 61 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 ragma]..**.** Re
e610: 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
e620: 48 31 32 32 36 31 5d 20 5b 48 31 32 32 36 33 5d H12261] [H12263]
e630: 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 .**.** If a sepa
e640: 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 rate thread make
e650: 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 s changes on the
e660: 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 same database c
e670: 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 onnection.** whi
e680: 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 le [sqlite3_tota
e690: 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 l_changes()] is
e6a0: 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 running then the
e6b0: 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e value.** return
e6c0: 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 ed is unpredicta
e6d0: 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e ble and not mean
e6e0: 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 ingful..*/.int s
e6f0: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 qlite3_total_cha
e700: 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a nges(sqlite3*);.
e710: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
e720: 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e Interrupt A Lon
e730: 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 20 g-Running Query
e740: 7b 48 31 32 32 37 30 7d 20 3c 53 33 30 35 30 30 {H12270} <S30500
e750: 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e >.**.** This fun
e760: 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 ction causes any
e770: 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 pending databas
e780: 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 e operation to a
e790: 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 bort and.** retu
e7a0: 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 rn at its earlie
e7b0: 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 st opportunity.
e7c0: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 This routine is
e7d0: 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c typically.** cal
e7e0: 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 led in response
e7f0: 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e to a user action
e800: 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e such as pressin
e810: 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 g "Cancel".** or
e820: 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 Ctrl-C where th
e830: 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c e user wants a l
e840: 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 ong query operat
e850: 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 ion to halt.** i
e860: 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a mmediately..**.*
e870: 2a 20 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 * It is safe to
e880: 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e call this routin
e890: 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 e from a thread
e8a0: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 different from t
e8b0: 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 he.** thread tha
e8c0: 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 t is currently r
e8d0: 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 unning the datab
e8e0: 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 ase operation.
e8f0: 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 But it.** is not
e900: 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 safe to call th
e910: 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 is routine with
e920: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a [database conn
e930: 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 ection] that.**
e940: 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 is closed or mig
e950: 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 ht close before
e960: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
e970: 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a t() returns..**.
e980: 2a 2a 20 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 ** If an SQL ope
e990: 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e ration is very n
e9a0: 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 early finished a
e9b0: 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a t the time when.
e9c0: 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 ** sqlite3_inter
e9d0: 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 rupt() is called
e9e0: 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 , then it might
e9f0: 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f not have an oppo
ea00: 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 rtunity.** to be
ea10: 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 interrupted and
ea20: 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 might continue
ea30: 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a to completion..*
ea40: 2a 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f 70 65 72 *.** An SQL oper
ea50: 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e ation that is in
ea60: 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 terrupted will r
ea70: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e eturn [SQLITE_IN
ea80: 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 49 66 20 TERRUPT]..** If
ea90: 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 the interrupted
eaa0: 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 SQL operation is
eab0: 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 an INSERT, UPDA
eac0: 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a TE, or DELETE.**
ead0: 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 that is inside
eae0: 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e an explicit tran
eaf0: 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 saction, then th
eb00: 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 e entire transac
eb10: 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 tion.** will be
eb20: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f rolled back auto
eb30: 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a matically..**.**
eb40: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 The sqlite3_int
eb50: 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 errupt(D) call i
eb60: 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 s in effect unti
eb70: 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 l all currently
eb80: 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 running.** SQL s
eb90: 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 tatements on [da
eba0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
ebb0: 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 n] D complete.
ebc0: 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 Any new SQL stat
ebd0: 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 ements.** that a
ebe0: 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 re started after
ebf0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 the sqlite3_int
ec00: 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e errupt() call an
ec10: 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a d before the .**
ec20: 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 running stateme
ec30: 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f nts reaches zero
ec40: 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 are interrupted
ec50: 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20 as if they had
ec60: 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 been.** running
ec70: 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c prior to the sql
ec80: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
ec90: 20 63 61 6c 6c 2e 20 20 4e 65 77 20 53 51 4c 20 call. New SQL
eca0: 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 statements.** th
ecb0: 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 at are started a
ecc0: 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 fter the running
ecd0: 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 statement count
ece0: 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 reaches zero ar
ecf0: 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 e.** not effecte
ed00: 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 d by the sqlite3
ed10: 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a _interrupt()..**
ed20: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 A call to sqlit
ed30: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 e3_interrupt(D)
ed40: 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e that occurs when
ed50: 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 there are no ru
ed60: 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 nning.** SQL sta
ed70: 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d tements is a no-
ed80: 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 op and has no ef
ed90: 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 fect on SQL stat
eda0: 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 ements.** that a
edb0: 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 re started after
edc0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 the sqlite3_int
edd0: 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 errupt() call re
ede0: 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 turns..**.** Req
edf0: 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
ee00: 31 32 32 37 31 5d 20 5b 48 31 32 32 37 32 5d 0a 12271] [H12272].
ee10: 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 **.** If the dat
ee20: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
ee30: 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 closes while [s
ee40: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
ee50: 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e ()].** is runnin
ee60: 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 g then bad thing
ee70: 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 s will likely ha
ee80: 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 ppen..*/.void sq
ee90: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
eea0: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a sqlite3*);../*.*
eeb0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 * CAPI3REF: Dete
eec0: 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 rmine If An SQL
eed0: 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d Statement Is Com
eee0: 70 6c 65 74 65 20 7b 48 31 30 35 31 30 7d 20 3c plete {H10510} <
eef0: 53 37 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S70200>.**.** Th
ef00: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
ef10: 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 useful during c
ef20: 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 ommand-line inpu
ef30: 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 t to determine i
ef40: 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 f the.** current
ef50: 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 ly entered text
ef60: 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 seems to form a
ef70: 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 complete SQL sta
ef80: 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 tement or.** if
ef90: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 additional input
efa0: 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 is needed befor
efb0: 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 e sending the te
efc0: 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 xt into.** SQLit
efd0: 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 e for parsing.
efe0: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
eff0: 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 eturn 1 if the i
f000: 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 nput string.** a
f010: 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 ppears to be a c
f020: 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 omplete SQL stat
f030: 65 6d 65 6e 74 2e 20 20 41 20 73 74 61 74 65 6d ement. A statem
f040: 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f ent is judged to
f050: 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 be.** complete
f060: 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 if it ends with
f070: 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 a semicolon toke
f080: 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 n and is not a p
f090: 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 refix of a.** we
f0a0: 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 ll-formed CREATE
f0b0: 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 TRIGGER stateme
f0c0: 6e 74 2e 20 20 53 65 6d 69 63 6f 6c 6f 6e 73 20 nt. Semicolons
f0d0: 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 that are embedde
f0e0: 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 d within.** stri
f0f0: 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 ng literals or q
f100: 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 uoted identifier
f110: 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e names or commen
f120: 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e ts are not.** in
f130: 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 dependent tokens
f140: 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20 (they are part
f150: 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 of the token in
f160: 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a which they are.*
f170: 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 * embedded) and
f180: 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e thus do not coun
f190: 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 t as a statement
f1a0: 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 57 68 terminator. Wh
f1b0: 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 itespace.** and
f1c0: 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f comments that fo
f1d0: 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 llow the final s
f1e0: 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e emicolon are ign
f1f0: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ored..**.** Thes
f200: 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 e routines retur
f210: 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65 n 0 if the state
f220: 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 ment is incomple
f230: 74 65 2e 20 20 49 66 20 61 0a 2a 2a 20 6d 65 6d te. If a.** mem
f240: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 ory allocation f
f250: 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 ails, then SQLIT
f260: 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 E_NOMEM is retur
f270: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ned..**.** These
f280: 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 routines do not
f290: 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 parse the SQL s
f2a0: 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a tatements thus.*
f2b0: 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 * will not detec
f2c0: 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 t syntactically
f2d0: 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a incorrect SQL..*
f2e0: 2a 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65 20 68 *.** If SQLite h
f2f0: 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 as not been init
f300: 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 ialized using [s
f310: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
f320: 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 e()] prior .** t
f330: 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 o invoking sqlit
f340: 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 e3_complete16()
f350: 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 then sqlite3_ini
f360: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 tialize() is inv
f370: 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 oked.** automati
f380: 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 cally by sqlite3
f390: 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 _complete16().
f3a0: 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 If that initiali
f3b0: 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a zation fails,.**
f3c0: 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e then the return
f3d0: 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 value from sqli
f3e0: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 te3_complete16()
f3f0: 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 will be non-zer
f400: 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 o.** regardless
f410: 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f of whether or no
f420: 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 t the input SQL
f430: 69 73 20 63 6f 6d 70 6c 65 74 65 2e 0a 2a 2a 0a is complete..**.
f440: 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
f450: 20 5b 48 31 30 35 31 31 5d 20 5b 48 31 30 35 31 [H10511] [H1051
f460: 32 5d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 2].**.** The inp
f470: 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ut to [sqlite3_c
f480: 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 omplete()] must
f490: 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e be a zero-termin
f4a0: 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 ated.** UTF-8 st
f4b0: 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ring..**.** The
f4c0: 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 input to [sqlite
f4d0: 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 3_complete16()]
f4e0: 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 must be a zero-t
f4f0: 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 erminated.** UTF
f500: 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 -16 string in na
f510: 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e tive byte order.
f520: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
f530: 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 complete(const c
f540: 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 har *sql);.int s
f550: 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 qlite3_complete1
f560: 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6(const void *sq
f570: 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 l);../*.** CAPI3
f580: 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 REF: Register A
f590: 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 Callback To Hand
f5a0: 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 le SQLITE_BUSY E
f5b0: 72 72 6f 72 73 20 7b 48 31 32 33 31 30 7d 20 3c rrors {H12310} <
f5c0: 53 34 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S40400>.**.** Th
f5d0: 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 is routine sets
f5e0: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 a callback funct
f5f0: 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 ion that might b
f600: 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 e invoked whenev
f610: 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 er.** an attempt
f620: 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e is made to open
f630: 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c a database tabl
f640: 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 e that another t
f650: 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 hread.** or proc
f660: 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a ess has locked..
f670: 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73 **.** If the bus
f680: 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 y callback is NU
f690: 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 LL, then [SQLITE
f6a0: 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 _BUSY] or [SQLIT
f6b0: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d E_IOERR_BLOCKED]
f6c0: 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 .** is returned
f6d0: 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e immediately upon
f6e0: 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 encountering th
f6f0: 65 20 6c 6f 63 6b 2e 20 49 66 20 74 68 65 20 62 e lock. If the b
f700: 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 usy callback.**
f710: 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 is not NULL, the
f720: 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 n the callback w
f730: 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 ill be invoked w
f740: 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 ith two argument
f750: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 s..**.** The fir
f760: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 st argument to t
f770: 68 65 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 he handler is a
f780: 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 copy of the void
f790: 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a * pointer which.
f7a0: 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 ** is the third
f7b0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
f7c0: 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 te3_busy_handler
f7d0: 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 (). The second
f7e0: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 argument to.** t
f7f0: 68 65 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 he handler callb
f800: 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 ack is the numbe
f810: 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 r of times that
f820: 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
f830: 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 has.** been inv
f840: 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f oked for this lo
f850: 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 49 66 cking event. If
f860: 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c the.** busy cal
f870: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c lback returns 0,
f880: 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f then no additio
f890: 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 nal attempts are
f8a0: 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 made to.** acce
f8b0: 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ss the database
f8c0: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 and [SQLITE_BUSY
f8d0: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 ] or [SQLITE_IOE
f8e0: 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 RR_BLOCKED] is r
f8f0: 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 eturned..** If t
f900: 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 he callback retu
f910: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 rns non-zero, th
f920: 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d en another attem
f930: 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f pt.** is made to
f940: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 open the databa
f950: 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 se for reading a
f960: 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 nd the cycle rep
f970: 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 eats..**.** The
f980: 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 presence of a bu
f990: 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 sy handler does
f9a0: 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 not guarantee th
f9b0: 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e at it will be in
f9c0: 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 voked.** when th
f9d0: 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 ere is lock cont
f9e0: 65 6e 74 69 6f 6e 2e 20 49 66 20 53 51 4c 69 74 ention. If SQLit
f9f0: 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 e determines tha
fa00: 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 t invoking the b
fa10: 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 usy.** handler c
fa20: 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 ould result in a
fa30: 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 deadlock, it wi
fa40: 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 ll go ahead and
fa50: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 return [SQLITE_B
fa60: 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 USY].** or [SQLI
fa70: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 TE_IOERR_BLOCKED
fa80: 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 ] instead of inv
fa90: 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 oking the busy h
faa0: 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 andler..** Consi
fab0: 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 der a scenario w
fac0: 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 here one process
fad0: 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 is holding a re
fae0: 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 ad lock that.**
faf0: 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 it is trying to
fb00: 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 promote to a res
fb10: 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a erved lock and.*
fb20: 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 * a second proce
fb30: 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 ss is holding a
fb40: 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 reserved lock th
fb50: 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a at it is trying.
fb60: 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f ** to promote to
fb70: 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f an exclusive lo
fb80: 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 ck. The first p
fb90: 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 rocess cannot pr
fba0: 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 oceed.** because
fbb0: 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 it is blocked b
fbc0: 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 y the second and
fbd0: 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 the second proc
fbe0: 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 ess cannot.** pr
fbf0: 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 oceed because it
fc00: 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 is blocked by t
fc10: 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f he first. If bo
fc20: 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 th processes.**
fc30: 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 invoke the busy
fc40: 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 handlers, neithe
fc50: 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 r will make any
fc60: 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 progress. There
fc70: 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 fore,.** SQLite
fc80: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
fc90: 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 BUSY] for the fi
fca0: 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 rst process, hop
fcb0: 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a ing that this.**
fcc0: 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 will induce the
fcd0: 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 first process t
fce0: 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 o release its re
fcf0: 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f ad lock and allo
fd00: 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 w.** the second
fd10: 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 process to proce
fd20: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 ed..**.** The de
fd30: 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 fault busy callb
fd40: 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a ack is NULL..**.
fd50: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 ** The [SQLITE_B
fd60: 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f USY] error is co
fd70: 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 nverted to [SQLI
fd80: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 TE_IOERR_BLOCKED
fd90: 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 ].** when SQLite
fda0: 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c is in the middl
fdb0: 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 e of a large tra
fdc0: 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 nsaction where a
fdd0: 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 ll the.** change
fde0: 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 s will not fit i
fdf0: 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 nto the in-memor
fe00: 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 y cache. SQLite
fe10: 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 will.** already
fe20: 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 hold a RESERVED
fe30: 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 lock on the dat
fe40: 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 abase file, but
fe50: 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 it needs.** to p
fe60: 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b romote this lock
fe70: 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f to EXCLUSIVE so
fe80: 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 that it can spi
fe90: 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 ll cache.** page
fea0: 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 s into the datab
feb0: 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 ase file without
fec0: 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 harm to concurr
fed0: 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 ent.** readers.
fee0: 20 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 If it is unable
fef0: 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 to promote the
ff00: 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 lock, then the i
ff10: 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 n-memory.** cach
ff20: 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 e will be left i
ff30: 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e n an inconsisten
ff40: 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 t state and so t
ff50: 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 he error.** code
ff60: 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f is promoted fro
ff70: 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 m the relatively
ff80: 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f benign [SQLITE_
ff90: 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 BUSY] to.** the
ffa0: 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c more severe [SQL
ffb0: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 ITE_IOERR_BLOCKE
ffc0: 44 5d 2e 20 20 54 68 69 73 20 65 72 72 6f 72 20 D]. This error
ffd0: 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a code promotion.*
ffe0: 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f * forces an auto
fff0: 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f matic rollback o
10000 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 f the changes.
10010 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 See the.** <a hr
10020 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b ef="/cvstrac/wik
10030 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f i?p=CorruptionFo
10040 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 llowingBusyError
10050 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e ">.** Corruption
10060 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 FollowingBusyErr
10070 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 or</a> wiki page
10080 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f for a discussio
10090 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 n of why.** this
100a0 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a is important..*
100b0 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f *.** There can o
100c0 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 nly be a single
100d0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 busy handler def
100e0 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a ined for each.**
100f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
10100 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 ction]. Setting
10110 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 a new busy hand
10120 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a ler clears any.*
10130 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 * previously set
10140 20 68 61 6e 64 6c 65 72 2e 20 20 4e 6f 74 65 20 handler. Note
10150 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 that calling [sq
10160 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f lite3_busy_timeo
10170 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c ut()].** will al
10180 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 so set or clear
10190 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
101a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 ..**.** The busy
101b0 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 callback should
101c0 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 not take any ac
101d0 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 tions which modi
101e0 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 fy the.** databa
101f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 se connection th
10200 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 at invoked the b
10210 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e usy handler. An
10220 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a y such actions.*
10230 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 * result in unde
10240 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a fined behavior..
10250 2a 2a 20 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 ** .** Requireme
10260 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 33 31 31 5d nts:.** [H12311]
10270 20 5b 48 31 32 33 31 32 5d 20 5b 48 31 32 33 31 [H12312] [H1231
10280 34 5d 20 5b 48 31 32 33 31 36 5d 20 5b 48 31 32 4] [H12316] [H12
10290 33 31 38 5d 0a 2a 2a 0a 2a 2a 20 41 20 62 75 73 318].**.** A bus
102a0 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e y handler must n
102b0 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 ot close the dat
102c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
102d0 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 .** or [prepared
102e0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 statement] that
102f0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 invoked the bus
10300 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e y handler..*/.in
10310 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 t sqlite3_busy_h
10320 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c andler(sqlite3*,
10330 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e int(*)(void*,in
10340 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a t), void*);../*.
10350 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 ** CAPI3REF: Set
10360 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 20 A Busy Timeout
10370 7b 48 31 32 33 34 30 7d 20 3c 53 34 30 34 31 30 {H12340} <S40410
10380 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 >.**.** This rou
10390 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c tine sets a [sql
103a0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 ite3_busy_handle
103b0 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 r | busy handler
103c0 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a ] that sleeps.**
103d0 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 for a specified
103e0 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 amount of time
103f0 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 when a table is
10400 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 68 61 6e locked. The han
10410 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 dler.** will sle
10420 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 ep multiple time
10430 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 s until at least
10440 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e "ms" millisecon
10450 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a ds of sleeping.*
10460 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 * have accumulat
10470 65 64 2e 20 7b 48 31 32 33 34 33 7d 20 41 66 74 ed. {H12343} Aft
10480 65 72 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 er "ms" millisec
10490 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 onds of sleeping
104a0 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 ,.** the handler
104b0 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 returns 0 which
104c0 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 causes [sqlite3
104d0 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 _step()] to retu
104e0 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 rn.** [SQLITE_BU
104f0 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 SY] or [SQLITE_I
10500 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a OERR_BLOCKED]..*
10510 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69 *.** Calling thi
10520 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 s routine with a
10530 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 n argument less
10540 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f than or equal to
10550 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f zero.** turns o
10560 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 ff all busy hand
10570 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 lers..**.** Ther
10580 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 e can only be a
10590 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 single busy hand
105a0 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 ler for a partic
105b0 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 ular.** [databas
105c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e e connection] an
105d0 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 y any given mome
105e0 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 nt. If another
105f0 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 busy handler.**
10600 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 was defined (us
10610 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 ing [sqlite3_bus
10620 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 y_handler()]) pr
10630 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a ior to calling.*
10640 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 * this routine,
10650 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 that other busy
10660 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 handler is clear
10670 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 ed..**.** Requir
10680 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 33 ements:.** [H123
10690 34 31 5d 20 5b 48 31 32 33 34 33 5d 20 5b 48 31 41] [H12343] [H1
106a0 32 33 34 34 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 2344].*/.int sql
106b0 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 ite3_busy_timeou
106c0 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 t(sqlite3*, int
106d0 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ms);../*.** CAPI
106e0 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 3REF: Convenienc
106f0 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 e Routines For R
10700 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 20 7b unning Queries {
10710 48 31 32 33 37 30 7d 20 3c 53 31 30 30 30 30 3e H12370} <S10000>
10720 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f .**.** Definitio
10730 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 n: A <b>result t
10740 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f able</b> is memo
10750 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 ry data structur
10760 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 e created by the
10770 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 .** [sqlite3_get
10780 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 _table()] interf
10790 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 ace. A result t
107a0 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 able records the
107b0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 .** complete que
107c0 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 ry results from
107d0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 one or more quer
107e0 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 ies..**.** The t
107f0 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c able conceptuall
10800 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f y has a number o
10810 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d f rows and colum
10820 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 ns. But.** thes
10830 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f e numbers are no
10840 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 t part of the re
10850 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c sult table itsel
10860 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d f. These.** num
10870 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 bers are obtaine
10880 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c d separately. L
10890 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 et N be the numb
108a0 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e er of rows.** an
108b0 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 d M be the numbe
108c0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a r of columns..**
108d0 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 .** A result tab
108e0 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f le is an array o
108f0 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 f pointers to ze
10900 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 ro-terminated UT
10910 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 F-8 strings..**
10920 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a There are (N+1)*
10930 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 M elements in th
10940 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 e array. The fi
10950 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 rst M pointers p
10960 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d oint.** to zero-
10970 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e terminated strin
10980 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e gs that contain
10990 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 the names of th
109a0 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 e columns..** Th
109b0 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 e remaining entr
109c0 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f ies all point to
109d0 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 query results.
109e0 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 NULL values res
109f0 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 ult.** in NULL p
10a00 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 ointers. All ot
10a10 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 her values are i
10a20 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 n their UTF-8 ze
10a30 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ro-terminated.**
10a40 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e string represen
10a50 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e tation as return
10a60 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 ed by [sqlite3_c
10a70 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a olumn_text()]..*
10a80 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 *.** A result ta
10a90 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 ble might consis
10aa0 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 t of one or more
10ab0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
10ac0 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f ons..** It is no
10ad0 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 t safe to pass a
10ae0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 result table di
10af0 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 rectly to [sqlit
10b00 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 e3_free()]..** A
10b10 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 result table sh
10b20 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 ould be dealloca
10b30 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ted using [sqlit
10b40 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d e3_free_table()]
10b50 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78 ..**.** As an ex
10b60 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 ample of the res
10b70 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 ult table format
10b80 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 , suppose a quer
10b90 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 y result.** is a
10ba0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a s follows:.**.**
10bb0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
10bc0 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d e>.** Nam
10bd0 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a e | Age.*
10be0 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d * -------
10bf0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
10c00 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 .** Alice
10c10 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 | 43.**
10c20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 Bob
10c30 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 | 28.**
10c40 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 Cindy | 2
10c50 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 1.** </pre></blo
10c60 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 ckquote>.**.** T
10c70 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c here are two col
10c80 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 umn (M==2) and t
10c90 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 hree rows (N==3)
10ca0 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 . Thus the.** r
10cb0 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 esult table has
10cc0 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 8 entries. Supp
10cd0 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 ose the result t
10ce0 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a able is stored.*
10cf0 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 * in an array na
10d00 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 mes azResult. T
10d10 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c hen azResult hol
10d20 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a ds this content:
10d30 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
10d40 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 te><pre>.**
10d50 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
10d60 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 0] = "Name";.**
10d70 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
10d80 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a #91;1] = "Age";.
10d90 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
10da0 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 lt[2] = "Ali
10db0 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 ce";.** a
10dc0 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d zResult[3] =
10dd0 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 "43";.**
10de0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d azResult[4]
10df0 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 = "Bob";.**
10e00 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
10e10 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 ;5] = "28";.**
10e20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
10e30 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 91;6] = "Cindy";
10e40 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
10e50 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 ult[7] = "21
10e60 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c ";.** </pre></bl
10e70 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
10e80 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f The sqlite3_get_
10e90 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e table() function
10ea0 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f evaluates one o
10eb0 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f r more.** semico
10ec0 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 lon-separated SQ
10ed0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 L statements in
10ee0 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 the zero-termina
10ef0 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 ted UTF-8.** str
10f00 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 ing of its 2nd p
10f10 61 72 61 6d 65 74 65 72 2e 20 20 49 74 20 72 65 arameter. It re
10f20 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 turns a result t
10f30 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 able to the.** p
10f40 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 ointer given in
10f50 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 its 3rd paramete
10f60 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 r..**.** After t
10f70 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 he calling funct
10f80 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 ion has finished
10f90 20 75 73 69 6e 67 20 74 68 65 20 72 65 73 75 6c using the resul
10fa0 74 2c 20 69 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 t, it should.**
10fb0 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 pass the pointer
10fc0 20 74 6f 20 74 68 65 20 72 65 73 75 6c 74 20 74 to the result t
10fd0 61 62 6c 65 20 74 6f 20 73 71 6c 69 74 65 33 5f able to sqlite3_
10fe0 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 free_table() in
10ff0 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 order to.** rele
11000 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 ase the memory t
11010 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 hat was malloced
11020 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 . Because of th
11030 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 e way the.** [sq
11040 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
11050 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 happens within s
11060 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
11070 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a (), the calling.
11080 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 ** function must
11090 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c not try to call
110a0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
110b0 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c ] directly. Onl
110c0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 y.** [sqlite3_fr
110d0 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 ee_table()] is a
110e0 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 ble to release t
110f0 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 he memory proper
11100 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a ly and safely..*
11110 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
11120 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 _get_table() int
11130 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d erface is implem
11140 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 ented as a wrapp
11150 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 er around.** [sq
11160 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 lite3_exec()].
11170 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f The sqlite3_get_
11180 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 table() routine
11190 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 does not have ac
111a0 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 cess.** to any i
111b0 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 nternal data str
111c0 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 uctures of SQLit
111d0 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 e. It uses only
111e0 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 the public.** i
111f0 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 nterface defined
11200 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e here. As a con
11210 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 sequence, errors
11220 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 that occur in t
11230 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 he.** wrapper la
11240 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 yer outside of t
11250 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c he internal [sql
11260 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c ite3_exec()] cal
11270 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 l are not.** ref
11280 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 lected in subseq
11290 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 uent calls to [s
112a0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 qlite3_errcode()
112b0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 ] or [sqlite3_er
112c0 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 rmsg()]..**.** R
112d0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
112e0 5b 48 31 32 33 37 31 5d 20 5b 48 31 32 33 37 33 [H12371] [H12373
112f0 5d 20 5b 48 31 32 33 37 34 5d 20 5b 48 31 32 33 ] [H12374] [H123
11300 37 36 5d 20 5b 48 31 32 33 37 39 5d 20 5b 48 31 76] [H12379] [H1
11310 32 33 38 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 2382].*/.int sql
11320 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a ite3_get_table(.
11330 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
11340 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 /* An op
11350 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 en database */.
11360 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 const char *zSq
11370 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f l, /* SQL to
11380 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f be evaluated */
11390 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 . char ***pazRe
113a0 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 sult, /* Resu
113b0 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 lts of the query
113c0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 */. int *pnRow
113d0 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e , /* N
113e0 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 umber of result
113f0 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 rows written her
11400 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f e */. int *pnCo
11410 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 lumn, /*
11420 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 Number of result
11430 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e columns written
11440 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 here */. char
11450 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 **pzErrmsg
11460 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 /* Error msg wr
11470 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b itten here */.);
11480 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 .void sqlite3_fr
11490 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a ee_table(char **
114a0 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 result);../*.**
114b0 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 CAPI3REF: Format
114c0 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 ted String Print
114d0 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 ing Functions {H
114e0 31 37 34 30 30 7d 20 3c 53 37 30 30 30 30 3e 3c 17400} <S70000><
114f0 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S20000>.**.** Th
11500 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
11510 20 77 6f 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 workalikes of t
11520 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 he "printf()" fa
11530 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e mily of function
11540 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 s.** from the st
11550 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 andard C library
11560 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
11570 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e te3_mprintf() an
11580 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e d sqlite3_vmprin
11590 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 tf() routines wr
115a0 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 ite their.** res
115b0 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 ults into memory
115c0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
115d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
115e0 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 ]..** The string
115f0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 s returned by th
11600 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 ese two routines
11610 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 should be.** re
11620 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 leased by [sqlit
11630 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 42 6f 74 e3_free()]. Bot
11640 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 h routines retur
11650 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e n a.** NULL poin
11660 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f ter if [sqlite3_
11670 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 malloc()] is una
11680 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 ble to allocate
11690 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 enough.** memory
116a0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 to hold the res
116b0 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a ulting string..*
116c0 2a 0a 2a 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f *.** In sqlite3_
116d0 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 snprintf() routi
116e0 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f ne is similar to
116f0 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 "snprintf()" fr
11700 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 om.** the standa
11710 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 rd C library. T
11720 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 he result is wri
11730 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a tten into the.**
11740 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 buffer supplied
11750 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 as the second p
11760 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 arameter whose s
11770 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a ize is given by.
11780 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 ** the first par
11790 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 ameter. Note tha
117a0 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 t the order of t
117b0 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 he.** first two
117c0 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 parameters is re
117d0 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 versed from snpr
117e0 69 6e 74 66 28 29 2e 20 20 54 68 69 73 20 69 73 intf(). This is
117f0 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 an.** historica
11800 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 l accident that
11810 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 cannot be fixed
11820 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 without breaking
11830 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f .** backwards co
11840 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f mpatibility. No
11850 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c te also that sql
11860 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a ite3_snprintf().
11870 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ** returns a poi
11880 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 nter to its buff
11890 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 er instead of th
118a0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 e number of.** c
118b0 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c haracters actual
118c0 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 ly written into
118d0 74 68 65 20 62 75 66 66 65 72 2e 20 20 57 65 20 the buffer. We
118e0 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 admit that.** th
118f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 e number of char
11900 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 acters written w
11910 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 ould be a more u
11920 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 seful return.**
11930 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e value but we can
11940 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 not change the i
11950 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
11960 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 sqlite3_snprint
11970 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f f().** now witho
11980 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 ut breaking comp
11990 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a atibility..**.**
119a0 20 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 As long as the
119b0 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 buffer size is g
119c0 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f reater than zero
119d0 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e , sqlite3_snprin
119e0 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 tf().** guarante
119f0 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 es that the buff
11a00 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 er is always zer
11a10 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 o-terminated. T
11a20 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 he first.** para
11a30 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 meter "n" is the
11a40 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 total size of t
11a50 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 he buffer, inclu
11a60 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a ding space for.*
11a70 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 * the zero termi
11a80 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c nator. So the l
11a90 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 ongest string th
11aa0 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 at can be comple
11ab0 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 tely.** written
11ac0 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 will be n-1 char
11ad0 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 acters..**.** Th
11ae0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c ese routines all
11af0 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 implement some
11b00 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 additional forma
11b10 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 tting.** options
11b20 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c that are useful
11b30 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e for constructin
11b40 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 g SQL statements
11b50 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 ..** All of the
11b60 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 usual printf() f
11b70 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e ormatting option
11b80 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 s apply. In add
11b90 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 ition, there.**
11ba0 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 is are "%q", "%Q
11bb0 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 ", and "%z" opti
11bc0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 ons..**.** The %
11bd0 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c q option works l
11be0 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 ike %s in that i
11bf0 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 t substitutes a
11c00 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a null-terminated.
11c10 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 ** string from t
11c20 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 he argument list
11c30 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 . But %q also d
11c40 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 oubles every '\'
11c50 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 ' character..**
11c60 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 %q is designed f
11c70 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 or use inside a
11c80 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 20 string literal.
11c90 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 By doubling eac
11ca0 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 h '\''.** charac
11cb0 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 ter it escapes t
11cc0 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e hat character an
11cd0 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 d allows it to b
11ce0 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a e inserted into.
11cf0 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a ** the string..*
11d00 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 *.** For example
11d10 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 , assume the str
11d20 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 ing variable zTe
11d30 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 xt contains text
11d40 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a as follows:.**.
11d50 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
11d60 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a pre>.** char *z
11d70 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 Text = "It's a h
11d80 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c appy day!";.** <
11d90 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
11da0 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e e>.**.** One can
11db0 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 use this text i
11dc0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 n an SQL stateme
11dd0 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a nt as follows:.*
11de0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
11df0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 ><pre>.** char
11e00 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f *zSQL = sqlite3_
11e10 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 mprintf("INSERT
11e20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 INTO table VALUE
11e30 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 S('%q')", zText)
11e40 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 ;.** sqlite3_ex
11e50 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 ec(db, zSQL, 0,
11e60 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 0, 0);.** sqlit
11e70 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a e3_free(zSQL);.*
11e80 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
11e90 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 uote>.**.** Beca
11ea0 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 use the %q forma
11eb0 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 t string is used
11ec0 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 , the '\'' chara
11ed0 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a cter in zText.**
11ee0 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 is escaped and
11ef0 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 the SQL generate
11f00 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a d is as follows:
11f10 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
11f20 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 te><pre>.** INS
11f30 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 ERT INTO table1
11f40 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 VALUES('It''s a
11f50 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 happy day!').**
11f60 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
11f70 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 te>.**.** This i
11f80 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 s correct. Had
11f90 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 we used %s inste
11fa0 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 ad of %q, the ge
11fb0 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 nerated SQL.** w
11fc0 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 ould have looked
11fd0 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a like this:.**.*
11fe0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
11ff0 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 re>.** INSERT I
12000 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 NTO table1 VALUE
12010 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 S('It's a happy
12020 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 day!');.** </pre
12030 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
12040 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 *.** This second
12050 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 example is an S
12060 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e QL syntax error.
12070 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 As a general r
12080 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a ule you should.*
12090 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 * always use %q
120a0 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 instead of %s wh
120b0 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 en inserting tex
120c0 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 t into a string
120d0 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 literal..**.** T
120e0 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 he %Q option wor
120f0 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 ks like %q excep
12100 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 t it also adds s
12110 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f ingle quotes aro
12120 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 und.** the outsi
12130 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 de of the total
12140 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f string. Additio
12150 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 nally, if the pa
12160 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a rameter in the.*
12170 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 * argument list
12180 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
12190 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65 r, %Q substitute
121a0 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c s the text "NULL
121b0 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 " (without.** si
121c0 6e 67 6c 65 20 71 75 6f 74 65 73 29 20 69 6e 20 ngle quotes) in
121d0 70 6c 61 63 65 20 6f 66 20 74 68 65 20 25 51 20 place of the %Q
121e0 6f 70 74 69 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 option. So, for
121f0 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f example, one co
12200 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c uld say:.**.** <
12210 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
12220 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 .** char *zSQL
12230 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 = sqlite3_mprint
12240 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 f("INSERT INTO t
12250 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 able VALUES(%Q)"
12260 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 , zText);.** sq
12270 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a lite3_exec(db, z
12280 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a SQL, 0, 0, 0);.*
12290 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 * sqlite3_free(
122a0 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e zSQL);.** </pre>
122b0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
122c0 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f .** The code abo
122d0 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 ve will render a
122e0 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 correct SQL sta
122f0 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 tement in the zS
12300 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 QL.** variable e
12310 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 ven if the zText
12320 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e variable is a N
12330 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a ULL pointer..**.
12340 2a 2a 20 54 68 65 20 22 25 7a 22 20 66 6f 72 6d ** The "%z" form
12350 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f atting option wo
12360 72 6b 73 20 65 78 61 63 74 6c 79 20 6c 69 6b 65 rks exactly like
12370 20 22 25 73 22 20 77 69 74 68 20 74 68 65 0a 2a "%s" with the.*
12380 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 * addition that
12390 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 after the string
123a0 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 has been read a
123b0 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a nd copied into.*
123c0 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 * the result, [s
123d0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 qlite3_free()] i
123e0 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 s called on the
123f0 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 20 7b 45 input string. {E
12400 4e 44 7d 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 ND}.**.** Requir
12410 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 34 ements:.** [H174
12420 30 33 5d 20 5b 48 31 37 34 30 36 5d 20 5b 48 31 03] [H17406] [H1
12430 37 34 30 37 5d 0a 2a 2f 0a 63 68 61 72 20 2a 73 7407].*/.char *s
12440 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 qlite3_mprintf(c
12450 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b onst char*,...);
12460 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 .char *sqlite3_v
12470 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 mprintf(const ch
12480 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 ar*, va_list);.c
12490 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 har *sqlite3_snp
124a0 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c rintf(int,char*,
124b0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e const char*, ...
124c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
124d0 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 EF: Memory Alloc
124e0 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 20 ation Subsystem
124f0 7b 48 31 37 33 30 30 7d 20 3c 53 32 30 30 30 30 {H17300} <S20000
12500 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 >.**.** The SQLi
12510 74 65 20 63 6f 72 65 20 20 75 73 65 73 20 74 68 te core uses th
12520 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e ese three routin
12530 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 es for all of it
12540 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 s own.** interna
12550 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 l memory allocat
12560 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 ion needs. "Core
12570 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 " in the previou
12580 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f s sentence.** do
12590 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f es not include o
125a0 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 perating-system
125b0 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 specific VFS imp
125c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 lementation. Th
125d0 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 e.** Windows VFS
125e0 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c uses native mal
125f0 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 loc() and free()
12600 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 for some operat
12610 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ions..**.** The
12620 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
12630 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
12640 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
12650 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f block.** of memo
12660 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 ry at least N by
12670 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 tes in length, w
12680 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 here N is the pa
12690 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 49 66 20 73 rameter..** If s
126a0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
126b0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 is unable to obt
126c0 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 ain sufficient f
126d0 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 ree.** memory, i
126e0 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c t returns a NULL
126f0 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 74 68 pointer. If th
12700 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f e parameter N to
12710 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c .** sqlite3_mall
12720 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 oc() is zero or
12730 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 negative then sq
12740 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 lite3_malloc() r
12750 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c eturns.** a NULL
12760 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 pointer..**.**
12770 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f Calling sqlite3_
12780 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f free() with a po
12790 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 inter previously
127a0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 returned.** by
127b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
127c0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c or sqlite3_real
127d0 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 loc() releases t
127e0 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a hat memory so.**
127f0 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 that it might b
12800 65 20 72 65 75 73 65 64 2e 20 20 54 68 65 20 73 e reused. The s
12810 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f qlite3_free() ro
12820 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f utine is.** a no
12830 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 -op if is called
12840 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 with a NULL poi
12850 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 nter. Passing a
12860 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a NULL pointer.**
12870 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 to sqlite3_free
12880 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 () is harmless.
12890 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 After being fre
128a0 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 ed, memory.** sh
128b0 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 ould neither be
128c0 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e read nor written
128d0 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 . Even reading
128e0 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 previously freed
128f0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 .** memory might
12900 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 result in a seg
12910 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 mentation fault
12920 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 or other severe
12930 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 error..** Memory
12940 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 corruption, a s
12950 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c egmentation faul
12960 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 t, or other seve
12970 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 re error.** migh
12980 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 t result if sqli
12990 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 te3_free() is ca
129a0 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d lled with a non-
129b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 NULL pointer tha
129c0 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 t.** was not obt
129d0 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 ained from sqlit
129e0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 e3_malloc() or s
129f0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
12a00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
12a10 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e te3_realloc() in
12a20 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 terface attempts
12a30 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 to resize a.**
12a40 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c prior memory all
12a50 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 ocation to be at
12a60 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 least N bytes,
12a70 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a where N is the.*
12a80 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 * second paramet
12a90 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 er. The memory
12aa0 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 allocation to be
12ab0 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 resized is the
12ac0 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 first.** paramet
12ad0 65 72 2e 20 20 49 66 20 74 68 65 20 66 69 72 73 er. If the firs
12ae0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 t parameter to s
12af0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
12b00 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f .** is a NULL po
12b10 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 inter then its b
12b20 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 ehavior is ident
12b30 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a ical to calling.
12b40 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f ** sqlite3_mallo
12b50 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 c(N) where N is
12b60 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
12b70 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
12b80 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66 realloc()..** If
12b90 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
12ba0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
12bb0 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 _realloc() is ze
12bc0 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 ro or.** negativ
12bd0 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 e then the behav
12be0 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 ior is exactly t
12bf0 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 he same as calli
12c00 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 ng.** sqlite3_fr
12c10 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73 ee(P) where P is
12c20 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
12c30 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
12c40 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 73 71 realloc()..** sq
12c50 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 lite3_realloc()
12c60 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
12c70 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c r to a memory al
12c80 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 location.** of a
12c90 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 t least N bytes
12ca0 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 in size or NULL
12cb0 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 if sufficient me
12cc0 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 mory is unavaila
12cd0 62 6c 65 2e 0a 2a 2a 20 49 66 20 4d 20 69 73 20 ble..** If M is
12ce0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
12cf0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e prior allocation
12d00 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 , then min(N,M)
12d10 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 bytes.** of the
12d20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e prior allocation
12d30 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f are copied into
12d40 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f the beginning o
12d50 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 f buffer returne
12d60 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f d.** by sqlite3_
12d70 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 realloc() and th
12d80 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 e prior allocati
12d90 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 on is freed..**
12da0 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c If sqlite3_reall
12db0 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c oc() returns NUL
12dc0 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f L, then the prio
12dd0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 r allocation.**
12de0 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a is not freed..**
12df0 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 72 .** The memory r
12e00 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
12e10 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 e3_malloc() and
12e20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
12e30 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 ).** is always a
12e40 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 ligned to at lea
12e50 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 st an 8 byte bou
12e60 6e 64 61 72 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a ndary. {END}.**.
12e70 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 69 ** The default i
12e80 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
12e90 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f the memory allo
12ea0 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d cation subsystem
12eb0 20 75 73 65 73 0a 2a 2a 20 74 68 65 20 6d 61 6c uses.** the mal
12ec0 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 loc(), realloc()
12ed0 20 61 6e 64 20 66 72 65 65 28 29 20 70 72 6f 76 and free() prov
12ee0 69 64 65 64 20 62 79 20 74 68 65 20 73 74 61 6e ided by the stan
12ef0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a dard C library..
12f00 2a 2a 20 7b 48 31 37 33 38 32 7d 20 48 6f 77 65 ** {H17382} Howe
12f10 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 ver, if SQLite i
12f20 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 s compiled with
12f30 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 45 the.** SQLITE_ME
12f40 4d 4f 52 59 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e MORY_SIZE=<i>NNN
12f50 3c 2f 69 3e 20 43 20 70 72 65 70 72 6f 63 65 73 </i> C preproces
12f60 73 6f 72 20 6d 61 63 72 6f 20 28 77 68 65 72 65 sor macro (where
12f70 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69 <i>NNN</i>.** i
12f80 73 20 61 6e 20 69 6e 74 65 67 65 72 29 2c 20 74 s an integer), t
12f90 68 65 6e 20 53 51 4c 69 74 65 20 63 72 65 61 74 hen SQLite creat
12fa0 65 20 61 20 73 74 61 74 69 63 20 61 72 72 61 79 e a static array
12fb0 20 6f 66 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 of at least.**
12fc0 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 74 65 73 <i>NNN</i> bytes
12fd0 20 69 6e 20 73 69 7a 65 20 61 6e 64 20 75 73 65 in size and use
12fe0 73 20 74 68 61 74 20 61 72 72 61 79 20 66 6f 72 s that array for
12ff0 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 all of its dyna
13000 6d 69 63 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c mic.** memory al
13010 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 location needs.
13020 7b 45 4e 44 7d 20 20 41 64 64 69 74 69 6f 6e 61 {END} Additiona
13030 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 l memory allocat
13040 6f 72 20 6f 70 74 69 6f 6e 73 0a 2a 2a 20 6d 61 or options.** ma
13050 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 y be added in fu
13060 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a ture releases..*
13070 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 *.** In SQLite v
13080 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 ersion 3.5.0 and
13090 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 3.5.1, it was p
130a0 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e ossible to defin
130b0 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f e.** the SQLITE_
130c0 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f OMIT_MEMORY_ALLO
130d0 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 CATION which wou
130e0 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 ld cause the bui
130f0 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 lt-in.** impleme
13100 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 ntation of these
13110 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 routines to be
13120 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 omitted. That c
13130 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 apability.** is
13140 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 no longer provid
13150 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d ed. Only built-
13160 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 in memory alloca
13170 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 tors can be used
13180 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 ..**.** The Wind
13190 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 ows OS interface
131a0 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 layer calls.**
131b0 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f the system mallo
131c0 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 c() and free() d
131d0 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e irectly when con
131e0 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e verting.** filen
131f0 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 ames between the
13200 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 UTF-8 encoding
13210 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a used by SQLite.*
13220 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 * and whatever f
13230 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 ilename encoding
13240 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 is used by the
13250 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f particular Windo
13260 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 ws.** installati
13270 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f on. Memory allo
13280 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 cation errors ar
13290 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a e detected, but.
132a0 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 70 6f ** they are repo
132b0 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 rted back as [SQ
132c0 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f LITE_CANTOPEN] o
132d0 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 r.** [SQLITE_IOE
132e0 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 RR] rather than
132f0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a [SQLITE_NOMEM]..
13300 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
13310 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 30 33 5d 20 ts:.** [H17303]
13320 5b 48 31 37 33 30 34 5d 20 5b 48 31 37 33 30 35 [H17304] [H17305
13330 5d 20 5b 48 31 37 33 30 36 5d 20 5b 48 31 37 33 ] [H17306] [H173
13340 31 30 5d 20 5b 48 31 37 33 31 32 5d 20 5b 48 31 10] [H17312] [H1
13350 37 33 31 35 5d 20 5b 48 31 37 33 31 38 5d 0a 2a 7315] [H17318].*
13360 2a 20 5b 48 31 37 33 32 31 5d 20 5b 48 31 37 33 * [H17321] [H173
13370 32 32 5d 20 5b 48 31 37 33 32 33 5d 0a 2a 2a 0a 22] [H17323].**.
13380 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 ** The pointer a
13390 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c rguments to [sql
133a0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 ite3_free()] and
133b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f [sqlite3_reallo
133c0 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 c()].** must be
133d0 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 either NULL or e
133e0 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 lse pointers obt
133f0 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 ained from a pri
13400 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e or.** invocation
13410 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c of [sqlite3_mal
13420 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 loc()] or [sqlit
13430 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 e3_realloc()] th
13440 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 at have.** not y
13450 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 et been released
13460 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c ..**.** The appl
13470 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 ication must not
13480 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 read or write a
13490 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 ny part of.** a
134a0 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 block of memory
134b0 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 after it has bee
134c0 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 n released using
134d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 .** [sqlite3_fre
134e0 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 e()] or [sqlite3
134f0 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a _realloc()]..*/.
13500 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 void *sqlite3_ma
13510 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 lloc(int);.void
13520 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 *sqlite3_realloc
13530 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f (void*, int);.vo
13540 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 id sqlite3_free(
13550 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 void*);../*.** C
13560 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 API3REF: Memory
13570 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 Allocator Statis
13580 74 69 63 73 20 7b 48 31 37 33 37 30 7d 20 3c 53 tics {H17370} <S
13590 33 30 32 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 30210>.**.** SQL
135a0 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 ite provides the
135b0 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 se two interface
135c0 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 s for reporting
135d0 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a on the status.**
135e0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
135f0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c _malloc()], [sql
13600 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e ite3_free()], an
13610 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c d [sqlite3_reall
13620 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 oc()].** routine
13630 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 s, which form th
13640 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 e built-in memor
13650 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 y allocation sub
13660 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 52 65 system..**.** Re
13670 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
13680 48 31 37 33 37 31 5d 20 5b 48 31 37 33 37 33 5d H17371] [H17373]
13690 20 5b 48 31 37 33 37 34 5d 20 5b 48 31 37 33 37 [H17374] [H1737
136a0 35 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 5].*/.sqlite3_in
136b0 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f t64 sqlite3_memo
136c0 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 ry_used(void);.s
136d0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c qlite3_int64 sql
136e0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 ite3_memory_high
136f0 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 water(int resetF
13700 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 lag);../*.** CAP
13710 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 I3REF: Pseudo-Ra
13720 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 ndom Number Gene
13730 72 61 74 6f 72 20 7b 48 31 37 33 39 30 7d 20 3c rator {H17390} <
13740 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 S20000>.**.** SQ
13750 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 Lite contains a
13760 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 high-quality pse
13770 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 udo-random numbe
13780 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e r generator (PRN
13790 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 G) used to.** se
137a0 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 lect random [ROW
137b0 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 ID | ROWIDs] whe
137c0 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 n inserting new
137d0 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 records into a t
137e0 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 able that.** alr
137f0 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 eady uses the la
13800 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b rgest possible [
13810 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e ROWID]. The PRN
13820 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 G is also used f
13830 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d or.** the build-
13840 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 in random() and
13850 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c randomblob() SQL
13860 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 functions. Thi
13870 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f s interface allo
13880 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f ws.** applicatio
13890 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 ns to access the
138a0 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f same PRNG for o
138b0 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a ther purposes..*
138c0 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 74 *.** A call to t
138d0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 his routine stor
138e0 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 es N bytes of ra
138f0 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 ndomness into bu
13900 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 ffer P..**.** Th
13910 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 e first time thi
13920 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 s routine is inv
13930 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 oked (either int
13940 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a ernally or by.**
13950 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
13960 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 ) the PRNG is se
13970 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f eded using rando
13980 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a mness obtained.*
13990 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 * from the xRand
139a0 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 omness method of
139b0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 the default [sq
139c0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 lite3_vfs] objec
139d0 74 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73 75 62 t..** On all sub
139e0 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 sequent invocati
139f0 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d ons, the pseudo-
13a00 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 randomness is ge
13a10 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 nerated.** inter
13a20 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 nally and withou
13a30 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 t recourse to th
13a40 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 e [sqlite3_vfs]
13a50 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d xRandomness.** m
13a60 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 ethod..**.** Req
13a70 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
13a80 31 37 33 39 32 5d 0a 2a 2f 0a 76 6f 69 64 20 73 17392].*/.void s
13a90 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 qlite3_randomnes
13aa0 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 s(int N, void *P
13ab0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
13ac0 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 EF: Compile-Time
13ad0 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 Authorization C
13ae0 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 35 30 30 allbacks {H12500
13af0 7d 20 3c 53 37 30 31 30 30 3e 0a 2a 2a 0a 2a 2a } <S70100>.**.**
13b00 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 This routine re
13b10 67 69 73 74 65 72 73 20 61 20 61 75 74 68 6f 72 gisters a author
13b20 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 izer callback wi
13b30 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a th a particular.
13b40 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
13b50 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 nection], suppli
13b60 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 ed in the first
13b70 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 argument..** The
13b80 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
13b90 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
13ba0 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 as SQL statement
13bb0 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 s are being comp
13bc0 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 iled.** by [sqli
13bd0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f te3_prepare()] o
13be0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b r its variants [
13bf0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
13c00 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 v2()],.** [sqlit
13c10 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 e3_prepare16()]
13c20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 and [sqlite3_pre
13c30 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 41 pare16_v2()]. A
13c40 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 t various.** poi
13c50 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 nts during the c
13c60 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 ompilation proce
13c70 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 ss, as logic is
13c80 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a being created.**
13c90 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 to perform vari
13ca0 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 ous actions, the
13cb0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
13cc0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
13cd0 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f to.** see if tho
13ce0 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 se actions are a
13cf0 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20 61 75 74 llowed. The aut
13d00 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
13d10 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 should.** retur
13d20 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f n [SQLITE_OK] to
13d30 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f allow the actio
13d40 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 n, [SQLITE_IGNOR
13d50 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 E] to disallow t
13d60 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 he.** specific a
13d70 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 ction but allow
13d80 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
13d90 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f t to continue to
13da0 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c be.** compiled,
13db0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 or [SQLITE_DENY
13dc0 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 ] to cause the e
13dd0 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d ntire SQL statem
13de0 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a ent to be.** rej
13df0 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 ected with an er
13e00 72 6f 72 2e 20 20 49 66 20 74 68 65 20 61 75 74 ror. If the aut
13e10 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
13e20 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 returns.** any
13e30 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e value other than
13e40 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d [SQLITE_IGNORE]
13e50 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f , [SQLITE_OK], o
13e60 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a r [SQLITE_DENY].
13e70 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c ** then the [sql
13e80 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
13e90 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 )] or equivalent
13ea0 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 call that trigg
13eb0 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 ered.** the auth
13ec0 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c orizer will fail
13ed0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d with an error m
13ee0 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 essage..**.** Wh
13ef0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 en the callback
13f00 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
13f10 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 OK], that means
13f20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a the operation.**
13f30 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b requested is ok
13f40 2e 20 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c . When the call
13f50 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 back returns [SQ
13f60 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a LITE_DENY], the.
13f70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
13f80 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 are_v2()] or equ
13f90 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 ivalent call tha
13fa0 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a t triggered the.
13fb0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 ** authorizer wi
13fc0 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 ll fail with an
13fd0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 error message ex
13fe0 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a plaining that.**
13ff0 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 access is denie
14000 64 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 d. .**.** The fi
14010 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f rst parameter to
14020 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
14030 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f callback is a co
14040 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a py of the third.
14050 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 ** parameter to
14060 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f the sqlite3_set_
14070 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 authorizer() int
14080 65 72 66 61 63 65 2e 20 54 68 65 20 73 65 63 6f erface. The seco
14090 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 nd parameter.**
140a0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
140b0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 is an integer [S
140c0 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 QLITE_COPY | act
140d0 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 ion code] that s
140e0 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 pecifies.** the
140f0 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f particular actio
14100 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a n to be authoriz
14110 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 74 68 ed. The third th
14120 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 rough sixth para
14130 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 meters.** to the
14140 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 callback are ze
14150 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 ro-terminated st
14160 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 rings that conta
14170 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a in additional.**
14180 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 details about t
14190 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 he action to be
141a0 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a authorized..**.*
141b0 2a 20 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 * If the action
141c0 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f code is [SQLITE_
141d0 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 READ].** and the
141e0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
141f0 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 s [SQLITE_IGNORE
14200 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 ] then the.** [p
14210 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
14220 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 t] statement is
14230 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 constructed to s
14240 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e ubstitute.** a N
14250 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 ULL value in pla
14260 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 ce of the table
14270 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c column that woul
14280 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 d have.** been r
14290 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f ead if [SQLITE_O
142a0 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 K] had been retu
142b0 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 rned. The [SQLI
142c0 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 TE_IGNORE].** re
142d0 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 turn can be used
142e0 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 to deny an untr
142f0 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73 usted user acces
14300 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a s to individual.
14310 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 ** columns of a
14320 74 61 62 6c 65 2e 0a 2a 2a 20 49 66 20 74 68 65 table..** If the
14330 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 action code is
14340 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 [SQLITE_DELETE]
14350 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b and the callback
14360 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c returns.** [SQL
14370 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e ITE_IGNORE] then
14380 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 the [DELETE] op
14390 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 eration proceeds
143a0 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 but the.** [tru
143b0 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 ncate optimizati
143c0 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 on] is disabled
143d0 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 and all rows are
143e0 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 deleted individ
143f0 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 ually..**.** An
14400 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 authorizer is us
14410 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 ed when [sqlite3
14420 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 _prepare | prepa
14430 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 ring].** SQL sta
14440 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 tements from an
14450 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 untrusted source
14460 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 , to ensure that
14470 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
14480 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 nts.** do not tr
14490 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 y to access data
144a0 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c they are not al
144b0 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 lowed to see, or
144c0 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f that they do no
144d0 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 t.** try to exec
144e0 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 ute malicious st
144f0 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 atements that da
14500 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 mage the databas
14510 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 e. For.** examp
14520 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 le, an applicati
14530 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 on may allow a u
14540 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 ser to enter arb
14550 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 itrary.** SQL qu
14560 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 eries for evalua
14570 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 tion by a databa
14580 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 se. But the app
14590 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a lication does.**
145a0 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 not want the us
145b0 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f er to be able to
145c0 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 make arbitrary
145d0 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a changes to the.*
145e0 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 * database. An
145f0 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 authorizer could
14600 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 then be put in
14610 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a place while the.
14620 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 ** user-entered
14630 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 SQL is being [sq
14640 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 lite3_prepare |
14650 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a prepared] that.*
14660 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 * disallows ever
14670 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 ything except [S
14680 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 ELECT] statement
14690 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 s..**.** Applica
146a0 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 tions that need
146b0 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 to process SQL f
146c0 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f rom untrusted so
146d0 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 urces.** might a
146e0 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 lso consider low
146f0 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c ering resource l
14700 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c imits using [sql
14710 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a ite3_limit()].**
14720 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 and limiting da
14730 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e tabase size usin
14740 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f g the [max_page_
14750 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a count] [PRAGMA].
14760 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 ** in addition t
14770 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f o using an autho
14780 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c rizer..**.** Onl
14790 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f y a single autho
147a0 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 rizer can be in
147b0 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 place on a datab
147c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase connection.*
147d0 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 * at a time. Ea
147e0 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 ch call to sqlit
147f0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
14800 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a r overrides the.
14810 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c ** previous call
14820 2e 20 20 44 69 73 61 62 6c 65 20 74 68 65 20 61 . Disable the a
14830 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 uthorizer by ins
14840 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 talling a NULL c
14850 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 allback..** The
14860 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 authorizer is di
14870 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c sabled by defaul
14880 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 t..**.** The aut
14890 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
148a0 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 must not do any
148b0 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 thing that will
148c0 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 modify.** the da
148d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
148e0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 n that invoked t
148f0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
14900 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 llback..** Note
14910 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 that [sqlite3_pr
14920 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 epare_v2()] and
14930 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
14940 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 both modify the
14950 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 ir.** database c
14960 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 onnections for t
14970 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d he meaning of "m
14980 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 odify" in this p
14990 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 aragraph..**.**
149a0 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 When [sqlite3_pr
149b0 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 epare_v2()] is u
149c0 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 sed to prepare a
149d0 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a statement, the.
149e0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 ** statement mig
149f0 68 74 20 62 65 20 72 65 70 72 65 70 61 72 65 64 ht be reprepared
14a00 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 during [sqlite3
14a10 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 _step()] due to
14a20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 a .** schema cha
14a30 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 nge. Hence, the
14a40 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f application sho
14a50 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 uld ensure that
14a60 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 the.** correct a
14a70 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
14a80 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c ck remains in pl
14a90 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b ace during the [
14aa0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e sqlite3_step()].
14ab0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 .**.** Note that
14ac0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
14ad0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
14ae0 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a ked only during.
14af0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
14b00 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 are()] or its va
14b10 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 riants. Authori
14b20 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a zation is not.**
14b30 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e performed durin
14b40 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c g statement eval
14b50 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 uation in [sqlit
14b60 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 e3_step()], unle
14b70 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 ss.** as stated
14b80 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 in the previous
14b90 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 paragraph, sqlit
14ba0 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 e3_step() invoke
14bb0 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 s.** sqlite3_pre
14bc0 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 pare_v2() to rep
14bd0 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 repare a stateme
14be0 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d nt after a schem
14bf0 61 20 63 68 61 6e 67 65 2e 0a 2a 2a 0a 2a 2a 20 a change..**.**
14c00 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
14c10 20 5b 48 31 32 35 30 31 5d 20 5b 48 31 32 35 30 [H12501] [H1250
14c20 32 5d 20 5b 48 31 32 35 30 33 5d 20 5b 48 31 32 2] [H12503] [H12
14c30 35 30 34 5d 20 5b 48 31 32 35 30 35 5d 20 5b 48 504] [H12505] [H
14c40 31 32 35 30 36 5d 20 5b 48 31 32 35 30 37 5d 20 12506] [H12507]
14c50 5b 48 31 32 35 31 30 5d 0a 2a 2a 20 5b 48 31 32 [H12510].** [H12
14c60 35 31 31 5d 20 5b 48 31 32 35 31 32 5d 20 5b 48 511] [H12512] [H
14c70 31 32 35 32 30 5d 20 5b 48 31 32 35 32 31 5d 20 12520] [H12521]
14c80 5b 48 31 32 35 32 32 5d 0a 2a 2f 0a 69 6e 74 20 [H12522].*/.int
14c90 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
14ca0 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 orizer(. sqlite
14cb0 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 3*,. int (*xAut
14cc0 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e h)(void*,int,con
14cd0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 st char*,const c
14ce0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a har*,const char*
14cf0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 ,const char*),.
14d00 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 void *pUserData
14d10 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
14d20 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 REF: Authorizer
14d30 52 65 74 75 72 6e 20 43 6f 64 65 73 20 7b 48 31 Return Codes {H1
14d40 32 35 39 30 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2590} <H12500>.*
14d50 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 *.** The [sqlite
14d60 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
14d70 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 | authorizer ca
14d80 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d llback function]
14d90 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 must.** return
14da0 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f either [SQLITE_O
14db0 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 K] or one of the
14dc0 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 se two constants
14dd0 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 in order.** to
14de0 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 signal SQLite wh
14df0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 ether or not the
14e00 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 action is permi
14e10 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a tted. See the.*
14e20 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 * [sqlite3_set_a
14e30 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 uthorizer | auth
14e40 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 orizer documenta
14e50 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 tion] for additi
14e60 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 onal.** informat
14e70 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ion..*/.#define
14e80 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 SQLITE_DENY 1
14e90 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 /* Abort the S
14ea0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 QL statement wit
14eb0 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 h an error */.#d
14ec0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e efine SQLITE_IGN
14ed0 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 ORE 2 /* Don't
14ee0 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 allow access, b
14ef0 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 ut don't generat
14f00 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f e an error */../
14f10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 *.** CAPI3REF: A
14f20 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e uthorizer Action
14f30 20 43 6f 64 65 73 20 7b 48 31 32 35 35 30 7d 20 Codes {H12550}
14f40 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <H12500>.**.** T
14f50 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f he [sqlite3_set_
14f60 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e authorizer()] in
14f70 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 terface register
14f80 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e s a callback fun
14f90 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 ction.** that is
14fa0 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 invoked to auth
14fb0 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 orize certain SQ
14fc0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 L statement acti
14fd0 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 ons. The.** sec
14fe0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ond parameter to
14ff0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 the callback is
15000 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 an integer code
15010 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a that specifies.
15020 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 ** what action i
15030 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a s being authoriz
15040 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 ed. These are t
15050 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f he integer actio
15060 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 n codes that.**
15070 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
15080 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 allback may be p
15090 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 assed..**.** The
150a0 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 se action code v
150b0 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 alues signify wh
150c0 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 at kind of opera
150d0 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a tion is to be.**
150e0 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 authorized. Th
150f0 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 e 3rd and 4th pa
15100 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 rameters to the
15110 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a authorization.**
15120 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
15130 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d on will be param
15140 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 eters or NULL de
15150 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 pending on which
15160 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 of these.** cod
15170 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68 es is used as th
15180 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
15190 65 72 2e 20 20 54 68 65 20 35 74 68 20 70 61 72 er. The 5th par
151a0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a ameter to the.**
151b0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
151c0 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 back is the name
151d0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
151e0 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 ("main", "temp"
151f0 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 ,.** etc.) if ap
15200 70 6c 69 63 61 62 6c 65 2e 20 20 54 68 65 20 36 plicable. The 6
15210 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
15220 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
15230 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 allback.** is th
15240 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e e name of the in
15250 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 ner-most trigger
15260 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 or view that is
15270 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 responsible for
15280 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 .** the access a
15290 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 ttempt or NULL i
152a0 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 f this access at
152b0 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c tempt is directl
152c0 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 y from.** top-le
152d0 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a vel SQL code..**
152e0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
152f0 3a 0a 2a 2a 20 5b 48 31 32 35 35 31 5d 20 5b 48 :.** [H12551] [H
15300 31 32 35 35 32 5d 20 5b 48 31 32 35 35 33 5d 20 12552] [H12553]
15310 5b 48 31 32 35 35 34 5d 0a 2a 2f 0a 2f 2a 2a 2a [H12554].*/./***
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 2a 2a 20 33 72 64 20 2a 2a 2a ******** 3rd ***
15350 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a ********* 4th **
15360 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 *********/.#defi
15370 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
15380 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 _INDEX
15390 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 1 /* Index Nam
153a0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d e Table Nam
153b0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
153c0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
153d0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 TABLE 2
153e0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
153f0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
15400 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
15410 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 SQLITE_CREATE_T
15420 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 EMP_INDEX 3
15430 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 /* Index Name
15440 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 Table Name
15450 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
15460 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 SQLITE_CREATE_TE
15470 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 MP_TABLE 4
15480 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
15490 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
154a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
154b0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d QLITE_CREATE_TEM
154c0 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 P_TRIGGER 5
154d0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 /* Trigger Name
154e0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
154f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
15500 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 LITE_CREATE_TEMP
15510 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f _VIEW 6 /
15520 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 * View Name
15530 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
15540 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
15550 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 ITE_CREATE_TRIGG
15560 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a ER 7 /*
15570 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 Trigger Name
15580 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
15590 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
155a0 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 TE_CREATE_VIEW
155b0 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 8 /*
155c0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 View Name
155d0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
155e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
155f0 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 E_DELETE
15600 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 9 /* T
15610 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
15620 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
15630 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
15640 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 _DROP_INDEX
15650 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 10 /* In
15660 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 dex Name Ta
15670 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
15680 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
15690 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 DROP_TABLE
156a0 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 11 /* Tab
156b0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
156c0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
156d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
156e0 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 ROP_TEMP_INDEX
156f0 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 12 /* Inde
15700 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c x Name Tabl
15710 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
15720 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
15730 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 OP_TEMP_TABLE
15740 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 13 /* Table
15750 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
15760 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
15770 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
15780 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 P_TEMP_TRIGGER
15790 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 14 /* Trigge
157a0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 r Name Table
157b0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
157c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
157d0 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 _TEMP_VIEW
157e0 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 15 /* View Na
157f0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 me NULL
15800 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
15810 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
15820 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 TRIGGER
15830 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 16 /* Trigger
15840 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 Name Table Na
15850 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
15860 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 ne SQLITE_DROP_V
15870 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 IEW 1
15880 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 7 /* View Name
15890 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
158a0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
158b0 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 e SQLITE_INSERT
158c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 18
158d0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
158e0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
158f0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
15900 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 SQLITE_PRAGMA
15910 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 19
15920 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 /* Pragma Name
15930 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 1st arg or
15940 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 NULL */.#define
15950 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 SQLITE_READ
15960 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20
15970 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
15980 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 Column Name
15990 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
159a0 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 QLITE_SELECT
159b0 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 21
159c0 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 /* NULL
159d0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
159e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
159f0 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e LITE_TRANSACTION
15a00 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 22 /
15a10 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 * Operation
15a20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
15a30 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
15a40 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 ITE_UPDATE
15a50 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 23 /*
15a60 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
15a70 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 Column Name
15a80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
15a90 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 TE_ATTACH
15aa0 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 24 /*
15ab0 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 Filename
15ac0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
15ad0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
15ae0 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 E_DETACH
15af0 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 25 /* D
15b00 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e atabase Name N
15b10 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
15b20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
15b30 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 _ALTER_TABLE
15b40 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 26 /* Da
15b50 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 tabase Name Ta
15b60 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
15b70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
15b80 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 REINDEX
15b90 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 27 /* Ind
15ba0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c ex Name NUL
15bb0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
15bc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
15bd0 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 NALYZE
15be0 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 28 /* Tabl
15bf0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
15c00 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
15c10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
15c20 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 EATE_VTABLE
15c30 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 29 /* Table
15c40 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c Name Modul
15c50 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 e Name */.#d
15c60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
15c70 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 P_VTABLE
15c80 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 30 /* Table
15c90 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 Name Module
15ca0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
15cb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 fine SQLITE_FUNC
15cc0 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 TION
15cd0 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 31 /* NULL
15ce0 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f Functio
15cf0 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 n Name */.#def
15d00 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 ine SQLITE_SAVEP
15d10 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 OINT
15d20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 32 /* Operatio
15d30 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e n Savepoin
15d40 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 t Name */.#defi
15d50 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 ne SQLITE_COPY
15d60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
15d70 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 0 /* No longer
15d80 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 used */../*.**
15d90 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e CAPI3REF: Tracin
15da0 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 g And Profiling
15db0 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 32 32 38 Functions {H1228
15dc0 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 20 45 0} <S60400>.** E
15dd0 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a XPERIMENTAL.**.*
15de0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
15df0 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 register callba
15e00 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 ck functions tha
15e10 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f t can be used fo
15e20 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 r.** tracing and
15e30 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 profiling the e
15e40 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 xecution of SQL
15e50 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a statements..**.*
15e60 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 * The callback f
15e70 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 unction register
15e80 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 ed by sqlite3_tr
15e90 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 ace() is invoked
15ea0 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 at.** various t
15eb0 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c imes when an SQL
15ec0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 statement is be
15ed0 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 ing run by [sqli
15ee0 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 te3_step()]..**
15ef0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 The callback ret
15f00 75 72 6e 73 20 61 20 55 54 46 2d 38 20 72 65 6e urns a UTF-8 ren
15f10 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 53 51 dering of the SQ
15f20 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 L statement text
15f30 0a 2a 2a 20 61 73 20 74 68 65 20 73 74 61 74 65 .** as the state
15f40 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e ment first begin
15f50 73 20 65 78 65 63 75 74 69 6e 67 2e 20 20 41 64 s executing. Ad
15f60 64 69 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 ditional callbac
15f70 6b 73 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 ks occur.** as e
15f80 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 ach triggered su
15f90 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 bprogram is ente
15fa0 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 red. The callba
15fb0 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 cks for triggers
15fc0 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 .** contain a UT
15fd0 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 F-8 SQL comment
15fe0 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 that identifies
15ff0 74 68 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a the trigger..**.
16000 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 ** The callback
16010 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 function registe
16020 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 red by sqlite3_p
16030 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f rofile() is invo
16040 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 ked.** as each S
16050 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e QL statement fin
16060 69 73 68 65 73 2e 20 20 54 68 65 20 70 72 6f 66 ishes. The prof
16070 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e ile callback con
16080 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 tains.** the ori
16090 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 ginal statement
160a0 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 text and an esti
160b0 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f mate of wall-clo
160c0 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f ck time.** of ho
160d0 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 w long that stat
160e0 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 ement took to ru
160f0 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 n..**.** Require
16100 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 38 ments:.** [H1228
16110 31 5d 20 5b 48 31 32 32 38 32 5d 20 5b 48 31 32 1] [H12282] [H12
16120 32 38 33 5d 20 5b 48 31 32 32 38 34 5d 20 5b 48 283] [H12284] [H
16130 31 32 32 38 35 5d 20 5b 48 31 32 32 38 37 5d 20 12285] [H12287]
16140 5b 48 31 32 32 38 38 5d 20 5b 48 31 32 32 38 39 [H12288] [H12289
16150 5d 0a 2a 2a 20 5b 48 31 32 32 39 30 5d 0a 2a 2f ].** [H12290].*/
16160 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 .SQLITE_EXPERIME
16170 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 NTAL void *sqlit
16180 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 e3_trace(sqlite3
16190 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 *, void(*xTrace)
161a0 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 (void*,const cha
161b0 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c r*), void*);.SQL
161c0 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c ITE_EXPERIMENTAL
161d0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 void *sqlite3_p
161e0 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c rofile(sqlite3*,
161f0 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 . void(*xProfi
16200 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 le)(void*,const
16210 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 char*,sqlite3_ui
16220 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a nt64), void*);..
16230 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
16240 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 Query Progress C
16250 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 31 30 allbacks {H12910
16260 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a } <S60400>.**.**
16270 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f This routine co
16280 6e 66 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62 nfigures a callb
16290 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 ack function - t
162a0 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 63 he.** progress c
162b0 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 20 69 allback - that i
162c0 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 s invoked period
162d0 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f ically during lo
162e0 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61 ng.** running ca
162f0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
16300 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 exec()], [sqlite
16310 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 3_step()] and.**
16320 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 [sqlite3_get_ta
16330 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d ble()]. An exam
16340 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 ple use for this
16350 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 .** interface is
16360 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 to keep a GUI u
16370 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 pdated during a
16380 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a large query..**.
16390 2a 2a 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 ** If the progre
163a0 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 ss callback retu
163b0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 rns non-zero, th
163c0 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a e operation is.*
163d0 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 * interrupted.
163e0 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e This feature can
163f0 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c be used to impl
16400 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 ement a.** "Canc
16410 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 el" button on a
16420 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 GUI progress dia
16430 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 log box..**.** T
16440 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 he progress hand
16450 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 ler must not do
16460 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 anything that wi
16470 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 ll modify.** the
16480 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
16490 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 tion that invoke
164a0 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 d the progress h
164b0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 andler..** Note
164c0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 that [sqlite3_pr
164d0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 epare_v2()] and
164e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
164f0 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 both modify the
16500 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 ir.** database c
16510 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 onnections for t
16520 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d he meaning of "m
16530 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 odify" in this p
16540 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 aragraph..**.**
16550 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
16560 20 5b 48 31 32 39 31 31 5d 20 5b 48 31 32 39 31 [H12911] [H1291
16570 32 5d 20 5b 48 31 32 39 31 33 5d 20 5b 48 31 32 2] [H12913] [H12
16580 39 31 34 5d 20 5b 48 31 32 39 31 35 5d 20 5b 48 914] [H12915] [H
16590 31 32 39 31 36 5d 20 5b 48 31 32 39 31 37 5d 20 12916] [H12917]
165a0 5b 48 31 32 39 31 38 5d 0a 2a 2a 0a 2a 2f 0a 76 [H12918].**.*/.v
165b0 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 oid sqlite3_prog
165c0 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c ress_handler(sql
165d0 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 ite3*, int, int(
165e0 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a *)(void*), void*
165f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
16600 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 EF: Opening A Ne
16610 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 w Database Conne
16620 63 74 69 6f 6e 20 7b 48 31 32 37 30 30 7d 20 3c ction {H12700} <
16630 53 34 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S40200>.**.** Th
16640 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 ese routines ope
16650 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 n an SQLite data
16660 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73 65 20 base file whose
16670 6e 61 6d 65 20 69 73 20 67 69 76 65 6e 20 62 79 name is given by
16680 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 the.** filename
16690 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 65 20 66 argument. The f
166a0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 ilename argument
166b0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 is interpreted
166c0 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 as UTF-8 for.**
166d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 sqlite3_open() a
166e0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f nd sqlite3_open_
166f0 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d v2() and as UTF-
16700 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 16 in the native
16710 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 byte.** order f
16720 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 or sqlite3_open1
16730 36 28 29 2e 20 41 20 5b 64 61 74 61 62 61 73 65 6(). A [database
16740 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e connection] han
16750 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a dle is usually.*
16760 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 * returned in *p
16770 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 pDb, even if an
16780 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 error occurs. T
16790 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f he only exceptio
167a0 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 n is that.** if
167b0 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 SQLite is unable
167c0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d to allocate mem
167d0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 ory to hold the
167e0 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 [sqlite3] object
167f0 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c ,.** a NULL will
16800 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f be written into
16810 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f *ppDb instead o
16820 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 f a pointer to t
16830 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 he [sqlite3].**
16840 6f 62 6a 65 63 74 2e 20 49 66 20 74 68 65 20 64 object. If the d
16850 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 atabase is opene
16860 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 d (and/or create
16870 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c d) successfully,
16880 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 then.** [SQLITE
16890 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 _OK] is returned
168a0 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 . Otherwise an
168b0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 [error code] is
168c0 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 0a 2a returned. The.*
168d0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 * [sqlite3_errms
168e0 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 g()] or [sqlite3
168f0 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 _errmsg16()] rou
16900 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 tines can be use
16910 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 d to obtain.** a
16920 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 n English langua
16930 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f ge description o
16940 66 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a f the error..**.
16950 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 65 ** The default e
16960 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 ncoding for the
16970 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 database will be
16980 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c UTF-8 if.** sql
16990 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 ite3_open() or s
169a0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
169b0 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a is called and.*
169c0 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 * UTF-16 in the
169d0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
169e0 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 r if sqlite3_ope
169f0 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a n16() is used..*
16a00 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 *.** Whether or
16a10 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 not an error occ
16a20 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f urs when it is o
16a30 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 pened, resources
16a40 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 .** associated w
16a50 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 ith the [databas
16a60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 e connection] ha
16a70 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 ndle should be r
16a80 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 eleased by.** pa
16a90 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c ssing it to [sql
16aa0 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 ite3_close()] wh
16ab0 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 en it is no long
16ac0 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a er required..**.
16ad0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f ** The sqlite3_o
16ae0 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 pen_v2() interfa
16af0 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 ce works like sq
16b00 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 lite3_open().**
16b10 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 except that it a
16b20 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 ccepts two addit
16b30 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 ional parameters
16b40 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 for additional
16b50 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 control.** over
16b60 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 the new database
16b70 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 connection. Th
16b80 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 e flags paramete
16b90 72 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f r can take one o
16ba0 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 f.** the followi
16bb0 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c ng three values,
16bc0 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 optionally comb
16bd0 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a ined with the .*
16be0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e * [SQLITE_OPEN_N
16bf0 4f 4d 55 54 45 58 5d 20 6f 72 20 5b 53 51 4c 49 OMUTEX] or [SQLI
16c00 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 TE_OPEN_FULLMUTE
16c10 58 5d 20 66 6c 61 67 73 3a 0a 2a 2a 0a 2a 2a 20 X] flags:.**.**
16c20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c <dl>.** <dt>[SQL
16c30 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c ITE_OPEN_READONL
16c40 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 Y]</dt>.** <dd>T
16c50 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
16c60 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e pened in read-on
16c70 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 ly mode. If the
16c80 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e database does n
16c90 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 ot.** already ex
16ca0 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 ist, an error is
16cb0 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a returned.</dd>.
16cc0 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 **.** <dt>[SQLIT
16cd0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 E_OPEN_READWRITE
16ce0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 ]</dt>.** <dd>Th
16cf0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 e database is op
16d00 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 ened for reading
16d10 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 and writing if
16d20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 possible, or rea
16d30 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 ding.** only if
16d40 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 the file is writ
16d50 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 e protected by t
16d60 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 he operating sys
16d70 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a tem. In either.
16d80 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61 ** case the data
16d90 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 base must alread
16da0 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 y exist, otherwi
16db0 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 se an error is r
16dc0 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a eturned.</dd>.**
16dd0 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f .** <dt>[SQLITE_
16de0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 OPEN_READWRITE]
16df0 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 | [SQLITE_OPEN_C
16e00 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c REATE]</dt>.** <
16e10 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 dd>The database
16e20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 is opened for re
16e30 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e ading and writin
16e40 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 g, and is create
16e50 73 20 69 74 20 69 66 0a 2a 2a 20 69 74 20 64 6f s it if.** it do
16e60 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 es not already e
16e70 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 xist. This is th
16e80 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 e behavior that
16e90 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 is always used f
16ea0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 or.** sqlite3_op
16eb0 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 en() and sqlite3
16ec0 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 0a _open16().</dd>.
16ed0 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 ** </dl>.**.** I
16ee0 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 f the 3rd parame
16ef0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f ter to sqlite3_o
16f00 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 pen_v2() is not
16f10 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f one of the.** co
16f20 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e mbinations shown
16f30 20 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20 6f 66 above or one of
16f40 20 74 68 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e the combination
16f50 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 63 6f s shown above co
16f60 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68 20 74 mbined.** with t
16f70 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f he [SQLITE_OPEN_
16f80 4e 4f 4d 55 54 45 58 5d 20 6f 72 20 5b 53 51 4c NOMUTEX] or [SQL
16f90 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 ITE_OPEN_FULLMUT
16fa0 45 58 5d 20 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 EX] flags,.** th
16fb0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 en the behavior
16fc0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a is undefined..**
16fd0 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53 51 4c 49 .** If the [SQLI
16fe0 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d TE_OPEN_NOMUTEX]
16ff0 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 flag is set, th
17000 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
17010 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 connection.** op
17020 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 ens in the multi
17030 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 -thread [threadi
17040 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 ng mode] as long
17050 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 as the single-t
17060 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 hread.** mode ha
17070 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 s not been set a
17080 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f t compile-time o
17090 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 49 r start-time. I
170a0 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 f the.** [SQLITE
170b0 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d _OPEN_FULLMUTEX]
170c0 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 flag is set the
170d0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 n the database c
170e0 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a onnection opens.
170f0 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c ** in the serial
17100 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 ized [threading
17110 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e mode] unless sin
17120 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a gle-thread was.*
17130 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c * previously sel
17140 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 ected at compile
17150 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 -time or start-t
17160 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ime..**.** If th
17170 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a e filename is ":
17180 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 memory:", then a
17190 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 private, tempor
171a0 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 ary in-memory da
171b0 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 tabase.** is cre
171c0 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e ated for the con
171d0 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 nection. This i
171e0 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 n-memory databas
171f0 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 e will vanish wh
17200 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 en.** the databa
17210 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
17220 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 closed. Future
17230 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
17240 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b ite might.** mak
17250 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f e use of additio
17260 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 nal special file
17270 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e names that begin
17280 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 with the ":" ch
17290 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 aracter..** It i
172a0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 s recommended th
172b0 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 at when a databa
172c0 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 se filename actu
172d0 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 ally does begin
172e0 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 with.** a ":" ch
172f0 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 aracter you shou
17300 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69 ld prefix the fi
17310 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 lename with a pa
17320 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a thname such as.*
17330 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 * "./" to avoid
17340 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a ambiguity..**.**
17350 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 If the filename
17360 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 is an empty str
17370 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 ing, then a priv
17380 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a ate, temporary.*
17390 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 * on-disk databa
173a0 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 se will be creat
173b0 65 64 2e 20 20 54 68 69 73 20 70 72 69 76 61 74 ed. This privat
173c0 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 e database will
173d0 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 be.** automatica
173e0 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 lly deleted as s
173f0 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 oon as the datab
17400 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
17410 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 s closed..**.**
17420 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d The fourth param
17430 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
17440 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 open_v2() is the
17450 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 name of the.**
17460 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 [sqlite3_vfs] ob
17470 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 ject that define
17480 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 s the operating
17490 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 system interface
174a0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 that.** the new
174b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
174c0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e tion should use.
174d0 20 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 If the fourth
174e0 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 parameter is.**
174f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 a NULL pointer t
17500 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 hen the default
17510 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 [sqlite3_vfs] ob
17520 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a ject is used..**
17530 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 .** <b>Note to W
17540 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 indows users:</b
17550 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 > The encoding
17560 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c used for the fil
17570 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a ename argument.*
17580 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 * of sqlite3_ope
17590 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f n() and sqlite3_
175a0 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 open_v2() must b
175b0 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 e UTF-8, not wha
175c0 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 tever.** codepag
175d0 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 e is currently d
175e0 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d efined. Filenam
175f0 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e es containing in
17600 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 ternational.** c
17610 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 haracters must b
17620 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 e converted to U
17630 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 TF-8 prior to pa
17640 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a ssing them into.
17650 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 ** sqlite3_open(
17660 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 ) or sqlite3_ope
17670 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 52 65 n_v2()..**.** Re
17680 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
17690 48 31 32 37 30 31 5d 20 5b 48 31 32 37 30 32 5d H12701] [H12702]
176a0 20 5b 48 31 32 37 30 33 5d 20 5b 48 31 32 37 30 [H12703] [H1270
176b0 34 5d 20 5b 48 31 32 37 30 36 5d 20 5b 48 31 32 4] [H12706] [H12
176c0 37 30 37 5d 20 5b 48 31 32 37 30 39 5d 20 5b 48 707] [H12709] [H
176d0 31 32 37 31 31 5d 0a 2a 2a 20 5b 48 31 32 37 31 12711].** [H1271
176e0 32 5d 20 5b 48 31 32 37 31 33 5d 20 5b 48 31 32 2] [H12713] [H12
176f0 37 31 34 5d 20 5b 48 31 32 37 31 37 5d 20 5b 48 714] [H12717] [H
17700 31 32 37 31 39 5d 20 5b 48 31 32 37 32 31 5d 20 12719] [H12721]
17710 5b 48 31 32 37 32 33 5d 0a 2a 2f 0a 69 6e 74 20 [H12723].*/.int
17720 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 sqlite3_open(.
17730 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 const char *file
17740 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 name, /* Datab
17750 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 ase filename (UT
17760 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 F-8) */. sqlite
17770 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 3 **ppDb
17780 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 /* OUT: SQLite
17790 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b db handle */.);
177a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 .int sqlite3_ope
177b0 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 n16(. const voi
177c0 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f d *filename, /
177d0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e * Database filen
177e0 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a ame (UTF-16) */.
177f0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 sqlite3 **ppDb
17800 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 /* OUT
17810 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 : SQLite db hand
17820 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c le */.);.int sql
17830 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 ite3_open_v2(.
17840 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 const char *file
17850 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 name, /* Datab
17860 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 ase filename (UT
17870 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 F-8) */. sqlite
17880 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 3 **ppDb,
17890 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 /* OUT: SQLite
178a0 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 db handle */.
178b0 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 int flags,
178c0 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 /* Flags
178d0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
178e0 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a *zVfs /*
178f0 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 Name of VFS mod
17900 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b ule to use */.);
17910 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
17920 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e : Error Codes An
17930 64 20 4d 65 73 73 61 67 65 73 20 7b 48 31 32 38 d Messages {H128
17940 30 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 0a 00} <S60200>.**.
17950 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 ** The sqlite3_e
17960 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 rrcode() interfa
17970 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e ce returns the n
17980 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 umeric [result c
17990 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 ode] or.** [exte
179a0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
179b0 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 ] for the most r
179c0 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c ecent failed sql
179d0 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a ite3_* API call.
179e0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ** associated wi
179f0 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 th a [database c
17a00 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 onnection]. If a
17a10 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 prior API call
17a20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 failed.** but th
17a30 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 e most recent AP
17a40 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 I call succeeded
17a50 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c , the return val
17a60 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 ue from.** sqlit
17a70 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 e3_errcode() is
17a80 75 6e 64 65 66 69 6e 65 64 2e 20 20 54 68 65 20 undefined. The
17a90 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
17aa0 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e _errcode().** in
17ab0 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73 terface is the s
17ac0 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20 ame except that
17ad0 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e it always return
17ae0 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e s the .** [exten
17af0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d ded result code]
17b00 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e even when exten
17b10 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
17b20 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 are.** disabled
17b30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
17b40 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 te3_errmsg() and
17b50 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 sqlite3_errmsg1
17b60 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 6() return Engli
17b70 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 sh-language.** t
17b80 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 ext that describ
17b90 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 es the error, as
17ba0 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 either UTF-8 or
17bb0 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 UTF-16 respecti
17bc0 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 vely..** Memory
17bd0 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f to hold the erro
17be0 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 r message string
17bf0 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 is managed inte
17c00 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 rnally..** The a
17c10 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 pplication does
17c20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 not need to worr
17c30 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 y about freeing
17c40 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 the result..** H
17c50 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f owever, the erro
17c60 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 r string might b
17c70 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 e overwritten or
17c80 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a deallocated by.
17c90 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 ** subsequent ca
17ca0 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c lls to other SQL
17cb0 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 ite interface fu
17cc0 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 57 nctions..**.** W
17cd0 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a hen the serializ
17ce0 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ed [threading mo
17cf0 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 de] is in use, i
17d00 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a t might be the.*
17d10 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 * case that a se
17d20 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 cond error occur
17d30 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 s on a separate
17d40 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 thread in betwee
17d50 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 n.** the time of
17d60 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 the first error
17d70 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f and the call to
17d80 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 these interface
17d90 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 s..** When that
17da0 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 happens, the sec
17db0 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 ond error will b
17dc0 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 e reported since
17dd0 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 these.** interf
17de0 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f aces always repo
17df0 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 rt the most rece
17e00 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 nt result. To a
17e10 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 void.** this, ea
17e20 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 ch thread can ob
17e30 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 tain exclusive u
17e40 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 se of the [datab
17e50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
17e60 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 D.** by invoking
17e70 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
17e80 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f enter]([sqlite3_
17e90 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 db_mutex](D)) be
17ea0 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a fore beginning.*
17eb0 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 * to use D and i
17ec0 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 nvoking [sqlite3
17ed0 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 _mutex_leave]([s
17ee0 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d qlite3_db_mutex]
17ef0 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c (D)) after.** al
17f00 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 l calls to the i
17f10 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 nterfaces listed
17f20 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 here are comple
17f30 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e ted..**.** If an
17f40 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 interface fails
17f50 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 with SQLITE_MIS
17f60 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 USE, that means
17f70 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a the interface.**
17f80 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 was invoked inc
17f90 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 orrectly by the
17fa0 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e application. In
17fb0 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a that case, the.
17fc0 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e ** error code an
17fd0 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 d message may or
17fe0 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e may not be set.
17ff0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
18000 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 38 30 31 5d nts:.** [H12801]
18010 20 5b 48 31 32 38 30 32 5d 20 5b 48 31 32 38 30 [H12802] [H1280
18020 33 5d 20 5b 48 31 32 38 30 37 5d 20 5b 48 31 32 3] [H12807] [H12
18030 38 30 38 5d 20 5b 48 31 32 38 30 39 5d 0a 2a 2f 808] [H12809].*/
18040 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 .int sqlite3_err
18050 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 code(sqlite3 *db
18060 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 );.int sqlite3_e
18070 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 xtended_errcode(
18080 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f sqlite3 *db);.co
18090 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
180a0 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 3_errmsg(sqlite3
180b0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a *);.const void *
180c0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 sqlite3_errmsg16
180d0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
180e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c ** CAPI3REF: SQL
180f0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 Statement Objec
18100 74 20 7b 48 31 33 30 30 30 7d 20 3c 48 31 33 30 t {H13000} <H130
18110 31 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 10>.** KEYWORDS:
18120 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 {prepared state
18130 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 ment} {prepared
18140 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a statements}.**.*
18150 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 * An instance of
18160 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 this object rep
18170 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 resents a single
18180 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a SQL statement..
18190 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 ** This object i
181a0 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 s variously know
181b0 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64 n as a "prepared
181c0 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 statement" or a
181d0 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 .** "compiled SQ
181e0 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 L statement" or
181f0 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 simply as a "sta
18200 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 tement"..**.** T
18210 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 he life of a sta
18220 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f tement object go
18230 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b es something lik
18240 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f e this:.**.** <o
18250 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 l>.** <li> Creat
18260 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 e the object usi
18270 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ng [sqlite3_prep
18280 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 are_v2()] or a r
18290 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 elated.** f
182a0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e unction..** <li>
182b0 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 Bind values to
182c0 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 [host parameters
182d0 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 ] using the sqli
182e0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 te3_bind_*().**
182f0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e interfaces.
18300 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 .** <li> Run the
18310 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 SQL by calling
18320 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
18330 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d one or more tim
18340 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 es..** <li> Rese
18350 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 t the statement
18360 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 using [sqlite3_r
18370 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 eset()] then go
18380 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 back.** to
18390 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 step 2. Do this
183a0 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 zero or more ti
183b0 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 mes..** <li> Des
183c0 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 troy the object
183d0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 using [sqlite3_f
183e0 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c inalize()]..** <
183f0 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 /ol>.**.** Refer
18400 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f to documentatio
18410 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 n on individual
18420 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f methods above fo
18430 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 r additional.**
18440 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a information..*/.
18450 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
18460 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 qlite3_stmt sqli
18470 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a te3_stmt;../*.**
18480 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 CAPI3REF: Run-t
18490 69 6d 65 20 4c 69 6d 69 74 73 20 7b 48 31 32 37 ime Limits {H127
184a0 36 30 7d 20 3c 53 32 30 36 30 30 3e 0a 2a 2a 0a 60} <S20600>.**.
184b0 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 ** This interfac
184c0 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a e allows the siz
184d0 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e e of various con
184e0 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 structs to be li
184f0 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f mited.** on a co
18500 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e nnection by conn
18510 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 ection basis. T
18520 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
18530 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 er is the.** [da
18540 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
18550 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 n] whose limit i
18560 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 s to be set or q
18570 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 ueried. The.**
18580 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
18590 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b is one of the [
185a0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 limit categories
185b0 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a ] that define a.
185c0 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 ** class of cons
185d0 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a tructs to be siz
185e0 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 e limited. The
185f0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
18600 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 is the.** new li
18610 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e mit for that con
18620 73 74 72 75 63 74 2e 20 20 54 68 65 20 66 75 6e struct. The fun
18630 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 ction returns th
18640 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a 2a 2a 0a e old limit..**.
18650 2a 2a 20 49 66 20 74 68 65 20 6e 65 77 20 6c 69 ** If the new li
18660 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 mit is a negativ
18670 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 e number, the li
18680 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 mit is unchanged
18690 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6c 69 6d ..** For the lim
186a0 69 74 20 63 61 74 65 67 6f 72 79 20 6f 66 20 53 it category of S
186b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59 5a 20 QLITE_LIMIT_XYZ
186c0 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b there is a .** [
186d0 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 limits | hard up
186e0 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 per bound].** se
186f0 74 20 62 79 20 61 20 63 6f 6d 70 69 6c 65 2d 74 t by a compile-t
18700 69 6d 65 20 43 20 70 72 65 70 72 6f 63 65 73 73 ime C preprocess
18710 6f 72 20 6d 61 63 72 6f 20 6e 61 6d 65 64 20 0a or macro named .
18720 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c ** [limits | SQL
18730 49 54 45 5f 4d 41 58 5f 58 59 5a 5d 2e 0a 2a 2a ITE_MAX_XYZ]..**
18740 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 (The "_LIMIT_"
18750 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 in the name is c
18760 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f hanged to "_MAX_
18770 22 2e 29 0a 2a 2a 20 41 74 74 65 6d 70 74 73 20 ".).** Attempts
18780 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 to increase a li
18790 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 mit above its ha
187a0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 rd upper bound a
187b0 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 re.** silently t
187c0 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 runcated to the
187d0 68 61 72 64 20 75 70 70 65 72 20 6c 69 6d 69 74 hard upper limit
187e0 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 20 74 69 6d 65 ..**.** Run time
187f0 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 limits are inte
18800 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 nded for use in
18810 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 applications tha
18820 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 t manage.** both
18830 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 their own inter
18840 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 nal database and
18850 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 also databases
18860 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c that are control
18870 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 led.** by untrus
18880 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 ted external sou
18890 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c rces. An exampl
188a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 e application mi
188b0 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 ght be a.** web
188c0 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 browser that has
188d0 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 its own databas
188e0 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 es for storing h
188f0 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 istory and.** se
18900 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73 parate databases
18910 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a controlled by J
18920 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 avaScript applic
18930 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 ations downloade
18940 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 d.** off the Int
18950 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 ernet. The inte
18960 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 rnal databases c
18970 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a an be given the.
18980 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c ** large, defaul
18990 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 t limits. Datab
189a0 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 ases managed by
189b0 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 external sources
189c0 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e can.** be given
189d0 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 much smaller li
189e0 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f mits designed to
189f0 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 prevent a denia
18a00 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 l of service.**
18a10 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 attack. Develop
18a20 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 ers might also w
18a30 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b ant to use the [
18a40 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
18a50 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 orizer()].** int
18a60 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 erface to furthe
18a70 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 r control untrus
18a80 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 ted SQL. The si
18a90 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 ze of the databa
18aa0 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 se.** created by
18ab0 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 an untrusted sc
18ac0 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 ript can be cont
18ad0 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a ained using the.
18ae0 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 ** [max_page_cou
18af0 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a nt] [PRAGMA]..**
18b00 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 .** New run-time
18b10 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 limit categorie
18b20 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 s may be added i
18b30 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
18b40 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 s..**.** Require
18b50 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 37 36 ments:.** [H1276
18b60 32 5d 20 5b 48 31 32 37 36 36 5d 20 5b 48 31 32 2] [H12766] [H12
18b70 37 36 39 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 769].*/.int sqli
18b80 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 te3_limit(sqlite
18b90 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 3*, int id, int
18ba0 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 newVal);../*.**
18bb0 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 CAPI3REF: Run-Ti
18bc0 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 me Limit Categor
18bd0 69 65 73 20 7b 48 31 32 37 39 30 7d 20 3c 48 31 ies {H12790} <H1
18be0 32 37 36 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 2760>.** KEYWORD
18bf0 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f S: {limit catego
18c00 72 79 7d 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 ry} {limit categ
18c10 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 ories}.**.** The
18c20 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 se constants def
18c30 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 ine various perf
18c40 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a ormance limits.*
18c50 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f * that can be lo
18c60 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d wered at run-tim
18c70 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 e using [sqlite3
18c80 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 _limit()]..** Th
18c90 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 e synopsis of th
18ca0 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 e meanings of th
18cb0 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 e various limits
18cc0 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e is shown below.
18cd0 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 .** Additional i
18ce0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 nformation is av
18cf0 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 ailable at [limi
18d00 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 ts | Limits in S
18d10 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 QLite]..**.** <d
18d20 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 l>.** <dt>SQLITE
18d30 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 _LIMIT_LENGTH</d
18d40 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
18d50 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e ximum size of an
18d60 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 y string or BLOB
18d70 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2e 3c 64 or table row.<d
18d80 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
18d90 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 ITE_LIMIT_SQL_LE
18da0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 NGTH</dt>.** <dd
18db0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e >The maximum len
18dc0 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 gth of an SQL st
18dd0 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a atement.</dd>.**
18de0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c .** <dt>SQLITE_L
18df0 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e IMIT_COLUMN</dt>
18e00 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
18e10 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f mum number of co
18e20 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 lumns in a table
18e30 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 definition or i
18e40 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 n the.** result
18e50 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 set of a [SELECT
18e60 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d ] or the maximum
18e70 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
18e80 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a ns in an index.*
18e90 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 * or in an ORDER
18ea0 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 BY or GROUP BY
18eb0 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a clause.</dd>.**.
18ec0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ** <dt>SQLITE_LI
18ed0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f MIT_EXPR_DEPTH</
18ee0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
18ef0 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 aximum depth of
18f00 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f the parse tree o
18f10 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e n any expression
18f20 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
18f30 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f >SQLITE_LIMIT_CO
18f40 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 MPOUND_SELECT</d
18f50 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
18f60 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
18f70 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f terms in a compo
18f80 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 und SELECT state
18f90 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ment.</dd>.**.**
18fa0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 <dt>SQLITE_LIMI
18fb0 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a T_VDBE_OP</dt>.*
18fc0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
18fd0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 m number of inst
18fe0 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 ructions in a vi
18ff0 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 rtual machine pr
19000 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f ogram.** used to
19010 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 implement an SQ
19020 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 L statement.</dd
19030 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
19040 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f TE_LIMIT_FUNCTIO
19050 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 N_ARG</dt>.** <d
19060 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 d>The maximum nu
19070 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 mber of argument
19080 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e s on a function.
19090 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
190a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 SQLITE_LIMIT_ATT
190b0 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ACHED</dt>.** <d
190c0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 d>The maximum nu
190d0 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 mber of [ATTACH
190e0 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 | attached datab
190f0 61 73 65 73 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a ases].</dd>.**.*
19100 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d * <dt>SQLITE_LIM
19110 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f IT_LIKE_PATTERN_
19120 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c LENGTH</dt>.** <
19130 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c dd>The maximum l
19140 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 ength of the pat
19150 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f tern argument to
19160 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a the [LIKE] or.*
19170 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f * [GLOB] operato
19180 72 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c rs.</dd>.**.** <
19190 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
191a0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c VARIABLE_NUMBER<
191b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
191c0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
191d0 66 20 76 61 72 69 61 62 6c 65 73 20 69 6e 20 61 f variables in a
191e0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 n SQL statement
191f0 74 68 61 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62 that can.** be b
19200 6f 75 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f ound.</dd>.** </
19210 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 dl>.*/.#define S
19220 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 QLITE_LIMIT_LENG
19230 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TH
19240 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 0.#define
19250 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c SQLITE_LIMIT_SQL
19260 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 _LENGTH
19270 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 1.#define
19280 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f SQLITE_LIMIT_CO
19290 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 LUMN
192a0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 2.#defin
192b0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 e SQLITE_LIMIT_E
192c0 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 XPR_DEPTH
192d0 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 3.#defi
192e0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
192f0 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 COMPOUND_SELECT
19300 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 4.#def
19310 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
19320 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 _VDBE_OP
19330 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 5.#de
19340 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
19350 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 T_FUNCTION_ARG
19360 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 6.#d
19370 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
19380 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 IT_ATTACHED
19390 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 7.#
193a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
193b0 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e MIT_LIKE_PATTERN
193c0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a _LENGTH 8.
193d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
193e0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 IMIT_VARIABLE_NU
193f0 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 MBER 9
19400 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
19410 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 : Compiling An S
19420 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 QL Statement {H1
19430 33 30 31 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 3010} <S10000>.*
19440 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c * KEYWORDS: {SQL
19450 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 statement compi
19460 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 ler}.**.** To ex
19470 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 ecute an SQL que
19480 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 ry, it must firs
19490 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e t be compiled in
194a0 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a to a byte-code.*
194b0 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 * program using
194c0 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 one of these rou
194d0 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 tines..**.** The
194e0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c first argument,
194f0 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 "db", is a [dat
19500 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
19510 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 ] obtained from
19520 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 a.** prior succe
19530 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 ssful call to [s
19540 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 qlite3_open()],
19550 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
19560 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 ()] or.** [sqlit
19570 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 e3_open16()]. T
19580 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
19590 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 ection must not
195a0 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 have been closed
195b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f ..**.** The seco
195c0 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 nd argument, "zS
195d0 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 ql", is the stat
195e0 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 ement to be comp
195f0 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a iled, encoded.**
19600 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 as either UTF-8
19610 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 or UTF-16. The
19620 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
19630 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 () and sqlite3_p
19640 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 repare_v2().** i
19650 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54 nterfaces use UT
19660 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 F-8, and sqlite3
19670 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 _prepare16() and
19680 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
19690 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 16_v2().** use U
196a0 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 TF-16..**.** If
196b0 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 the nByte argume
196c0 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 nt is less than
196d0 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 zero, then zSql
196e0 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 is read up to th
196f0 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 e.** first zero
19700 74 65 72 6d 69 6e 61 74 6f 72 2e 20 49 66 20 6e terminator. If n
19710 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 Byte is non-nega
19720 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 tive, then it is
19730 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 the maximum.**
19740 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 number of bytes
19750 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e read from zSql.
19760 20 20 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 When nByte is
19770 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 non-negative, th
19780 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 e.** zSql string
19790 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 ends at either
197a0 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 the first '\000'
197b0 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 or '\u0000' cha
197c0 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 racter or.** the
197d0 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 nByte-th byte,
197e0 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 whichever comes
197f0 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 first. If the ca
19800 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 ller knows.** th
19810 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 at the supplied
19820 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 string is nul-te
19830 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 rminated, then t
19840 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a here is a small.
19850 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 ** performance a
19860 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 dvantage to be g
19870 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 ained by passing
19880 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 an nByte parame
19890 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 ter that.** is e
198a0 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 qual to the numb
198b0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
198c0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 he input string
198d0 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e <i>including</i>
198e0 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d .** the nul-term
198f0 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a inator bytes..**
19900 0a 2a 2a 20 49 66 20 70 7a 54 61 69 6c 20 69 73 .** If pzTail is
19910 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a not NULL then *
19920 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 pzTail is made t
19930 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 o point to the f
19940 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 irst byte.** pas
19950 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 t the end of the
19960 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 first SQL state
19970 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 ment in zSql. T
19980 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e hese routines on
19990 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 ly.** compile th
199a0 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e e first statemen
199b0 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 t in zSql, so *p
199c0 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f zTail is left po
199d0 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 inting to.** wha
199e0 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 t remains uncomp
199f0 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 iled..**.** *ppS
19a00 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e tmt is left poin
19a10 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c ting to a compil
19a20 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ed [prepared sta
19a30 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e tement] that can
19a40 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 be.** executed
19a50 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 using [sqlite3_s
19a60 74 65 70 28 29 5d 2e 20 20 49 66 20 74 68 65 72 tep()]. If ther
19a70 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a e is an error, *
19a80 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a ppStmt is set.**
19a90 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74 68 to NULL. If th
19aa0 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e e input text con
19ab0 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 tains no SQL (if
19ac0 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e the input is an
19ad0 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 empty.** string
19ae0 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 or a comment) t
19af0 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 hen *ppStmt is s
19b00 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 et to NULL..** T
19b10 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 he calling proce
19b20 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 dure is responsi
19b30 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 ble for deleting
19b40 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a the compiled.**
19b50 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 SQL statement u
19b60 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 sing [sqlite3_fi
19b70 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 nalize()] after
19b80 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 it has finished
19b90 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 with it..** ppSt
19ba0 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 mt may not be NU
19bb0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 LL..**.** On suc
19bc0 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b cess, [SQLITE_OK
19bd0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2c 20 6f ] is returned, o
19be0 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 therwise an [err
19bf0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 or code] is retu
19c00 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 rned..**.** The
19c10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
19c20 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 v2() and sqlite3
19c30 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 _prepare16_v2()
19c40 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a interfaces are.*
19c50 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f * recommended fo
19c60 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 r all new progra
19c70 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 ms. The two olde
19c80 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 r interfaces are
19c90 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 retained.** for
19ca0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 backwards compa
19cb0 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 tibility, but th
19cc0 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f eir use is disco
19cd0 75 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 uraged..** In th
19ce0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 e "v2" interface
19cf0 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 s, the prepared
19d00 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 statement.** tha
19d10 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 t is returned (t
19d20 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 he [sqlite3_stmt
19d30 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 ] object) contai
19d40 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 ns a copy of the
19d50 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c .** original SQL
19d60 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 text. This caus
19d70 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f es the [sqlite3_
19d80 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 step()] interfac
19d90 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 e to.** behave a
19da0 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 differently in
19db0 74 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 two ways:.**.**
19dc0 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 <ol>.** <li>.**
19dd0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 If the database
19de0 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 schema changes,
19df0 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 instead of retur
19e00 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 ning [SQLITE_SCH
19e10 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c EMA] as it.** al
19e20 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c ways used to do,
19e30 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
19e40 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 ] will automatic
19e50 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 ally recompile t
19e60 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d he SQL.** statem
19e70 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 ent and try to r
19e80 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 49 66 un it again. If
19e90 20 74 68 65 20 73 63 68 65 6d 61 20 68 61 73 20 the schema has
19ea0 63 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 changed in.** a
19eb0 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20 74 way that makes t
19ec0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 he statement no
19ed0 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 longer valid, [s
19ee0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 qlite3_step()] w
19ef0 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 ill still.** ret
19f00 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 urn [SQLITE_SCHE
19f10 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 MA]. But unlike
19f20 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 the legacy beha
19f30 76 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 vior, [SQLITE_SC
19f40 48 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 HEMA] is.** now
19f50 61 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 a fatal error.
19f60 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 Calling [sqlite3
19f70 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 _prepare_v2()] a
19f80 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 gain will not ma
19f90 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 ke the.** error
19fa0 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 go away. Note:
19fb0 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 use [sqlite3_err
19fc0 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 msg()] to find t
19fd0 68 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 he text.** of th
19fe0 65 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72 20 e parsing error
19ff0 74 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 that results in
1a000 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d an [SQLITE_SCHEM
1a010 41 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f A] return..** </
1a020 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a li>.**.** <li>.*
1a030 2a 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 * When an error
1a040 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 occurs, [sqlite3
1a050 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 _step()] will re
1a060 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 turn one of the
1a070 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 detailed.** [err
1a080 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 or codes] or [ex
1a090 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 tended error cod
1a0a0 65 73 5d 2e 20 20 54 68 65 20 6c 65 67 61 63 79 es]. The legacy
1a0b0 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 behavior was th
1a0c0 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 at.** [sqlite3_s
1a0d0 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c tep()] would onl
1a0e0 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 y return a gener
1a0f0 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 ic [SQLITE_ERROR
1a100 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a ] result code.**
1a110 20 61 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20 68 and you would h
1a120 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 ave to make a se
1a130 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 cond call to [sq
1a140 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 69 lite3_reset()] i
1a150 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 66 69 n order.** to fi
1a160 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e nd the underlyin
1a170 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 g cause of the p
1a180 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 roblem. With the
1a190 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a "v2" prepare.**
1a1a0 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 interfaces, the
1a1b0 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 underlying reas
1a1c0 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 on for the error
1a1d0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d is returned imm
1a1e0 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c ediately..** </l
1a1f0 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a i>.** </ol>.**.*
1a200 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
1a210 2a 2a 20 5b 48 31 33 30 31 31 5d 20 5b 48 31 33 ** [H13011] [H13
1a220 30 31 32 5d 20 5b 48 31 33 30 31 33 5d 20 5b 48 012] [H13013] [H
1a230 31 33 30 31 34 5d 20 5b 48 31 33 30 31 35 5d 20 13014] [H13015]
1a240 5b 48 31 33 30 31 36 5d 20 5b 48 31 33 30 31 39 [H13016] [H13019
1a250 5d 20 5b 48 31 33 30 32 31 5d 0a 2a 2a 0a 2a 2f ] [H13021].**.*/
1a260 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 .int sqlite3_pre
1a270 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 pare(. sqlite3
1a280 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
1a290 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 /* Database hand
1a2a0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 le */. const ch
1a2b0 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 ar *zSql,
1a2c0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 /* SQL statement
1a2d0 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 , UTF-8 encoded
1a2e0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 */. int nByte,
1a2f0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
1a300 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f Maximum length o
1a310 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e f zSql in bytes.
1a320 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 */. sqlite3_st
1a330 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a mt **ppStmt, /*
1a340 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 OUT: Statement
1a350 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
1a360 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 t char **pzTail
1a370 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e /* OUT: Poin
1a380 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f ter to unused po
1a390 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f rtion of zSql */
1a3a0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .);.int sqlite3_
1a3b0 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 prepare_v2(. sq
1a3c0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
1a3d0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 /* Databas
1a3e0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f e handle */. co
1a3f0 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 nst char *zSql,
1a400 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 /* SQL sta
1a410 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e tement, UTF-8 en
1a420 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e coded */. int n
1a430 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 Byte,
1a440 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 /* Maximum le
1a450 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 ngth of zSql in
1a460 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 bytes. */. sqli
1a470 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d te3_stmt **ppStm
1a480 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 t, /* OUT: Stat
1a490 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a ement handle */.
1a4a0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 const char **p
1a4b0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 zTail /* OUT
1a4c0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 : Pointer to unu
1a4d0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a sed portion of z
1a4e0 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 Sql */.);.int sq
1a4f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
1a500 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
1a510 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 /* Da
1a520 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f tabase handle */
1a530 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a . const void *z
1a540 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 Sql, /* SQ
1a550 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 L statement, UTF
1a560 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 -16 encoded */.
1a570 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 int nByte,
1a580 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 /* Maxi
1a590 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 mum length of zS
1a5a0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a ql in bytes. */.
1a5b0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a sqlite3_stmt *
1a5c0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 *ppStmt, /* OUT
1a5d0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 : Statement hand
1a5e0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f le */. const vo
1a5f0 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 id **pzTail
1a600 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 /* OUT: Pointer
1a610 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f to unused portio
1a620 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a n of zSql */.);.
1a630 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 int sqlite3_prep
1a640 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 are16_v2(. sqli
1a650 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
1a660 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
1a670 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
1a680 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 t void *zSql,
1a690 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 /* SQL state
1a6a0 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 ment, UTF-16 enc
1a6b0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 oded */. int nB
1a6c0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 yte,
1a6d0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e /* Maximum len
1a6e0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 gth of zSql in b
1a6f0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 ytes. */. sqlit
1a700 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 e3_stmt **ppStmt
1a710 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 , /* OUT: State
1a720 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 ment handle */.
1a730 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a const void **pz
1a740 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a Tail /* OUT:
1a750 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 Pointer to unus
1a760 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 ed portion of zS
1a770 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ql */.);../*.**
1a780 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 CAPI3REF: Retrie
1a790 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 ving Statement S
1a7a0 51 4c 20 7b 48 31 33 31 30 30 7d 20 3c 48 31 33 QL {H13100} <H13
1a7b0 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 000>.**.** This
1a7c0 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 interface can be
1a7d0 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 used to retriev
1a7e0 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f e a saved copy o
1a7f0 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a f the original.*
1a800 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 * SQL text used
1a810 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 to create a [pre
1a820 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
1a830 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 if that stateme
1a840 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c nt was.** compil
1a850 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 ed using either
1a860 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1a870 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 _v2()] or [sqlit
1a880 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
1a890 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 )]..**.** Requir
1a8a0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 31 ements:.** [H131
1a8b0 30 31 5d 20 5b 48 31 33 31 30 32 5d 20 5b 48 31 01] [H13102] [H1
1a8c0 33 31 30 33 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 3103].*/.const c
1a8d0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c har *sqlite3_sql
1a8e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 (sqlite3_stmt *p
1a8f0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Stmt);../*.** CA
1a900 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 PI3REF: Dynamica
1a910 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 lly Typed Value
1a920 4f 62 6a 65 63 74 20 7b 48 31 35 30 30 30 7d 20 Object {H15000}
1a930 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 <S20200>.** KEYW
1a940 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 ORDS: {protected
1a950 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 sqlite3_value}
1a960 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c {unprotected sql
1a970 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a ite3_value}.**.*
1a980 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 * SQLite uses th
1a990 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 e sqlite3_value
1a9a0 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 object to repres
1a9b0 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a ent all values.*
1a9c0 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 * that can be st
1a9d0 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 ored in a databa
1a9e0 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 se table. SQLite
1a9f0 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 uses dynamic ty
1aa00 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 ping.** for the
1aa10 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 values it stores
1aa20 2e 20 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 . Values stored
1aa30 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 in sqlite3_value
1aa40 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 objects.** can
1aa50 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f be integers, flo
1aa60 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 ating point valu
1aa70 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f es, strings, BLO
1aa80 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a Bs, or NULL..**.
1aa90 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 ** An sqlite3_va
1aaa0 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 lue object may b
1aab0 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 e either "protec
1aac0 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 ted" or "unprote
1aad0 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 cted"..** Some i
1aae0 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 nterfaces requir
1aaf0 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 e a protected sq
1ab00 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 lite3_value. Ot
1ab10 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a her interfaces.*
1ab20 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 * will accept ei
1ab30 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 ther a protected
1ab40 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 or an unprotect
1ab50 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
1ab60 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 ..** Every inter
1ab70 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74 face that accept
1ab80 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 s sqlite3_value
1ab90 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 arguments specif
1aba0 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f ies.** whether o
1abb0 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 r not it require
1abc0 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 s a protected sq
1abd0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a lite3_value..**.
1abe0 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 ** The terms "pr
1abf0 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e otected" and "un
1ac00 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 protected" refer
1ac10 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e to whether or n
1ac20 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 ot.** a mutex is
1ac30 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e held. A intern
1ac40 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 al mutex is held
1ac50 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 for a protected
1ac60 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 .** sqlite3_valu
1ac70 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 e object but no
1ac80 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f mutex is held fo
1ac90 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 r an unprotected
1aca0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 .** sqlite3_valu
1acb0 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 e object. If SQ
1acc0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
1acd0 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 to be single-th
1ace0 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 readed.** (with
1acf0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
1ad00 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b FE=0] and with [
1ad10 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 sqlite3_threadsa
1ad20 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 fe()] returning
1ad30 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 0).** or if SQLi
1ad40 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 te is run in one
1ad50 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 of reduced mute
1ad60 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c x modes .** [SQL
1ad70 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c ITE_CONFIG_SINGL
1ad80 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c ETHREAD] or [SQL
1ad90 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 ITE_CONFIG_MULTI
1ada0 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 THREAD].** then
1adb0 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 there is no dist
1adc0 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 inction between
1add0 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e protected and un
1ade0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c protected.** sql
1adf0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
1ae00 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 ts and they can
1ae10 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 be used intercha
1ae20 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 ngeably. Howeve
1ae30 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 r,.** for maximu
1ae40 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 m code portabili
1ae50 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 ty it is recomme
1ae60 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 nded that applic
1ae70 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 ations.** still
1ae80 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 make the distinc
1ae90 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 62 65 74 tion between bet
1aea0 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 ween protected a
1aeb0 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a nd unprotected.*
1aec0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 * sqlite3_value
1aed0 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 objects even whe
1aee0 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 n not strictly r
1aef0 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 equired..**.** T
1af00 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 he sqlite3_value
1af10 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 objects that ar
1af20 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 e passed as para
1af30 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a meters into the.
1af40 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
1af50 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f n of [applicatio
1af60 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 n-defined SQL fu
1af70 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f nctions] are pro
1af80 74 65 63 74 65 64 2e 0a 2a 2a 20 54 68 65 20 73 tected..** The s
1af90 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
1afa0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a ect returned by.
1afb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ** [sqlite3_colu
1afc0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 mn_value()] is u
1afd0 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 nprotected..** U
1afe0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
1aff0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
1b000 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 may only be use
1b010 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 d with.** [sqlit
1b020 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 e3_result_value(
1b030 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
1b040 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a bind_value()]..*
1b050 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 * The [sqlite3_v
1b060 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 alue_blob | sqli
1b070 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 te3_value_type()
1b080 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 ] family of.** i
1b090 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 nterfaces requir
1b0a0 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 e protected sqli
1b0b0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
1b0c0 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 s..*/.typedef st
1b0d0 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 ruct Mem sqlite3
1b0e0 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 _value;../*.** C
1b0f0 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e API3REF: SQL Fun
1b100 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 ction Context Ob
1b110 6a 65 63 74 20 7b 48 31 36 30 30 31 7d 20 3c 53 ject {H16001} <S
1b120 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20200>.**.** The
1b130 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 context in whic
1b140 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f h an SQL functio
1b150 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74 n executes is st
1b160 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 ored in an.** sq
1b170 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 lite3_context ob
1b180 6a 65 63 74 2e 20 20 41 20 70 6f 69 6e 74 65 72 ject. A pointer
1b190 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 to an sqlite3_c
1b1a0 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a ontext object.**
1b1b0 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 is always first
1b1c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 parameter to [a
1b1d0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
1b1e0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 ed SQL functions
1b1f0 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 ]..** The applic
1b200 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
1b210 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 L function imple
1b220 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 mentation will p
1b230 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e ass this.** poin
1b240 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f ter through into
1b250 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 calls to [sqlit
1b260 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 e3_result_int |
1b270 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 sqlite3_result()
1b280 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 ],.** [sqlite3_a
1b290 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
1b2a0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 ()], [sqlite3_us
1b2b0 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b er_data()],.** [
1b2c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f sqlite3_context_
1b2d0 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 db_handle()], [s
1b2e0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 qlite3_get_auxda
1b2f0 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 ta()],.** and/or
1b300 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
1b310 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 xdata()]..*/.typ
1b320 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
1b330 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 te3_context sqli
1b340 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a te3_context;../*
1b350 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 .** CAPI3REF: Bi
1b360 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 nding Values To
1b370 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 Prepared Stateme
1b380 6e 74 73 20 7b 48 31 33 35 30 30 7d 20 3c 53 37 nts {H13500} <S7
1b390 30 33 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 0300>.** KEYWORD
1b3a0 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 S: {host paramet
1b3b0 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 er} {host parame
1b3c0 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 ters} {host para
1b3d0 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b meter name}.** K
1b3e0 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 EYWORDS: {SQL pa
1b3f0 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 rameter} {SQL pa
1b400 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d rameters} {param
1b410 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a eter binding}.**
1b420 0a 2a 2a 20 49 6e 20 74 68 65 20 53 51 4c 20 73 .** In the SQL s
1b430 74 72 69 6e 67 73 20 69 6e 70 75 74 20 74 6f 20 trings input to
1b440 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1b450 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 _v2()] and its v
1b460 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 ariants,.** lite
1b470 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c rals may be repl
1b480 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d aced by a [param
1b490 65 74 65 72 5d 20 69 6e 20 6f 6e 65 20 6f 66 20 eter] in one of
1b4a0 74 68 65 73 65 20 66 6f 72 6d 73 3a 0a 2a 2a 0a these forms:.**.
1b4b0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
1b4c0 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e ?.** <li> ?NNN
1b4d0 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a .** <li> :VVV.*
1b4e0 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 * <li> @VVV.**
1b4f0 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f <li> $VVV.** </
1b500 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 ul>.**.** In the
1b510 20 70 61 72 61 6d 65 74 65 72 20 66 6f 72 6d 73 parameter forms
1b520 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 4e 4e 4e shown above NNN
1b530 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c is an integer l
1b540 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 iteral,.** and V
1b550 56 56 20 69 73 20 61 6e 20 61 6c 70 68 61 2d 6e VV is an alpha-n
1b560 75 6d 65 72 69 63 20 70 61 72 61 6d 65 74 65 72 umeric parameter
1b570 20 6e 61 6d 65 2e 20 54 68 65 20 76 61 6c 75 65 name. The value
1b580 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 s of these.** pa
1b590 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 rameters (also c
1b5a0 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 alled "host para
1b5b0 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 meter names" or
1b5c0 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 "SQL parameters"
1b5d0 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 ).** can be set
1b5e0 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 using the sqlite
1b5f0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 3_bind_*() routi
1b600 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 nes defined here
1b610 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 ..**.** The firs
1b620 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 t argument to th
1b630 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
1b640 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 () routines is a
1b650 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 lways.** a point
1b660 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 er to the [sqlit
1b670 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 e3_stmt] object
1b680 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a returned from.**
1b690 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1b6a0 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 e_v2()] or its v
1b6b0 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 ariants..**.** T
1b6c0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
1b6d0 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 nt is the index
1b6e0 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d of the SQL param
1b6f0 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a eter to be set..
1b700 2a 2a 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 ** The leftmost
1b710 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 SQL parameter ha
1b720 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e s an index of 1.
1b730 20 20 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 When the same
1b740 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 named.** SQL par
1b750 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d ameter is used m
1b760 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 ore than once, s
1b770 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 econd and subseq
1b780 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e uent.** occurren
1b790 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d ces have the sam
1b7a0 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 e index as the f
1b7b0 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e irst occurrence.
1b7c0 0a 2a 2a 20 54 68 65 20 69 6e 64 65 78 20 66 6f .** The index fo
1b7d0 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 r named paramete
1b7e0 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 rs can be looked
1b7f0 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a up using the.**
1b800 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
1b810 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 arameter_index()
1b820 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64 ] API if desired
1b830 2e 20 20 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 . The index.**
1b840 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d for "?NNN" param
1b850 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c eters is the val
1b860 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 ue of NNN..** Th
1b870 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 e NNN value must
1b880 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e be between 1 an
1b890 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c d the [sqlite3_l
1b8a0 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d imit()].** param
1b8b0 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d eter [SQLITE_LIM
1b8c0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 IT_VARIABLE_NUMB
1b8d0 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c ER] (default val
1b8e0 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 ue: 999)..**.**
1b8f0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 The third argume
1b900 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 nt is the value
1b910 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 to bind to the p
1b920 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 arameter..**.**
1b930 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 In those routine
1b940 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f s that have a fo
1b950 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 urth argument, i
1b960 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a ts value is the.
1b970 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 ** number of byt
1b980 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 es in the parame
1b990 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 ter. To be clea
1b9a0 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 r: the value is
1b9b0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 the.** number of
1b9c0 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e <u>bytes</u> in
1b9d0 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 the value, not
1b9e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 the number of ch
1b9f0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 49 66 20 aracters..** If
1ba00 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
1ba10 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 eter is negative
1ba20 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 , the length of
1ba30 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a the string is.**
1ba40 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
1ba50 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 ytes up to the f
1ba60 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e irst zero termin
1ba70 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ator..**.** The
1ba80 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 fifth argument t
1ba90 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 o sqlite3_bind_b
1baa0 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 lob(), sqlite3_b
1bab0 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a ind_text(), and.
1bac0 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f ** sqlite3_bind_
1bad0 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65 text16() is a de
1bae0 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f structor used to
1baf0 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 dispose of the
1bb00 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e BLOB or.** strin
1bb10 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 g after SQLite h
1bb20 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 as finished with
1bb30 20 69 74 2e 20 49 66 20 74 68 65 20 66 69 66 74 it. If the fift
1bb40 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a h argument is.**
1bb50 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c the special val
1bb60 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 ue [SQLITE_STATI
1bb70 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 C], then SQLite
1bb80 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 assumes that the
1bb90 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 .** information
1bba0 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e is in static, un
1bbb0 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e managed space an
1bbc0 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 d does not need
1bbd0 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 to be freed..**
1bbe0 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 If the fifth arg
1bbf0 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 ument has the va
1bc00 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e lue [SQLITE_TRAN
1bc10 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 SIENT], then.**
1bc20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 SQLite makes its
1bc30 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 own private cop
1bc40 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d y of the data im
1bc50 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 mediately, befor
1bc60 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 e.** the sqlite3
1bc70 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e _bind_*() routin
1bc80 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a e returns..**.**
1bc90 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e The sqlite3_bin
1bca0 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 d_zeroblob() rou
1bcb0 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f tine binds a BLO
1bcc0 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 B of length N th
1bcd0 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 at.** is filled
1bce0 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 41 20 with zeroes. A
1bcf0 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 zeroblob uses a
1bd00 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 fixed amount of
1bd10 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 memory.** (just
1bd20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f an integer to ho
1bd30 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 ld its size) whi
1bd40 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 le it is being p
1bd50 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 rocessed..** Zer
1bd60 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e oblobs are inten
1bd70 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 ded to serve as
1bd80 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 placeholders for
1bd90 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 BLOBs whose.**
1bda0 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 content is later
1bdb0 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a written using.*
1bdc0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f * [sqlite3_blob_
1bdd0 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 open | increment
1bde0 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 al BLOB I/O] rou
1bdf0 74 69 6e 65 73 2e 0a 2a 2a 20 41 20 6e 65 67 61 tines..** A nega
1be00 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 tive value for t
1be10 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 he zeroblob resu
1be20 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 lts in a zero-le
1be30 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a ngth BLOB..**.**
1be40 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e The sqlite3_bin
1be50 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 6d d_*() routines m
1be60 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 61 66 ust be called af
1be70 74 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ter.** [sqlite3_
1be80 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 28 61 prepare_v2()] (a
1be90 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 nd its variants)
1bea0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 or [sqlite3_res
1beb0 65 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 et()] and.** bef
1bec0 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 ore [sqlite3_ste
1bed0 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 p()]..** Binding
1bee0 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 s are not cleare
1bef0 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 d by the [sqlite
1bf00 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 3_reset()] routi
1bf10 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 ne..** Unbound p
1bf20 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e arameters are in
1bf30 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c terpreted as NUL
1bf40 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 L..**.** These r
1bf50 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b outines return [
1bf60 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 SQLITE_OK] on su
1bf70 63 63 65 73 73 20 6f 72 20 61 6e 20 65 72 72 6f ccess or an erro
1bf80 72 20 63 6f 64 65 20 69 66 0a 2a 2a 20 61 6e 79 r code if.** any
1bf90 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 thing goes wrong
1bfa0 2e 20 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 . [SQLITE_RANGE
1bfb0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 ] is returned if
1bfc0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a the parameter.*
1bfd0 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f * index is out o
1bfe0 66 20 72 61 6e 67 65 2e 20 20 5b 53 51 4c 49 54 f range. [SQLIT
1bff0 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 E_NOMEM] is retu
1c000 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 rned if malloc()
1c010 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49 fails..** [SQLI
1c020 54 45 5f 4d 49 53 55 53 45 5d 20 6d 69 67 68 74 TE_MISUSE] might
1c030 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 be returned if
1c040 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 these routines a
1c050 72 65 20 63 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a re called on a.*
1c060 2a 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e * virtual machin
1c070 65 20 74 68 61 74 20 69 73 20 74 68 65 20 77 72 e that is the wr
1c080 6f 6e 67 20 73 74 61 74 65 20 6f 72 20 77 68 69 ong state or whi
1c090 63 68 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 ch has already b
1c0a0 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a een finalized..*
1c0b0 2a 20 44 65 74 65 63 74 69 6f 6e 20 6f 66 20 6d * Detection of m
1c0c0 69 73 75 73 65 20 69 73 20 75 6e 72 65 6c 69 61 isuse is unrelia
1c0d0 62 6c 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f ble. Applicatio
1c0e0 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 64 65 ns should not de
1c0f0 70 65 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54 pend.** on SQLIT
1c100 45 5f 4d 49 53 55 53 45 20 72 65 74 75 72 6e 73 E_MISUSE returns
1c110 2e 20 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 . SQLITE_MISUSE
1c120 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 is intended to
1c130 69 6e 64 69 63 61 74 65 20 61 0a 2a 2a 20 61 20 indicate a.** a
1c140 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 74 logic error in t
1c150 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 he application.
1c160 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 Future versions
1c170 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 of SQLite might
1c180 0a 2a 2a 20 70 61 6e 69 63 20 72 61 74 68 65 72 .** panic rather
1c190 20 74 68 61 6e 20 72 65 74 75 72 6e 20 53 51 4c than return SQL
1c1a0 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a ITE_MISUSE..**.*
1c1b0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
1c1c0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
1c1d0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a ter_count()],.**
1c1e0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
1c1f0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d arameter_name()]
1c200 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 , and [sqlite3_b
1c210 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e ind_parameter_in
1c220 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 dex()]..**.** Re
1c230 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
1c240 48 31 33 35 30 36 5d 20 5b 48 31 33 35 30 39 5d H13506] [H13509]
1c250 20 5b 48 31 33 35 31 32 5d 20 5b 48 31 33 35 31 [H13512] [H1351
1c260 35 5d 20 5b 48 31 33 35 31 38 5d 20 5b 48 31 33 5] [H13518] [H13
1c270 35 32 31 5d 20 5b 48 31 33 35 32 34 5d 20 5b 48 521] [H13524] [H
1c280 31 33 35 32 37 5d 0a 2a 2a 20 5b 48 31 33 35 33 13527].** [H1353
1c290 30 5d 20 5b 48 31 33 35 33 33 5d 20 5b 48 31 33 0] [H13533] [H13
1c2a0 35 33 36 5d 20 5b 48 31 33 35 33 39 5d 20 5b 48 536] [H13539] [H
1c2b0 31 33 35 34 32 5d 20 5b 48 31 33 35 34 35 5d 20 13542] [H13545]
1c2c0 5b 48 31 33 35 34 38 5d 20 5b 48 31 33 35 35 31 [H13548] [H13551
1c2d0 5d 0a 2a 2a 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ].**.*/.int sqli
1c2e0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 te3_bind_blob(sq
1c2f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
1c300 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 , const void*, i
1c310 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f nt n, void(*)(vo
1c320 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 id*));.int sqlit
1c330 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 e3_bind_double(s
1c340 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
1c350 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 t, double);.int
1c360 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 sqlite3_bind_int
1c370 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
1c380 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 int, int);.int s
1c390 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 qlite3_bind_int6
1c3a0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 4(sqlite3_stmt*,
1c3b0 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e int, sqlite3_in
1c3c0 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 t64);.int sqlite
1c3d0 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 3_bind_null(sqli
1c3e0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b te3_stmt*, int);
1c3f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
1c400 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 d_text(sqlite3_s
1c410 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
1c420 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 char*, int n, v
1c430 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
1c440 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
1c450 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f _text16(sqlite3_
1c460 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 stmt*, int, cons
1c470 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f t void*, int, vo
1c480 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 id(*)(void*));.i
1c490 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
1c4a0 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 value(sqlite3_st
1c4b0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 mt*, int, const
1c4c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
1c4d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
1c4e0 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 d_zeroblob(sqlit
1c4f0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 e3_stmt*, int, i
1c500 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 nt n);../*.** CA
1c510 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f PI3REF: Number O
1c520 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 f SQL Parameters
1c530 20 7b 48 31 33 36 30 30 7d 20 3c 53 37 30 33 30 {H13600} <S7030
1c540 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 0>.**.** This ro
1c550 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 utine can be use
1c560 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 d to find the nu
1c570 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 mber of [SQL par
1c580 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 ameters].** in a
1c590 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
1c5a0 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 ment]. SQL para
1c5b0 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e meters are token
1c5c0 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d s of the.** form
1c5d0 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a "?", "?NNN", ":
1c5e0 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 AAA", "$AAA", or
1c5f0 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 "@AAA" that ser
1c600 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f ve as.** placeho
1c610 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 lders for values
1c620 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 that are [sqlit
1c630 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 e3_bind_blob | b
1c640 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 ound].** to the
1c650 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 parameters at a
1c660 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a later time..**.*
1c670 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 * This routine a
1c680 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 ctually returns
1c690 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 the index of the
1c6a0 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d largest (rightm
1c6b0 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 ost).** paramete
1c6c0 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 r. For all forms
1c6d0 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 except ?NNN, th
1c6e0 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f is will correspo
1c6f0 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d nd to the.** num
1c700 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 ber of unique pa
1c710 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 rameters. If pa
1c720 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 rameters of the
1c730 3f 4e 4e 4e 20 61 72 65 20 75 73 65 64 2c 0a 2a ?NNN are used,.*
1c740 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 * there may be g
1c750 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e aps in the list.
1c760 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
1c770 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
1c780 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 lob|sqlite3_bind
1c790 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
1c7a0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
1c7b0 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 name()], and.**
1c7c0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
1c7d0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d rameter_index()]
1c7e0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
1c7f0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 30 31 ents:.** [H13601
1c800 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ].*/.int sqlite3
1c810 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
1c820 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 count(sqlite3_st
1c830 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 mt*);../*.** CAP
1c840 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 I3REF: Name Of A
1c850 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 20 Host Parameter
1c860 7b 48 31 33 36 32 30 7d 20 3c 53 37 30 33 30 30 {H13620} <S70300
1c870 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 >.**.** This rou
1c880 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 tine returns a p
1c890 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 61 ointer to the na
1c8a0 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74 68 0a 2a me of the n-th.*
1c8b0 2a 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 * [SQL parameter
1c8c0 5d 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 ] in a [prepared
1c8d0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 statement]..**
1c8e0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f SQL parameters o
1c8f0 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e f the form "?NNN
1c900 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 " or ":AAA" or "
1c910 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a @AAA" or "$AAA".
1c920 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 ** have a name w
1c930 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 hich is the stri
1c940 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 ng "?NNN" or ":A
1c950 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 AA" or "@AAA" or
1c960 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 "$AAA".** respe
1c970 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f ctively..** In o
1c980 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 ther words, the
1c990 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 initial ":" or "
1c9a0 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 $" or "@" or "?"
1c9b0 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 .** is included
1c9c0 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e as part of the n
1c9d0 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 74 65 ame..** Paramete
1c9e0 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 rs of the form "
1c9f0 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c ?" without a fol
1ca00 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 lowing integer h
1ca10 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 ave no name.** a
1ca20 6e 64 20 61 72 65 20 61 6c 73 6f 20 72 65 66 65 nd are also refe
1ca30 72 72 65 64 20 74 6f 20 61 73 20 22 61 6e 6f 6e rred to as "anon
1ca40 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 ymous parameters
1ca50 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 "..**.** The fir
1ca60 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 st host paramete
1ca70 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f r has an index o
1ca80 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a f 1, not 0..**.*
1ca90 2a 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6e * If the value n
1caa0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 is out of range
1cab0 20 6f 72 20 69 66 20 74 68 65 20 6e 2d 74 68 20 or if the n-th
1cac0 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 parameter is.**
1cad0 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e nameless, then N
1cae0 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e ULL is returned.
1caf0 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 The returned s
1cb00 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 tring is.** alwa
1cb10 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f ys in UTF-8 enco
1cb20 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 ding even if the
1cb30 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 named parameter
1cb40 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c was.** original
1cb50 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 ly specified as
1cb60 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 UTF-16 in [sqlit
1cb70 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 e3_prepare16()]
1cb80 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 or.** [sqlite3_p
1cb90 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a repare16_v2()]..
1cba0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
1cbb0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
1cbc0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 ob|sqlite3_bind(
1cbd0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
1cbe0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 bind_parameter_c
1cbf0 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 ount()], and.**
1cc00 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
1cc10 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d rameter_index()]
1cc20 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
1cc30 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 32 31 ents:.** [H13621
1cc40 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 ].*/.const char
1cc50 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 *sqlite3_bind_pa
1cc60 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c rameter_name(sql
1cc70 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 ite3_stmt*, int)
1cc80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1cc90 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 F: Index Of A Pa
1cca0 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 rameter With A G
1ccb0 69 76 65 6e 20 4e 61 6d 65 20 7b 48 31 33 36 34 iven Name {H1364
1ccc0 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 0} <S70300>.**.*
1ccd0 2a 20 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 * Return the ind
1cce0 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 ex of an SQL par
1ccf0 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 ameter given its
1cd00 20 6e 61 6d 65 2e 20 20 54 68 65 0a 2a 2a 20 69 name. The.** i
1cd10 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 ndex value retur
1cd20 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 ned is suitable
1cd30 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 for use as the s
1cd40 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 econd.** paramet
1cd50 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 er to [sqlite3_b
1cd60 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 ind_blob|sqlite3
1cd70 5f 62 69 6e 64 28 29 5d 2e 20 20 41 20 7a 65 72 _bind()]. A zer
1cd80 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 o.** is returned
1cd90 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 if no matching
1cda0 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 parameter is fou
1cdb0 6e 64 2e 20 20 54 68 65 20 70 61 72 61 6d 65 74 nd. The paramet
1cdc0 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 er.** name must
1cdd0 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d be given in UTF-
1cde0 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 8 even if the or
1cdf0 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 iginal statement
1ce00 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 .** was prepared
1ce10 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 from UTF-16 tex
1ce20 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
1ce30 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
1ce40 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
1ce50 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f : [sqlite3_bind_
1ce60 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e blob|sqlite3_bin
1ce70 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 d()],.** [sqlite
1ce80 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
1ce90 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a _count()], and.*
1cea0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
1ceb0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 parameter_index(
1cec0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 )]..**.** Requir
1ced0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 ements:.** [H136
1cee0 34 31 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 41].*/.int sqlit
1cef0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
1cf00 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f r_index(sqlite3_
1cf10 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 stmt*, const cha
1cf20 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a r *zName);../*.*
1cf30 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 * CAPI3REF: Rese
1cf40 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f t All Bindings O
1cf50 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 n A Prepared Sta
1cf60 74 65 6d 65 6e 74 20 7b 48 31 33 36 36 30 7d 20 tement {H13660}
1cf70 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 43 <S70300>.**.** C
1cf80 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 ontrary to the i
1cf90 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 ntuition of many
1cfa0 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 , [sqlite3_reset
1cfb0 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 ()] does not res
1cfc0 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 et.** the [sqlit
1cfd0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 e3_bind_blob | b
1cfe0 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 indings] on a [p
1cff0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
1d000 74 5d 2e 0a 2a 2a 20 55 73 65 20 74 68 69 73 20 t]..** Use this
1d010 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 routine to reset
1d020 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 all host parame
1d030 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a ters to NULL..**
1d040 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
1d050 3a 0a 2a 2a 20 5b 48 31 33 36 36 31 5d 0a 2a 2f :.** [H13661].*/
1d060 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 .int sqlite3_cle
1d070 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 ar_bindings(sqli
1d080 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a te3_stmt*);../*.
1d090 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d ** CAPI3REF: Num
1d0a0 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 ber Of Columns I
1d0b0 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b n A Result Set {
1d0c0 48 31 33 37 31 30 7d 20 3c 53 31 30 37 30 30 3e H13710} <S10700>
1d0d0 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 .**.** Return th
1d0e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 e number of colu
1d0f0 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c mns in the resul
1d100 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 t set returned b
1d110 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 y the.** [prepar
1d120 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54 ed statement]. T
1d130 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 his routine retu
1d140 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 rns 0 if pStmt i
1d150 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 s an SQL.** stat
1d160 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 ement that does
1d170 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 not return data
1d180 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 (for example an
1d190 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a [UPDATE])..**.**
1d1a0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
1d1b0 2a 20 5b 48 31 33 37 31 31 5d 0a 2a 2f 0a 69 6e * [H13711].*/.in
1d1c0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e t sqlite3_column
1d1d0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 _count(sqlite3_s
1d1e0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a tmt *pStmt);../*
1d1f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
1d200 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 lumn Names In A
1d210 52 65 73 75 6c 74 20 53 65 74 20 7b 48 31 33 37 Result Set {H137
1d220 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 20} <S10700>.**.
1d230 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
1d240 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d s return the nam
1d250 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 e assigned to a
1d260 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d particular colum
1d270 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 n.** in the resu
1d280 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c lt set of a [SEL
1d290 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 ECT] statement.
1d2a0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c The sqlite3_col
1d2b0 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e umn_name().** in
1d2c0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
1d2d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a a pointer to a z
1d2e0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 ero-terminated U
1d2f0 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 TF-8 string.** a
1d300 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nd sqlite3_colum
1d310 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 n_name16() retur
1d320 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
1d330 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
1d340 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 d.** UTF-16 stri
1d350 6e 67 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 ng. The first p
1d360 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 arameter is the
1d370 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
1d380 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 ent].** that imp
1d390 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c lements the [SEL
1d3a0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 ECT] statement.
1d3b0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
1d3c0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 eter is the.** c
1d3d0 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 54 olumn number. T
1d3e0 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 he leftmost colu
1d3f0 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a mn is number 0..
1d400 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e **.** The return
1d410 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 ed string pointe
1d420 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c r is valid until
1d430 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 either the [pre
1d440 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
1d450 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 .** is destroyed
1d460 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e by [sqlite3_fin
1d470 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 alize()] or unti
1d480 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 l the next call
1d490 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f to.** sqlite3_co
1d4a0 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 lumn_name() or s
1d4b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
1d4c0 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 me16() on the sa
1d4d0 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a me column..**.**
1d4e0 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c If sqlite3_mall
1d4f0 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e oc() fails durin
1d500 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 g the processing
1d510 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 of either routi
1d520 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 ne.** (for examp
1d530 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 le during a conv
1d540 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d ersion from UTF-
1d550 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 8 to UTF-16) the
1d560 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e n a.** NULL poin
1d570 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e ter is returned.
1d580 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 .**.** The name
1d590 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 of a result colu
1d5a0 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 mn is the value
1d5b0 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 of the "AS" clau
1d5c0 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 se for.** that c
1d5d0 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 olumn, if there
1d5e0 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e is an AS clause.
1d5f0 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f If there is no
1d600 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 AS clause.** th
1d610 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 en the name of t
1d620 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 he column is uns
1d630 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 pecified and may
1d640 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 change from.**
1d650 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 one release of S
1d660 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 QLite to the nex
1d670 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 t..**.** Require
1d680 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 32 ments:.** [H1372
1d690 31 5d 20 5b 48 31 33 37 32 33 5d 20 5b 48 31 33 1] [H13723] [H13
1d6a0 37 32 34 5d 20 5b 48 31 33 37 32 35 5d 20 5b 48 724] [H13725] [H
1d6b0 31 33 37 32 36 5d 20 5b 48 31 33 37 32 37 5d 0a 13726] [H13727].
1d6c0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 */.const char *s
1d6d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
1d6e0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
1d6f0 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 , int N);.const
1d700 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
1d710 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 lumn_name16(sqli
1d720 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e te3_stmt*, int N
1d730 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1d740 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 EF: Source Of Da
1d750 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 ta In A Query Re
1d760 73 75 6c 74 20 7b 48 31 33 37 34 30 7d 20 3c 53 sult {H13740} <S
1d770 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 10700>.**.** The
1d780 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 se routines prov
1d790 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 ide a means to d
1d7a0 65 74 65 72 6d 69 6e 65 20 77 68 61 74 20 63 6f etermine what co
1d7b0 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a 20 lumn of what.**
1d7c0 74 61 62 6c 65 20 69 6e 20 77 68 69 63 68 20 64 table in which d
1d7d0 61 74 61 62 61 73 65 20 61 20 72 65 73 75 6c 74 atabase a result
1d7e0 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 of a [SELECT] s
1d7f0 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66 tatement comes f
1d800 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 rom..** The name
1d810 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
1d820 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c or table or col
1d830 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 umn can be retur
1d840 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 ned as.** either
1d850 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d a UTF-8 or UTF-
1d860 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 16 string. The
1d870 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 _database_ routi
1d880 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 nes return.** th
1d890 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c e database name,
1d8a0 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 the _table_ rou
1d8b0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 tines return the
1d8c0 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 table name, and
1d8d0 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 .** the origin_
1d8e0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
1d8f0 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e the column name.
1d900 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 .** The returned
1d910 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 string is valid
1d920 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 until the [prep
1d930 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
1d940 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 is destroyed.**
1d950 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 using [sqlite3_f
1d960 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e inalize()] or un
1d970 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 til the same inf
1d980 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 ormation is requ
1d990 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 ested.** again i
1d9a0 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e n a different en
1d9b0 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 coding..**.** Th
1d9c0 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 e names returned
1d9d0 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 are the origina
1d9e0 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d l un-aliased nam
1d9f0 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 es of the.** dat
1da00 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e abase, table, an
1da10 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 d column..**.**
1da20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
1da30 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 nt to the follow
1da40 69 6e 67 20 63 61 6c 6c 73 20 69 73 20 61 20 5b ing calls is a [
1da50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1da60 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73 65 20 66 75 nt]..** These fu
1da70 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 nctions return i
1da80 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 nformation about
1da90 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
1daa0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 returned by.** t
1dab0 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 he statement, wh
1dac0 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 ere N is the sec
1dad0 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 ond function arg
1dae0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 ument..**.** If
1daf0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 the Nth column r
1db00 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 eturned by the s
1db10 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 tatement is an e
1db20 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 xpression or.**
1db30 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 subquery and is
1db40 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c not a column val
1db50 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 ue, then all of
1db60 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 these functions
1db70 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 return.** NULL.
1db80 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d These routine m
1db90 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e ight also return
1dba0 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 NULL if a memor
1dbb0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 y allocation err
1dbc0 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 4f or.** occurs. O
1dbd0 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 therwise, they r
1dbe0 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f eturn the name o
1dbf0 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 f the attached d
1dc00 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 0a 2a atabase, table.*
1dc10 2a 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74 68 61 * and column tha
1dc20 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 t query result c
1dc30 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 olumn was extrac
1dc40 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 ted from..**.**
1dc50 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 As with all othe
1dc60 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 r SQLite APIs, t
1dc70 68 6f 73 65 20 70 6f 73 74 66 69 78 65 64 20 77 hose postfixed w
1dc80 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a ith "16" return.
1dc90 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 ** UTF-16 encode
1dca0 64 20 73 74 72 69 6e 67 73 2c 20 74 68 65 20 6f d strings, the o
1dcb0 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 ther functions r
1dcc0 65 74 75 72 6e 20 55 54 46 2d 38 2e 20 7b 45 4e eturn UTF-8. {EN
1dcd0 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 41 D}.**.** These A
1dce0 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 PIs are only ava
1dcf0 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 ilable if the li
1dd00 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c brary was compil
1dd10 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b ed with the.** [
1dd20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f SQLITE_ENABLE_CO
1dd30 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 LUMN_METADATA] C
1dd40 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 -preprocessor sy
1dd50 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a mbol defined..**
1dd60 0a 2a 2a 20 7b 41 31 33 37 35 31 7d 0a 2a 2a 20 .** {A13751}.**
1dd70 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 If two or more t
1dd80 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 hreads call one
1dd90 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 or more of these
1dda0 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 routines agains
1ddb0 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 t the same.** pr
1ddc0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1ddd0 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 and column at t
1dde0 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 he same time the
1ddf0 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 n the results ar
1de00 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a e.** undefined..
1de10 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
1de20 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 34 31 5d 20 ts:.** [H13741]
1de30 5b 48 31 33 37 34 32 5d 20 5b 48 31 33 37 34 33 [H13742] [H13743
1de40 5d 20 5b 48 31 33 37 34 34 5d 20 5b 48 31 33 37 ] [H13744] [H137
1de50 34 35 5d 20 5b 48 31 33 37 34 36 5d 20 5b 48 31 45] [H13746] [H1
1de60 33 37 34 38 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 3748].**.** If t
1de70 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 wo or more threa
1de80 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d ds call one or m
1de90 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ore.** [sqlite3_
1dea0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f column_database_
1deb0 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 name | column me
1dec0 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 tadata interface
1ded0 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 s].** for the sa
1dee0 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 me [prepared sta
1def0 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 tement] and resu
1df00 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 lt column.** at
1df10 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 the same time th
1df20 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 en the results a
1df30 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f re undefined..*/
1df40 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
1df50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 ite3_column_data
1df60 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 base_name(sqlite
1df70 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 3_stmt*,int);.co
1df80 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
1df90 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 3_column_databas
1dfa0 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 e_name16(sqlite3
1dfb0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e _stmt*,int);.con
1dfc0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
1dfd0 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 _column_table_na
1dfe0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
1dff0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 ,int);.const voi
1e000 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
1e010 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 n_table_name16(s
1e020 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
1e030 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 );.const char *s
1e040 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 qlite3_column_or
1e050 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 igin_name(sqlite
1e060 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 3_stmt*,int);.co
1e070 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
1e080 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 3_column_origin_
1e090 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 name16(sqlite3_s
1e0a0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a tmt*,int);../*.*
1e0b0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c * CAPI3REF: Decl
1e0c0 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 ared Datatype Of
1e0d0 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 A Query Result
1e0e0 7b 48 31 33 37 36 30 7d 20 3c 53 31 30 37 30 30 {H13760} <S10700
1e0f0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 >.**.** The firs
1e100 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 t parameter is a
1e110 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
1e120 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 ment]..** If thi
1e130 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 s statement is a
1e140 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d [SELECT] statem
1e150 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 ent and the Nth
1e160 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a column of the.**
1e170 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 returned result
1e180 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 set of that [SE
1e190 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 LECT] is a table
1e1a0 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a column (not an.
1e1b0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 ** expression or
1e1c0 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 subquery) then
1e1d0 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 the declared typ
1e1e0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a e of the table.*
1e1f0 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 * column is retu
1e200 72 6e 65 64 2e 20 20 49 66 20 74 68 65 20 4e 74 rned. If the Nt
1e210 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 h column of the
1e220 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e result set is an
1e230 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f .** expression o
1e240 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e r subquery, then
1e250 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
1e260 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 is returned..**
1e270 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 The returned str
1e280 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 ing is always UT
1e290 46 2d 38 20 65 6e 63 6f 64 65 64 2e 20 7b 45 4e F-8 encoded. {EN
1e2a0 44 7d 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 D}.**.** For exa
1e2b0 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 mple, given the
1e2c0 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a database schema:
1e2d0 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 .**.** CREATE TA
1e2e0 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e BLE t1(c1 VARIAN
1e2f0 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 T);.**.** and th
1e300 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 e following stat
1e310 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 ement to be comp
1e320 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 iled:.**.** SELE
1e330 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 CT c1 + 1, c1 FR
1e340 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 OM t1;.**.** thi
1e350 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 s routine would
1e360 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e return the strin
1e370 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 g "VARIANT" for
1e380 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c the second resul
1e390 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d t.** column (i==
1e3a0 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 1), and a NULL p
1e3b0 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 ointer for the f
1e3c0 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 irst result colu
1e3d0 6d 6e 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a mn (i==0)..**.**
1e3e0 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e SQLite uses dyn
1e3f0 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 amic run-time ty
1e400 70 69 6e 67 2e 20 20 53 6f 20 6a 75 73 74 20 62 ping. So just b
1e410 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a ecause a column.
1e420 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 ** is declared t
1e430 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 o contain a part
1e440 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 icular type does
1e450 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 not mean that t
1e460 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 he.** data store
1e470 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e d in that column
1e480 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 is of the decla
1e490 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 red type. SQLit
1e4a0 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 e is.** strongly
1e4b0 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 typed, but the
1e4c0 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 typing is dynami
1e4d0 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 54 c not static. T
1e4e0 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 ype.** is associ
1e4f0 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 ated with indivi
1e500 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 dual values, not
1e510 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 with the contai
1e520 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 ners.** used to
1e530 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 hold those value
1e540 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 s..**.** Require
1e550 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 36 ments:.** [H1376
1e560 31 5d 20 5b 48 31 33 37 36 32 5d 20 5b 48 31 33 1] [H13762] [H13
1e570 37 36 33 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 763].*/.const ch
1e580 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ar *sqlite3_colu
1e590 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 mn_decltype(sqli
1e5a0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
1e5b0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
1e5c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 te3_column_declt
1e5d0 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ype16(sqlite3_st
1e5e0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a mt*,int);../*.**
1e5f0 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 CAPI3REF: Evalu
1e600 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 ate An SQL State
1e610 6d 65 6e 74 20 7b 48 31 33 32 30 30 7d 20 3c 53 ment {H13200} <S
1e620 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 66 74 10000>.**.** Aft
1e630 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 er a [prepared s
1e640 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 tatement] has be
1e650 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e en prepared usin
1e660 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c g either.** [sql
1e670 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
1e680 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 )] or [sqlite3_p
1e690 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f repare16_v2()] o
1e6a0 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 r one of the leg
1e6b0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 acy.** interface
1e6c0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 s [sqlite3_prepa
1e6d0 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 re()] or [sqlite
1e6e0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 3_prepare16()],
1e6f0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a this function.**
1e700 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 must be called
1e710 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 one or more time
1e720 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 s to evaluate th
1e730 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a e statement..**.
1e740 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f ** The details o
1e750 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f f the behavior o
1e760 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 f the sqlite3_st
1e770 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 ep() interface d
1e780 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 epend.** on whet
1e790 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e her the statemen
1e7a0 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75 t was prepared u
1e7b0 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 sing the newer "
1e7c0 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a v2" interface.**
1e7d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1e7e0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c e_v2()] and [sql
1e7f0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
1e800 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 2()] or the olde
1e810 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 r legacy.** inte
1e820 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 rface [sqlite3_p
1e830 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 repare()] and [s
1e840 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
1e850 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 ()]. The use of
1e860 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 the.** new "v2"
1e870 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 interface is re
1e880 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 commended for ne
1e890 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 w applications b
1e8a0 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a ut the legacy.**
1e8b0 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 interface will
1e8c0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 continue to be s
1e8d0 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 upported..**.**
1e8e0 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e In the legacy in
1e8f0 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 terface, the ret
1e900 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 urn value will b
1e910 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 e either [SQLITE
1e920 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 _BUSY],.** [SQLI
1e930 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 TE_DONE], [SQLIT
1e940 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f E_ROW], [SQLITE_
1e950 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 ERROR], or [SQLI
1e960 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 TE_MISUSE]..** W
1e970 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 ith the "v2" int
1e980 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 erface, any of t
1e990 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 he other [result
1e9a0 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 codes] or.** [e
1e9b0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
1e9c0 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 odes] might be r
1e9d0 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e eturned as well.
1e9e0 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 .**.** [SQLITE_B
1e9f0 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 USY] means that
1ea00 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 the database eng
1ea10 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 ine was unable t
1ea20 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a o acquire the.**
1ea30 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 database locks
1ea40 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 it needs to do i
1ea50 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68 65 20 ts job. If the
1ea60 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b statement is a [
1ea70 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 COMMIT].** or oc
1ea80 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 curs outside of
1ea90 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e an explicit tran
1eaa0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f saction, then yo
1eab0 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a u can retry the.
1eac0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 ** statement. I
1ead0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 f the statement
1eae0 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 is not a [COMMIT
1eaf0 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 ] and occurs wit
1eb00 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 hin a.** explici
1eb10 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 t transaction th
1eb20 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f en you should ro
1eb30 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 llback the trans
1eb40 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a action before.**
1eb50 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a continuing..**.
1eb60 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d ** [SQLITE_DONE]
1eb70 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 means that the
1eb80 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 statement has fi
1eb90 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 nished executing
1eba0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 .** successfully
1ebb0 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 . sqlite3_step(
1ebc0 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 ) should not be
1ebd0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 called again on
1ebe0 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 this virtual.**
1ebf0 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 machine without
1ec00 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 first calling [s
1ec10 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
1ec20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 to reset the vir
1ec30 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 tual.** machine
1ec40 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 back to its init
1ec50 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a ial state..**.**
1ec60 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 If the SQL stat
1ec70 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 ement being exec
1ec80 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 uted returns any
1ec90 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c data, then [SQL
1eca0 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 ITE_ROW].** is r
1ecb0 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d eturned each tim
1ecc0 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 e a new row of d
1ecd0 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 ata is ready for
1ece0 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 processing by t
1ecf0 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 he.** caller. Th
1ed00 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 e values may be
1ed10 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 accessed using t
1ed20 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 he [column acces
1ed30 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a s functions]..**
1ed40 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
1ed50 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 is called again
1ed60 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 to retrieve the
1ed70 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 next row of data
1ed80 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ..**.** [SQLITE_
1ed90 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 ERROR] means tha
1eda0 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 t a run-time err
1edb0 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f or (such as a co
1edc0 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c nstraint.** viol
1edd0 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 ation) has occur
1ede0 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 red. sqlite3_st
1edf0 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 ep() should not
1ee00 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 be called again
1ee10 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f on.** the VM. Mo
1ee20 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d re information m
1ee30 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 ay be found by c
1ee40 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
1ee50 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 errmsg()]..** Wi
1ee60 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e th the legacy in
1ee70 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 terface, a more
1ee80 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 specific error c
1ee90 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 ode (for example
1eea0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 ,.** [SQLITE_INT
1eeb0 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 ERRUPT], [SQLITE
1eec0 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 _SCHEMA], [SQLIT
1eed0 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 E_CORRUPT], and
1eee0 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e so forth).** can
1eef0 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 be obtained by
1ef00 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 calling [sqlite3
1ef10 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 _reset()] on the
1ef20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 .** [prepared st
1ef30 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68 atement]. In th
1ef40 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 e "v2" interface
1ef50 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 ,.** the more sp
1ef60 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 ecific error cod
1ef70 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 e is returned di
1ef80 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 rectly by sqlite
1ef90 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 3_step()..**.**
1efa0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 [SQLITE_MISUSE]
1efb0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 means that the t
1efc0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 his routine was
1efd0 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 called inappropr
1efe0 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 iately..** Perha
1eff0 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 ps it was called
1f000 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 on a [prepared
1f010 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 statement] that
1f020 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 has.** already b
1f030 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e een [sqlite3_fin
1f040 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 alize | finalize
1f050 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 d] or on one tha
1f060 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 t had.** previou
1f070 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 sly returned [SQ
1f080 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b LITE_ERROR] or [
1f090 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f SQLITE_DONE]. O
1f0a0 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 r it could.** be
1f0b0 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 the case that t
1f0c0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 he same database
1f0d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 connection is b
1f0e0 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f eing used by two
1f0f0 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 or.** more thre
1f100 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 ads at the same
1f110 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a moment in time..
1f120 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 **.** <b>Goofy I
1f130 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c nterface Alert:<
1f140 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 /b> In the legac
1f150 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 y interface, the
1f160 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a sqlite3_step().
1f170 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 ** API always re
1f180 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 turns a generic
1f190 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c error code, [SQL
1f1a0 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c ITE_ERROR], foll
1f1b0 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 owing any.** err
1f1c0 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 or other than [S
1f1d0 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 QLITE_BUSY] and
1f1e0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e [SQLITE_MISUSE].
1f1f0 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a You must call.
1f200 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ** [sqlite3_rese
1f210 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 t()] or [sqlite3
1f220 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 _finalize()] in
1f230 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e order to find on
1f240 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 e of the.** spec
1f250 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 ific [error code
1f260 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 s] that better d
1f270 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 escribes the err
1f280 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 or..** We admit
1f290 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 that this is a g
1f2a0 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 oofy design. Th
1f2b0 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 e problem has be
1f2c0 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 en fixed.** with
1f2d0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 the "v2" interf
1f2e0 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 ace. If you pre
1f2f0 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 pare all of your
1f300 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a SQL statements.
1f310 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 ** using either
1f320 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1f330 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 _v2()] or [sqlit
1f340 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
1f350 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 )] instead.** of
1f360 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c the legacy [sql
1f370 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
1f380 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 and [sqlite3_pre
1f390 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 pare16()] interf
1f3a0 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 aces,.** then th
1f3b0 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 e more specific
1f3c0 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 [error codes] ar
1f3d0 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 e returned direc
1f3e0 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 tly.** by sqlite
1f3f0 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 3_step(). The u
1f400 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 se of the "v2" i
1f410 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f nterface is reco
1f420 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 mmended..**.** R
1f430 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
1f440 5b 48 31 33 32 30 32 5d 20 5b 48 31 35 33 30 34 [H13202] [H15304
1f450 5d 20 5b 48 31 35 33 30 36 5d 20 5b 48 31 35 33 ] [H15306] [H153
1f460 30 38 5d 20 5b 48 31 35 33 31 30 5d 0a 2a 2f 0a 08] [H15310].*/.
1f470 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 int sqlite3_step
1f480 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b (sqlite3_stmt*);
1f490 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1f4a0 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 : Number of colu
1f4b0 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 mns in a result
1f4c0 73 65 74 20 7b 48 31 33 37 37 30 7d 20 3c 53 31 set {H13770} <S1
1f4d0 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 0700>.**.** Retu
1f4e0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
1f4f0 66 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20 f values in the
1f500 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 current row of t
1f510 68 65 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a he result set..*
1f520 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
1f530 73 3a 0a 2a 2a 20 5b 48 31 33 37 37 31 5d 20 5b s:.** [H13771] [
1f540 48 31 33 37 37 32 5d 0a 2a 2f 0a 69 6e 74 20 73 H13772].*/.int s
1f550 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e qlite3_data_coun
1f560 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a t(sqlite3_stmt *
1f570 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 pStmt);../*.** C
1f580 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 API3REF: Fundame
1f590 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 20 7b ntal Datatypes {
1f5a0 48 31 30 32 36 35 7d 20 3c 53 31 30 31 31 30 3e H10265} <S10110>
1f5b0 3c 53 31 30 31 32 30 3e 0a 2a 2a 20 4b 45 59 57 <S10120>.** KEYW
1f5c0 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 ORDS: SQLITE_TEX
1f5d0 54 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 36 36 7d T.**.** {H10266}
1f5e0 20 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 Every value in
1f5f0 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f SQLite has one o
1f600 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 f five fundament
1f610 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a al datatypes:.**
1f620 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
1f630 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 64-bit signed i
1f640 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 nteger.** <li> 6
1f650 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 4-bit IEEE float
1f660 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 ing point number
1f670 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a .** <li> string.
1f680 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 ** <li> BLOB.**
1f690 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 <li> NULL.** </u
1f6a0 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 l> {END}.**.** T
1f6b0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 hese constants a
1f6c0 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 re codes for eac
1f6d0 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 h of those types
1f6e0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ..**.** Note tha
1f6f0 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 t the SQLITE_TEX
1f700 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 T constant was a
1f710 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 lso used in SQLi
1f720 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 te version 2.**
1f730 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 for a completely
1f740 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 different meani
1f750 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 ng. Software th
1f760 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 at links against
1f770 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 both.** SQLite
1f780 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 version 2 and SQ
1f790 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 Lite version 3 s
1f7a0 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 hould use SQLITE
1f7b0 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 3_TEXT, not.** S
1f7c0 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 QLITE_TEXT..*/.#
1f7d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e define SQLITE_IN
1f7e0 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 TEGER 1.#define
1f7f0 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 SQLITE_FLOAT
1f800 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
1f810 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 E_BLOB 4.#de
1f820 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c fine SQLITE_NULL
1f830 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 5.#ifdef SQ
1f840 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 LITE_TEXT.# unde
1f850 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 f SQLITE_TEXT.#e
1f860 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c lse.# define SQL
1f870 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 ITE_TEXT 3.#
1f880 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 endif.#define SQ
1f890 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 LITE3_TEXT 3
1f8a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1f8b0 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 : Result Values
1f8c0 46 72 6f 6d 20 41 20 51 75 65 72 79 20 7b 48 31 From A Query {H1
1f8d0 33 38 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 3800} <S10700>.*
1f8e0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c * KEYWORDS: {col
1f8f0 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 umn access funct
1f900 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ions}.**.** Thes
1f910 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 e routines form
1f920 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 20 the "result set
1f930 71 75 65 72 79 22 20 69 6e 74 65 72 66 61 63 65 query" interface
1f940 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f ..**.** These ro
1f950 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e utines return in
1f960 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 formation about
1f970 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 a single column
1f980 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a of the current.*
1f990 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 * result row of
1f9a0 61 20 71 75 65 72 79 2e 20 20 49 6e 20 65 76 65 a query. In eve
1f9b0 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 ry case the firs
1f9c0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 t argument is a
1f9d0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 pointer.** to th
1f9e0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
1f9f0 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 ement] that is b
1fa00 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 eing evaluated (
1fa10 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d the [sqlite3_stm
1fa20 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 t*].** that was
1fa30 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 returned from [s
1fa40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1fa50 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 2()] or one of i
1fa60 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 ts variants).**
1fa70 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 and the second a
1fa80 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 rgument is the i
1fa90 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 ndex of the colu
1faa0 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 mn for which inf
1fab0 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 ormation.** shou
1fac0 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 ld be returned.
1fad0 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f The leftmost co
1fae0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 lumn of the resu
1faf0 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 lt set has the i
1fb00 6e 64 65 78 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 ndex 0..**.** If
1fb10 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
1fb20 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 nt does not curr
1fb30 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 ently point to a
1fb40 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 valid row, or i
1fb50 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 f the.** column
1fb60 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 index is out of
1fb70 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c range, the resul
1fb80 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a t is undefined..
1fb90 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
1fba0 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 s may only be ca
1fbb0 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f lled when the mo
1fbc0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 st recent call t
1fbd0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 o.** [sqlite3_st
1fbe0 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e ep()] has return
1fbf0 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 ed [SQLITE_ROW]
1fc00 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b and neither.** [
1fc10 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
1fc20 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 nor [sqlite3_fi
1fc30 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 nalize()] have b
1fc40 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 een called subse
1fc50 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 quently..** If a
1fc60 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 ny of these rout
1fc70 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 ines are called
1fc80 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 after [sqlite3_r
1fc90 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 eset()] or.** [s
1fca0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
1fcb0 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c )] or after [sql
1fcc0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 ite3_step()] has
1fcd0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d returned.** som
1fce0 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 ething other tha
1fcf0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 n [SQLITE_ROW],
1fd00 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 the results are
1fd10 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 undefined..** If
1fd20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
1fd30 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 ] or [sqlite3_re
1fd40 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 set()] or [sqlit
1fd50 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a e3_finalize()].*
1fd60 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f * are called fro
1fd70 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 m a different th
1fd80 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f read while any o
1fd90 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
1fda0 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c .** are pending,
1fdb0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 then the result
1fdc0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e s are undefined.
1fdd0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
1fde0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 e3_column_type()
1fdf0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
1fe00 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
1fe10 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 INTEGER | dataty
1fe20 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 pe code] for the
1fe30 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 initial data ty
1fe40 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 pe.** of the res
1fe50 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 ult column. The
1fe60 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 returned value
1fe70 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 is one of [SQLIT
1fe80 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b E_INTEGER],.** [
1fe90 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b SQLITE_FLOAT], [
1fea0 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 SQLITE_TEXT], [S
1feb0 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 QLITE_BLOB], or
1fec0 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 [SQLITE_NULL].
1fed0 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 The value.** ret
1fee0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
1fef0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 _column_type() i
1ff00 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 s only meaningfu
1ff10 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 l if no type.**
1ff20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 conversions have
1ff30 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73 occurred as des
1ff40 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 cribed below. A
1ff50 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 fter a type conv
1ff60 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 ersion,.** the v
1ff70 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 alue returned by
1ff80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
1ff90 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 type() is undefi
1ffa0 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 ned. Future.**
1ffb0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
1ffc0 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 te may change th
1ffd0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 e behavior of sq
1ffe0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 lite3_column_typ
1fff0 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 e().** following
20000 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 a type conversi
20010 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 on..**.** If the
20020 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f result is a BLO
20030 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e B or UTF-8 strin
20040 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 g then the sqlit
20050 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
20060 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 ).** routine ret
20070 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
20080 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 of bytes in that
20090 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e BLOB or string.
200a0 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c .** If the resul
200b0 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 t is a UTF-16 st
200c0 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 ring, then sqlit
200d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
200e0 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 ) converts.** th
200f0 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d e string to UTF-
20100 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 8 and then retur
20110 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
20120 20 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 bytes..** If th
20130 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 e result is a nu
20140 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e meric value then
20150 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
20160 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 bytes() uses.**
20170 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 [sqlite3_snprint
20180 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 f()] to convert
20190 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 that value to a
201a0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 UTF-8 string and
201b0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 returns.** the
201c0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
201d0 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a in that string..
201e0 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 ** The value ret
201f0 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 urned does not i
20200 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 nclude the zero
20210 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 terminator at th
20220 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 e end.** of the
20230 73 74 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 string. For cla
20240 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20 rity: the value
20250 72 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 returned is the
20260 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 number of.** byt
20270 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 es in the string
20280 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 , not the number
20290 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a of characters..
202a0 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 20 72 65 **.** Strings re
202b0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 turned by sqlite
202c0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 3_column_text()
202d0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 and sqlite3_colu
202e0 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 mn_text16(),.**
202f0 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e even empty strin
20300 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a gs, are always z
20310 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 ero terminated.
20320 20 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 The return.** v
20330 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 alue from sqlite
20340 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 3_column_blob()
20350 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 for a zero-lengt
20360 68 20 42 4c 4f 42 20 69 73 20 61 6e 20 61 72 62 h BLOB is an arb
20370 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 itrary.** pointe
20380 72 2c 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e r, possibly even
20390 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
203a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
203b0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
203c0 36 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 6() routine is s
203d0 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 imilar to sqlite
203e0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
203f0 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74 .** but leaves t
20400 68 65 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46 he result in UTF
20410 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 -16 in native by
20420 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 te order instead
20430 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 54 68 of UTF-8..** Th
20440 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f e zero terminato
20450 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 r is not include
20460 64 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e d in this count.
20470 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a 65 63 .**.** The objec
20480 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 t returned by [s
20490 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 qlite3_column_va
204a0 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 lue()] is an.**
204b0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c [unprotected sql
204c0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
204d0 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 ct. An unprotec
204e0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
204f0 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 e object.** may
20500 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 only be used wit
20510 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f h [sqlite3_bind_
20520 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 value()] and [sq
20530 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c lite3_result_val
20540 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 ue()]..** If the
20550 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 [unprotected sq
20560 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
20570 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a ect returned by.
20580 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ** [sqlite3_colu
20590 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 mn_value()] is u
205a0 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 sed in any other
205b0 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 way, including
205c0 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 calls.** to rout
205d0 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 ines like [sqlit
205e0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c e3_value_int()],
205f0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
20600 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b text()],.** or [
20610 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 sqlite3_value_by
20620 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 tes()], then the
20630 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 behavior is und
20640 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 efined..**.** Th
20650 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 ese routines att
20660 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 empt to convert
20670 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 the value where
20680 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 46 6f appropriate. Fo
20690 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 r.** example, if
206a0 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 the internal re
206b0 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 presentation is
206c0 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 FLOAT and a text
206d0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 result.** is re
206e0 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 quested, [sqlite
206f0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 3_snprintf()] is
20700 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 used internally
20710 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a to perform the.
20720 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 ** conversion au
20730 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 tomatically. Th
20740 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c e following tabl
20750 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f e details the co
20760 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 nversions.** tha
20770 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a t are applied:.*
20780 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
20790 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 >.** <table bord
207a0 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c er="1">.** <tr><
207b0 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e th> Internal<br>
207c0 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 Type <th> Reques
207d0 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e ted<br>Type <th>
207e0 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a Conversion.**.
207f0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c ** <tr><td> NUL
20800 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 L <td> INTEGE
20810 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 R <td> Result
20820 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e is 0.** <tr><td>
20830 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 NULL <td>
20840 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 FLOAT <td> Re
20850 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c sult is 0.0.** <
20860 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 tr><td> NULL
20870 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 <td> TEXT
20880 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e <td> Result is N
20890 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c ULL pointer.** <
208a0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 tr><td> NULL
208b0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 <td> BLOB
208c0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e <td> Result is N
208d0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c ULL pointer.** <
208e0 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 tr><td> INTEGER
208f0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 <td> FLOAT
20900 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f <td> Convert fro
20910 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f m integer to flo
20920 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 at.** <tr><td> I
20930 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 NTEGER <td> T
20940 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 EXT <td> ASCI
20950 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 I rendering of t
20960 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 he integer.** <t
20970 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 r><td> INTEGER
20980 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c <td> BLOB <
20990 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 td> Same as INTE
209a0 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 GER->TEXT.** <tr
209b0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c ><td> FLOAT <
209c0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 td> INTEGER <t
209d0 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 d> Convert from
209e0 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 float to integer
209f0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c .** <tr><td> FL
20a00 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 OAT <td> TEX
20a10 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 T <td> ASCII
20a20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 rendering of the
20a30 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 float.** <tr><t
20a40 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e d> FLOAT <td>
20a50 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 BLOB <td>
20a60 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 Same as FLOAT->T
20a70 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 EXT.** <tr><td>
20a80 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e TEXT <td> IN
20a90 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 TEGER <td> Use
20aa0 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c atoi().** <tr><
20ab0 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 td> TEXT <td
20ac0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e > FLOAT <td>
20ad0 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c Use atof().** <
20ae0 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 tr><td> TEXT
20af0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 <td> BLOB
20b00 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a <td> No change.*
20b10 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 * <tr><td> BLOB
20b20 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 <td> INTEGER
20b30 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 <td> Convert
20b40 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 to TEXT then use
20b50 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c atoi().** <tr><
20b60 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 td> BLOB <td
20b70 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e > FLOAT <td>
20b80 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 Convert to TEXT
20b90 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 then use atof()
20ba0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c .** <tr><td> BL
20bb0 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 OB <td> TEX
20bc0 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 T <td> Add a
20bd0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 zero terminator
20be0 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 if needed.** </t
20bf0 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b able>.** </block
20c00 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 quote>.**.** The
20c10 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b table above mak
20c20 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 es reference to
20c30 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 standard C libra
20c40 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f ry functions ato
20c50 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 i().** and atof(
20c60 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 ). SQLite does
20c70 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 not really use t
20c80 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 hese functions.
20c90 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f It has its.** o
20ca0 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e wn equivalent in
20cb0 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e ternal routines.
20cc0 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 The atoi() and
20cd0 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 atof() names ar
20ce0 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 e.** used in the
20cf0 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 table for brevi
20d00 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 ty and because t
20d10 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 hey are familiar
20d20 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 to most.** C pr
20d30 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a ogrammers..**.**
20d40 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 Note that when
20d50 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 type conversions
20d60 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 occur, pointers
20d70 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 returned by pri
20d80 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 or.** calls to s
20d90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
20da0 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f ob(), sqlite3_co
20db0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 lumn_text(), and
20dc0 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 /or.** sqlite3_c
20dd0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d olumn_text16() m
20de0 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 ay be invalidate
20df0 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 d..** Type conve
20e00 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 rsions and point
20e10 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 er invalidations
20e20 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 might occur.**
20e30 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 in the following
20e40 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 cases:.**.** <u
20e50 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 l>.** <li> The i
20e60 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 nitial content i
20e70 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c s a BLOB and sql
20e80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
20e90 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 () or.** sq
20ea0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
20eb0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e t16() is called.
20ec0 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 A zero-termina
20ed0 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 tor might.**
20ee0 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 need to be add
20ef0 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 ed to the string
20f00 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 .</li>.** <li> T
20f10 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 he initial conte
20f20 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 nt is UTF-8 text
20f30 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
20f40 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 umn_bytes16() or
20f50 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 .** sqlite3
20f60 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
20f70 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 is called. The
20f80 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 content must be
20f90 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 converted.**
20fa0 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c to UTF-16.</l
20fb0 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 i>.** <li> The i
20fc0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 nitial content i
20fd0 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e s UTF-16 text an
20fe0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e d sqlite3_column
20ff0 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 _bytes() or.**
21000 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 sqlite3_colu
21010 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c mn_text() is cal
21020 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e led. The conten
21030 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 t must be conver
21040 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 ted.** to U
21050 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f TF-8.</li>.** </
21060 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 ul>.**.** Conver
21070 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 sions between UT
21080 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 F-16be and UTF-1
21090 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6le are always d
210a0 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 one in place and
210b0 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c do.** not inval
210c0 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f idate a prior po
210d0 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 inter, though of
210e0 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 course the cont
210f0 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 ent of the buffe
21100 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 r.** that the pr
21110 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e ior pointer poin
21120 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 ts to will have
21130 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 been modified.
21140 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f Other kinds.** o
21150 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 f conversion are
21160 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 done in place w
21170 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 hen it is possib
21180 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 le, but sometime
21190 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f s they.** are no
211a0 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 t possible and i
211b0 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 n those cases pr
211c0 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 ior pointers are
211d0 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a invalidated..**
211e0 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 .** The safest a
211f0 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 nd easiest to re
21200 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 member policy is
21210 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 to invoke these
21220 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 routines.** in
21230 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f one of the follo
21240 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a wing ways:.**.**
21250 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 <ul>.** <li>sq
21260 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
21270 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 t() followed by
21280 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
21290 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 ytes()</li>.**
212a0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 <li>sqlite3_colu
212b0 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 mn_blob() follow
212c0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f ed by sqlite3_co
212d0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 lumn_bytes()</li
212e0 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 >.** <li>sqlite
212f0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
21300 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 ) followed by sq
21310 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
21320 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c es16()</li>.** <
21330 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 /ul>.**.** In ot
21340 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 her words, you s
21350 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 hould call sqlit
21360 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
21370 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c ,.** sqlite3_col
21380 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 umn_blob(), or s
21390 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
213a0 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 xt16() first to
213b0 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 force the result
213c0 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 .** into the des
213d0 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 ired format, the
213e0 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 n invoke sqlite3
213f0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 _column_bytes()
21400 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f or.** sqlite3_co
21410 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 lumn_bytes16() t
21420 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 o find the size
21430 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 of the result.
21440 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 Do not mix calls
21450 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 .** to sqlite3_c
21460 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 olumn_text() or
21470 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
21480 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 lob() with calls
21490 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 to.** sqlite3_c
214a0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c olumn_bytes16(),
214b0 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 and do not mix
214c0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
214d0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
214e0 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 .** with calls t
214f0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e o sqlite3_column
21500 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 _bytes()..**.**
21510 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 The pointers ret
21520 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 urned are valid
21530 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e until a type con
21540 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 version occurs a
21550 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 s.** described a
21560 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b bove, or until [
21570 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
21580 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 or [sqlite3_rese
21590 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 t()] or.** [sqli
215a0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
215b0 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 is called. The
215c0 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 memory space use
215d0 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 d to hold string
215e0 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 s.** and BLOBs i
215f0 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 s freed automati
21600 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f cally. Do <b>no
21610 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 t</b> pass the p
21620 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 ointers returned
21630 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c .** [sqlite3_col
21640 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 umn_blob()], [sq
21650 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
21660 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a t()], etc. into.
21670 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ** [sqlite3_free
21680 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 ()]..**.** If a
21690 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
216a0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 n error occurs d
216b0 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 uring the evalua
216c0 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f tion of any.** o
216d0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
216e0 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 , a default valu
216f0 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 e is returned.
21700 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 The default valu
21710 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 e.** is either t
21720 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 he integer 0, th
21730 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 e floating point
21740 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 number 0.0, or
21750 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 a NULL.** pointe
21760 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 r. Subsequent c
21770 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
21780 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c _errcode()] will
21790 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 return.** [SQLI
217a0 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a TE_NOMEM]..**.**
217b0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
217c0 2a 20 5b 48 31 33 38 30 33 5d 20 5b 48 31 33 38 * [H13803] [H138
217d0 30 36 5d 20 5b 48 31 33 38 30 39 5d 20 5b 48 31 06] [H13809] [H1
217e0 33 38 31 32 5d 20 5b 48 31 33 38 31 35 5d 20 5b 3812] [H13815] [
217f0 48 31 33 38 31 38 5d 20 5b 48 31 33 38 32 31 5d H13818] [H13821]
21800 20 5b 48 31 33 38 32 34 5d 0a 2a 2a 20 5b 48 31 [H13824].** [H1
21810 33 38 32 37 5d 20 5b 48 31 33 38 33 30 5d 0a 2a 3827] [H13830].*
21820 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 /.const void *sq
21830 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
21840 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c b(sqlite3_stmt*,
21850 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 int iCol);.int
21860 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
21870 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d ytes(sqlite3_stm
21880 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 t*, int iCol);.i
21890 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nt sqlite3_colum
218a0 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 n_bytes16(sqlite
218b0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
218c0 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 l);.double sqlit
218d0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 e3_column_double
218e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
218f0 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 int iCol);.int s
21900 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e qlite3_column_in
21910 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c t(sqlite3_stmt*,
21920 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 int iCol);.sqli
21930 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 te3_int64 sqlite
21940 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 3_column_int64(s
21950 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
21960 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 t iCol);.const u
21970 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 nsigned char *sq
21980 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
21990 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c t(sqlite3_stmt*,
219a0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 int iCol);.cons
219b0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
219c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 column_text16(sq
219d0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
219e0 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 iCol);.int sqli
219f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 te3_column_type(
21a00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
21a10 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 nt iCol);.sqlite
21a20 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 3_value *sqlite3
21a30 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 _column_value(sq
21a40 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
21a50 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 iCol);../*.** C
21a60 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 API3REF: Destroy
21a70 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 A Prepared Stat
21a80 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 ement Object {H1
21a90 33 33 30 30 7d 20 3c 53 37 30 33 30 30 3e 3c 53 3300} <S70300><S
21aa0 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 30100>.**.** The
21ab0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a sqlite3_finaliz
21ac0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 e() function is
21ad0 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 called to delete
21ae0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
21af0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 tement]..** If t
21b00 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 he statement was
21b10 20 65 78 65 63 75 74 65 64 20 73 75 63 63 65 73 executed succes
21b20 73 66 75 6c 6c 79 20 6f 72 20 6e 6f 74 20 65 78 sfully or not ex
21b30 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 ecuted at all, t
21b40 68 65 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b hen.** SQLITE_OK
21b50 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 49 66 is returned. If
21b60 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 execution of th
21b70 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c e statement fail
21b80 65 64 20 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65 ed then an.** [e
21b90 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 rror code] or [e
21ba0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f xtended error co
21bb0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e de] is returned.
21bc0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
21bd0 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 ine can be calle
21be0 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 d at any point d
21bf0 75 72 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 uring the execut
21c00 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 ion of the.** [p
21c10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
21c20 74 5d 2e 20 20 49 66 20 74 68 65 20 76 69 72 74 t]. If the virt
21c30 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20 ual machine has
21c40 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 not.** completed
21c50 20 65 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20 execution when
21c60 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 this routine is
21c70 63 61 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20 called, that is
21c80 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 like.** encounte
21c90 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72 ring an error or
21ca0 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 an [sqlite3_int
21cb0 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75 errupt | interru
21cc0 70 74 5d 2e 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 pt]..** Incomple
21cd0 74 65 20 75 70 64 61 74 65 73 20 6d 61 79 20 62 te updates may b
21ce0 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e e rolled back an
21cf0 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 d transactions c
21d00 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64 65 70 65 anceled,.** depe
21d10 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 nding on the cir
21d20 63 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 cumstances, and
21d30 74 68 65 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f the.** [error co
21d40 64 65 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c de] returned wil
21d50 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f l be [SQLITE_ABO
21d60 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 RT]..**.** Requi
21d70 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 31 rements:.** [H11
21d80 33 30 32 5d 20 5b 48 31 31 33 30 34 5d 0a 2a 2f 302] [H11304].*/
21d90 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e .int sqlite3_fin
21da0 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 alize(sqlite3_st
21db0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a mt *pStmt);../*.
21dc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 ** CAPI3REF: Res
21dd0 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 et A Prepared St
21de0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b atement Object {
21df0 48 31 33 33 33 30 7d 20 3c 53 37 30 33 30 30 3e H13330} <S70300>
21e00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
21e10 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 e3_reset() funct
21e20 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f ion is called to
21e30 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 reset a [prepar
21e40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a ed statement].**
21e50 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 object back to
21e60 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 its initial stat
21e70 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 e, ready to be r
21e80 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41 e-executed..** A
21e90 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ny SQL statement
21ea0 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 variables that
21eb0 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 had values bound
21ec0 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a to them using.*
21ed0 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 * the [sqlite3_b
21ee0 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 ind_blob | sqlit
21ef0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d e3_bind_*() API]
21f00 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 retain their va
21f10 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 lues..** Use [sq
21f20 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 lite3_clear_bind
21f30 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 ings()] to reset
21f40 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a the bindings..*
21f50 2a 0a 2a 2a 20 7b 48 31 31 33 33 32 7d 20 54 68 *.** {H11332} Th
21f60 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 e [sqlite3_reset
21f70 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 (S)] interface r
21f80 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 esets the [prepa
21f90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
21fa0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 61 63 .** bac
21fb0 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 k to the beginni
21fc0 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 ng of its progra
21fd0 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 34 m..**.** {H11334
21fe0 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 } If the most re
21ff0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 cent call to [sq
22000 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 lite3_step(S)] f
22010 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 or the.**
22020 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 [prepared sta
22030 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e tement] S return
22040 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 ed [SQLITE_ROW]
22050 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d or [SQLITE_DONE]
22060 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 ,.** or
22070 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 if [sqlite3_ste
22080 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 p(S)] has never
22090 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c before been call
220a0 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20 20 20 ed on S,.**
220b0 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 then [sqlit
220c0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 e3_reset(S)] ret
220d0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d urns [SQLITE_OK]
220e0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 36 7d ..**.** {H11336}
220f0 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 If the most rec
22100 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ent call to [sql
22110 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f ite3_step(S)] fo
22120 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 r the.**
22130 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 [prepared stat
22140 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 ement] S indicat
22150 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 ed an error, the
22160 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 n.** [s
22170 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d qlite3_reset(S)]
22180 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 returns an appr
22190 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 opriate [error c
221a0 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 ode]..**.** {H11
221b0 33 33 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 338} The [sqlite
221c0 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 3_reset(S)] inte
221d0 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 rface does not c
221e0 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 hange the values
221f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 .** of
22200 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e any [sqlite3_bin
22210 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d d_blob|bindings]
22220 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 on the [prepare
22230 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a d statement] S..
22240 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 */.int sqlite3_r
22250 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d eset(sqlite3_stm
22260 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
22270 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 * CAPI3REF: Crea
22280 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 te Or Redefine S
22290 51 4c 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 QL Functions {H1
222a0 36 31 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 6100} <S20200>.*
222b0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e * KEYWORDS: {fun
222c0 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 ction creation r
222d0 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 outines}.** KEYW
222e0 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 ORDS: {applicati
222f0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 on-defined SQL f
22300 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 unction}.** KEYW
22310 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 ORDS: {applicati
22320 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 on-defined SQL f
22330 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 unctions}.**.**
22340 54 68 65 73 65 20 74 77 6f 20 66 75 6e 63 74 69 These two functi
22350 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c ons (collectivel
22360 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 y known as "func
22370 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f tion creation ro
22380 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 utines").** are
22390 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 used to add SQL
223a0 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 functions or agg
223b0 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 regates or to re
223c0 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 define the behav
223d0 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 ior.** of existi
223e0 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 ng SQL functions
223f0 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 or aggregates.
22400 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 The only differ
22410 65 6e 63 65 20 62 65 74 77 65 65 6e 20 74 68 65 ence between the
22420 0a 2a 2a 20 74 77 6f 20 69 73 20 74 68 61 74 20 .** two is that
22430 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
22440 65 74 65 72 2c 20 74 68 65 20 6e 61 6d 65 20 6f eter, the name o
22450 66 20 74 68 65 20 28 73 63 61 6c 61 72 29 20 66 f the (scalar) f
22460 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 unction or.** ag
22470 67 72 65 67 61 74 65 2c 20 69 73 20 65 6e 63 6f gregate, is enco
22480 64 65 64 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 ded in UTF-8 for
22490 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
224a0 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 function() and U
224b0 54 46 2d 31 36 0a 2a 2a 20 66 6f 72 20 73 71 6c TF-16.** for sql
224c0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
224d0 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 tion16()..**.**
224e0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 The first parame
224f0 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 ter is the [data
22500 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
22510 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 to which the SQ
22520 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 L.** function is
22530 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 49 to be added. I
22540 66 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 f a single progr
22550 61 6d 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 am uses more tha
22560 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a n one database.*
22570 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 6e 74 * connection int
22580 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 ernally, then SQ
22590 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 L functions must
225a0 20 62 65 20 61 64 64 65 64 20 69 6e 64 69 76 69 be added indivi
225b0 64 75 61 6c 6c 79 20 74 6f 0a 2a 2a 20 65 61 63 dually to.** eac
225c0 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 h database conne
225d0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ction..**.** The
225e0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
225f0 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 r is the name of
22600 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
22610 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 n to be created
22620 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e or.** redefined.
22630 20 20 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 The length of
22640 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 the name is limi
22650 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 ted to 255 bytes
22660 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a , exclusive of.*
22670 2a 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 * the zero-termi
22680 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 nator. Note tha
22690 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 t the name lengt
226a0 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79 h limit is in by
226b0 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 tes, not.** char
226c0 61 63 74 65 72 73 2e 20 20 41 6e 79 20 61 74 74 acters. Any att
226d0 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 empt to create a
226e0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 function with a
226f0 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 longer name.**
22700 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b will result in [
22710 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 62 65 SQLITE_ERROR] be
22720 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a ing returned..**
22730 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 70 61 .** The third pa
22740 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a rameter (nArg).*
22750 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 * is the number
22760 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 of arguments tha
22770 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 t the SQL functi
22780 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 on or.** aggrega
22790 74 65 20 74 61 6b 65 73 2e 20 49 66 20 74 68 69 te takes. If thi
227a0 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e s parameter is n
227b0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 egative, then th
227c0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f e SQL function o
227d0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d r.** aggregate m
227e0 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 ay take any numb
227f0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e er of arguments.
22800 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 .**.** The fourt
22810 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 h parameter, eTe
22820 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 xtRep, specifies
22830 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 what.** [SQLITE
22840 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 _UTF8 | text enc
22850 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 oding] this SQL
22860 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 function prefers
22870 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 for.** its para
22880 6d 65 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c meters. Any SQL
22890 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d function implem
228a0 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 entation should
228b0 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a be able to work.
228c0 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46 ** work with UTF
228d0 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 -8, UTF-16le, or
228e0 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 UTF-16be. But
228f0 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 some implementat
22900 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d ions may be.** m
22910 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 ore efficient wi
22920 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 th one encoding
22930 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49 than another. I
22940 74 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a t is allowed to.
22950 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 ** invoke sqlite
22960 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
22970 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 n() or sqlite3_c
22980 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
22990 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 () multiple.** t
229a0 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 imes with the sa
229b0 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 me function but
229c0 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 with different v
229d0 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 alues of eTextRe
229e0 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69 p..** When multi
229f0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ple implementati
22a00 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 ons of the same
22a10 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 function are ava
22a20 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a ilable, SQLite.*
22a30 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 * will pick the
22a40 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 one that involve
22a50 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 s the least amou
22a60 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 nt of data conve
22a70 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 rsion..** If the
22a80 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e re is only a sin
22a90 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 gle implementati
22aa0 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f on which does no
22ab0 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74 t care what text
22ac0 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 .** encoding is
22ad0 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 used, then the f
22ae0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 ourth argument s
22af0 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 hould be [SQLITE
22b00 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 _ANY]..**.** The
22b10 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 fifth parameter
22b20 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 is an arbitrary
22b30 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 pointer. The i
22b40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
22b50 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e the.** function
22b60 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 can gain access
22b70 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 to this pointer
22b80 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
22b90 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a user_data()]..**
22ba0 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e 74 68 2c .** The seventh,
22bb0 20 65 69 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 eighth and nint
22bc0 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 h parameters, xF
22bd0 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 unc, xStep and x
22be0 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f Final, are.** po
22bf0 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 inters to C-lang
22c00 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 uage functions t
22c10 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 hat implement th
22c20 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f e SQL function o
22c30 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 r.** aggregate.
22c40 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e A scalar SQL fun
22c50 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 ction requires a
22c60 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e n implementation
22c70 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a of the xFunc.**
22c80 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 callback only,
22c90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73 68 NULL pointers sh
22ca0 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 61 ould be passed a
22cb0 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 s the xStep and
22cc0 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 xFinal.** parame
22cd0 74 65 72 73 2e 20 41 6e 20 61 67 67 72 65 67 61 ters. An aggrega
22ce0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 te SQL function
22cf0 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c requires an impl
22d00 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 ementation of xS
22d10 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 tep.** and xFina
22d20 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c l and NULL shoul
22d30 64 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 d be passed for
22d40 78 46 75 6e 63 2e 20 54 6f 20 64 65 6c 65 74 65 xFunc. To delete
22d50 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 an existing.**
22d60 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 SQL function or
22d70 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 aggregate, pass
22d80 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 NULL for all thr
22d90 65 65 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c ee function call
22da0 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 backs..**.** It
22db0 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 is permitted to
22dc0 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c register multipl
22dd0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
22de0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a s of the same.**
22df0 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 functions with
22e00 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 the same name bu
22e10 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69 t with either di
22e20 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 ffering numbers
22e30 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 of.** arguments
22e40 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 or differing pre
22e50 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f ferred text enco
22e60 64 69 6e 67 73 2e 20 20 53 51 4c 69 74 65 20 77 dings. SQLite w
22e70 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 ill use.** the i
22e80 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f mplementation mo
22e90 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 st closely match
22ea0 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 es the way in wh
22eb0 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 ich the.** SQL f
22ec0 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e unction is used.
22ed0 20 20 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 A function imp
22ee0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 lementation with
22ef0 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a a non-negative.
22f00 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 ** nArg paramete
22f10 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 r is a better ma
22f20 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 tch than a funct
22f30 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ion implementati
22f40 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 on with.** a neg
22f50 61 74 69 76 65 20 6e 41 72 67 2e 20 20 41 20 66 ative nArg. A f
22f60 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 unction where th
22f70 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 e preferred text
22f80 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 encoding.** mat
22f90 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 ches the databas
22fa0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 e encoding is a
22fb0 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 better.** match
22fc0 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 than a function
22fd0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 where the encodi
22fe0 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e ng is different.
22ff0 20 20 0a 2a 2a 20 41 20 66 75 6e 63 74 69 6f 6e .** A function
23000 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 where the encod
23010 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 ing difference i
23020 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c s between UTF16l
23030 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a e and UTF16be.**
23040 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 is a closer mat
23050 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 ch than a functi
23060 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 on where the enc
23070 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 oding difference
23080 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 is.** between U
23090 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a TF8 and UTF16..*
230a0 2a 0a 2a 2a 20 42 75 69 6c 74 2d 69 6e 20 66 75 *.** Built-in fu
230b0 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f nctions may be o
230c0 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 verloaded by new
230d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
230e0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a ined functions..
230f0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 70 70 ** The first app
23100 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
23110 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 function with a
23120 20 67 69 76 65 6e 20 6e 61 6d 65 20 6f 76 65 72 given name over
23130 72 69 64 65 73 20 61 6c 6c 0a 2a 2a 20 62 75 69 rides all.** bui
23140 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 lt-in functions
23150 69 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 in the same [dat
23160 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
23170 5d 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 ] with the same
23180 6e 61 6d 65 2e 0a 2a 2a 20 53 75 62 73 65 71 75 name..** Subsequ
23190 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d ent application-
231a0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
231b0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 6e 61 s of the same na
231c0 6d 65 20 6f 6e 6c 79 20 6f 76 65 72 72 69 64 65 me only override
231d0 20 0a 2a 2a 20 70 72 69 6f 72 20 61 70 70 6c 69 .** prior appli
231e0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
231f0 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 61 72 unctions that ar
23200 65 20 61 6e 20 65 78 61 63 74 20 6d 61 74 63 68 e an exact match
23210 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 for the.** numb
23220 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 er of parameters
23230 20 61 6e 64 20 70 72 65 66 65 72 72 65 64 20 65 and preferred e
23240 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 41 ncoding..**.** A
23250 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 n application-de
23260 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 fined function i
23270 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 s permitted to c
23280 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c all other.** SQL
23290 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 ite interfaces.
232a0 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 However, such c
232b0 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a alls must not.**
232c0 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 close the datab
232d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e ase connection n
232e0 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 or finalize or r
232f0 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 eset the prepare
23300 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 d.** statement i
23310 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 n which the func
23320 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e tion is running.
23330 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
23340 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 31 30 33 5d nts:.** [H16103]
23350 20 5b 48 31 36 31 30 36 5d 20 5b 48 31 36 31 30 [H16106] [H1610
23360 39 5d 20 5b 48 31 36 31 31 32 5d 20 5b 48 31 36 9] [H16112] [H16
23370 31 31 38 5d 20 5b 48 31 36 31 32 31 5d 20 5b 48 118] [H16121] [H
23380 31 36 31 32 34 5d 20 5b 48 31 36 31 32 37 5d 0a 16124] [H16127].
23390 2a 2a 20 5b 48 31 36 31 33 30 5d 20 5b 48 31 36 ** [H16130] [H16
233a0 31 33 33 5d 20 5b 48 31 36 31 33 36 5d 20 5b 48 133] [H16136] [H
233b0 31 36 31 33 39 5d 20 5b 48 31 36 31 34 32 5d 0a 16139] [H16142].
233c0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 */.int sqlite3_c
233d0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a reate_function(.
233e0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 sqlite3 *db,.
233f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 const char *zFu
23400 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e nctionName,. in
23410 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 t nArg,. int eT
23420 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a extRep,. void *
23430 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 pApp,. void (*x
23440 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f Func)(sqlite3_co
23450 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 ntext*,int,sqlit
23460 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 e3_value**),. v
23470 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c oid (*xStep)(sql
23480 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e ite3_context*,in
23490 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t,sqlite3_value*
234a0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 *),. void (*xFi
234b0 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e nal)(sqlite3_con
234c0 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 text*).);.int sq
234d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
234e0 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 ction16(. sqlit
234f0 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 e3 *db,. const
23500 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e void *zFunctionN
23510 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c ame,. int nArg,
23520 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c . int eTextRep,
23530 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 . void *pApp,.
23540 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 void (*xFunc)(s
23550 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
23560 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 int,sqlite3_valu
23570 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 e**),. void (*x
23580 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f Step)(sqlite3_co
23590 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 ntext*,int,sqlit
235a0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 e3_value**),. v
235b0 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 oid (*xFinal)(sq
235c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a lite3_context*).
235d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
235e0 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e EF: Text Encodin
235f0 67 73 20 7b 48 31 30 32 36 37 7d 20 3c 53 35 30 gs {H10267} <S50
23600 32 30 30 3e 20 3c 48 31 36 31 30 30 3e 0a 2a 2a 200> <H16100>.**
23610 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 .** These consta
23620 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 nt define intege
23630 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 r codes that rep
23640 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f resent the vario
23650 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 us.** text encod
23660 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 ings supported b
23670 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 y SQLite..*/.#de
23680 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 fine SQLITE_UTF8
23690 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 1.#de
236a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 fine SQLITE_UTF1
236b0 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 6LE 2.#de
236c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 fine SQLITE_UTF1
236d0 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 6BE 3.#de
236e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 fine SQLITE_UTF1
236f0 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 6 4
23700 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 /* Use native by
23710 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 te order */.#def
23720 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 ine SQLITE_ANY
23730 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 5 /
23740 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 * sqlite3_create
23750 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a _function only *
23760 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
23770 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 _UTF16_ALIGNED
23780 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 8 /* sqlite3_
23790 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
237a0 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 only */../*.**
237b0 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 CAPI3REF: Deprec
237c0 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a ated Functions.*
237d0 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a * DEPRECATED.**.
237e0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f ** These functio
237f0 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 ns are [deprecat
23800 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 ed]. In order t
23810 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 o maintain.** ba
23820 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 ckwards compatib
23830 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 ility with older
23840 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e code, these fun
23850 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 ctions continue
23860 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 .** to be suppor
23870 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e ted. However, n
23880 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 ew applications
23890 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 should avoid.**
238a0 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 the use of these
238b0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 functions. To
238c0 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 help encourage p
238d0 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a eople to avoid.*
238e0 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 * using these fu
238f0 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 nctions, we are
23900 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c not going to tel
23910 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 l you what they
23920 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 do..*/.#ifndef S
23930 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 QLITE_OMIT_DEPRE
23940 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 CATED.SQLITE_DEP
23950 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 RECATED int sqli
23960 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
23970 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 unt(sqlite3_cont
23980 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 ext*);.SQLITE_DE
23990 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c PRECATED int sql
239a0 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c ite3_expired(sql
239b0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c ite3_stmt*);.SQL
239c0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 ITE_DEPRECATED i
239d0 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 nt sqlite3_trans
239e0 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c fer_bindings(sql
239f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 ite3_stmt*, sqli
23a00 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 te3_stmt*);.SQLI
23a10 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e TE_DEPRECATED in
23a20 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c t sqlite3_global
23a30 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a _recover(void);.
23a40 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 SQLITE_DEPRECATE
23a50 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 D void sqlite3_t
23a60 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f hread_cleanup(vo
23a70 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 id);.SQLITE_DEPR
23a80 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 ECATED int sqlit
23a90 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 e3_memory_alarm(
23aa0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 void(*)(void*,sq
23ab0 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 lite3_int64,int)
23ac0 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 ,void*,sqlite3_i
23ad0 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f nt64);.#endif../
23ae0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
23af0 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e btaining SQL Fun
23b00 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 ction Parameter
23b10 56 61 6c 75 65 73 20 7b 48 31 35 31 30 30 7d 20 Values {H15100}
23b20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S20200>.**.** T
23b30 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d he C-language im
23b40 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
23b50 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e SQL functions an
23b60 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 d aggregates use
23b70 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 s.** this set of
23b80 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 interface routi
23b90 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 nes to access th
23ba0 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 e parameter valu
23bb0 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e es on.** the fun
23bc0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 ction or aggrega
23bd0 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 te..**.** The xF
23be0 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 unc (for scalar
23bf0 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 functions) or xS
23c00 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 tep (for aggrega
23c10 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a tes) parameters.
23c20 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ** to [sqlite3_c
23c30 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
23c40 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 ] and [sqlite3_c
23c50 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
23c60 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 ()].** define ca
23c70 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 llbacks that imp
23c80 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 lement the SQL f
23c90 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 unctions and agg
23ca0 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 regates..** The
23cb0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 4th parameter to
23cc0 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 these callbacks
23cd0 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 is an array of
23ce0 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b pointers to.** [
23cf0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
23d00 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 3_value] objects
23d10 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 . There is one
23d20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 [sqlite3_value]
23d30 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 object for.** ea
23d40 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 ch parameter to
23d50 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
23d60 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 . These routine
23d70 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a s are used to.**
23d80 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 extract values
23d90 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 from the [sqlite
23da0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 3_value] objects
23db0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f ..**.** These ro
23dc0 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 utines work only
23dd0 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 with [protected
23de0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
23df0 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 objects..** Any
23e00 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 attempt to use t
23e10 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e hese routines on
23e20 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 an [unprotected
23e30 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a sqlite3_value].
23e40 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 ** object result
23e50 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 s in undefined b
23e60 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 ehavior..**.** T
23e70 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f hese routines wo
23e80 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 rk just like the
23e90 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b corresponding [
23ea0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 column access fu
23eb0 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 nctions].** exce
23ec0 70 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72 pt that these r
23ed0 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 outines take a s
23ee0 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 ingle [protected
23ef0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
23f00 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 object.** pointe
23f10 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b r instead of a [
23f20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 sqlite3_stmt*] p
23f30 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e ointer and an in
23f40 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d teger column num
23f50 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ber..**.** The s
23f60 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
23f70 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 t16() interface
23f80 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 extracts a UTF-1
23f90 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 6 string.** in t
23fa0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f he native byte-o
23fb0 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 rder of the host
23fc0 20 6d 61 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a machine. The.*
23fd0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f * sqlite3_value_
23fe0 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 text16be() and s
23ff0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
24000 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 t16le() interfac
24010 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 es.** extract UT
24020 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 F-16 strings as
24030 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c big-endian and l
24040 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 ittle-endian res
24050 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a pectively..**.**
24060 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c The sqlite3_val
24070 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 ue_numeric_type(
24080 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 ) interface atte
24090 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a mpts to apply.**
240a0 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 numeric affinit
240b0 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 y to the value.
240c0 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 This means that
240d0 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a an attempt is.*
240e0 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 * made to conver
240f0 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 t the value to a
24100 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f n integer or flo
24110 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 ating point. If
24120 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 .** such a conve
24130 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c rsion is possibl
24140 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f e without loss o
24150 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 f information (i
24160 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 n other.** words
24170 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 , if the value i
24180 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 s a string that
24190 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d looks like a num
241a0 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ber).** then the
241b0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 conversion is p
241c0 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 erformed. Other
241d0 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 wise no conversi
241e0 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 on occurs..** Th
241f0 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 e [SQLITE_INTEGE
24200 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 R | datatype] af
24210 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 ter conversion i
24220 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
24230 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 * Please pay par
24240 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f ticular attentio
24250 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 n to the fact th
24260 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 at the pointer r
24270 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 eturned.** from
24280 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 [sqlite3_value_b
24290 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 lob()], [sqlite3
242a0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 _value_text()],
242b0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 or.** [sqlite3_v
242c0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 alue_text16()] c
242d0 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 an be invalidate
242e0 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e d by a subsequen
242f0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 t call to.** [sq
24300 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 lite3_value_byte
24310 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 s()], [sqlite3_v
24320 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c alue_bytes16()],
24330 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
24340 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b text()],.** or [
24350 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
24360 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 xt16()]..**.** T
24370 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 hese routines mu
24380 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f st be called fro
24390 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 m the same threa
243a0 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 d as.** the SQL
243b0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 function that su
243c0 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 pplied the [sqli
243d0 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 te3_value*] para
243e0 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 meters..**.** Re
243f0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
24400 48 31 35 31 30 33 5d 20 5b 48 31 35 31 30 36 5d H15103] [H15106]
24410 20 5b 48 31 35 31 30 39 5d 20 5b 48 31 35 31 31 [H15109] [H1511
24420 32 5d 20 5b 48 31 35 31 31 35 5d 20 5b 48 31 35 2] [H15115] [H15
24430 31 31 38 5d 20 5b 48 31 35 31 32 31 5d 20 5b 48 118] [H15121] [H
24440 31 35 31 32 34 5d 0a 2a 2a 20 5b 48 31 35 31 32 15124].** [H1512
24450 37 5d 20 5b 48 31 35 31 33 30 5d 20 5b 48 31 35 7] [H15130] [H15
24460 31 33 33 5d 20 5b 48 31 35 31 33 36 5d 0a 2a 2f 133] [H15136].*/
24470 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
24480 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 ite3_value_blob(
24490 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
244a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c .int sqlite3_val
244b0 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 ue_bytes(sqlite3
244c0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 _value*);.int sq
244d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 lite3_value_byte
244e0 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 s16(sqlite3_valu
244f0 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 e*);.double sqli
24500 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 te3_value_double
24510 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
24520 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 ;.int sqlite3_va
24530 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f lue_int(sqlite3_
24540 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 value*);.sqlite3
24550 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 _int64 sqlite3_v
24560 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 alue_int64(sqlit
24570 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 e3_value*);.cons
24580 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 t unsigned char
24590 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 *sqlite3_value_t
245a0 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 ext(sqlite3_valu
245b0 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 e*);.const void
245c0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 *sqlite3_value_t
245d0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 ext16(sqlite3_va
245e0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 lue*);.const voi
245f0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 d *sqlite3_value
24600 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 _text16le(sqlite
24610 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 3_value*);.const
24620 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 void *sqlite3_v
24630 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 alue_text16be(sq
24640 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 lite3_value*);.i
24650 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt sqlite3_value
24660 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 _type(sqlite3_va
24670 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 lue*);.int sqlit
24680 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 e3_value_numeric
24690 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 _type(sqlite3_va
246a0 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 lue*);../*.** CA
246b0 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 PI3REF: Obtain A
246c0 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f ggregate Functio
246d0 6e 20 43 6f 6e 74 65 78 74 20 7b 48 31 36 32 31 n Context {H1621
246e0 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 0} <S20200>.**.*
246f0 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 * The implementa
24700 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 67 61 74 tion of aggregat
24710 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 e SQL functions
24720 75 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 use this routine
24730 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20 to allocate.**
24740 61 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 a structure for
24750 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 storing their st
24760 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 ate..**.** The f
24770 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 irst time the sq
24780 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
24790 63 6f 6e 74 65 78 74 28 29 20 72 6f 75 74 69 6e context() routin
247a0 65 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 e is called for
247b0 61 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 a.** particular
247c0 61 67 67 72 65 67 61 74 65 2c 20 53 51 4c 69 74 aggregate, SQLit
247d0 65 20 61 6c 6c 6f 63 61 74 65 73 20 6e 42 79 74 e allocates nByt
247e0 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 es of memory, ze
247f0 72 6f 65 73 20 6f 75 74 20 74 68 61 74 0a 2a 2a roes out that.**
24800 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 memory, and ret
24810 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
24820 6f 20 69 74 2e 20 4f 6e 20 73 65 63 6f 6e 64 20 o it. On second
24830 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 and subsequent c
24840 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 alls to.** sqlit
24850 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
24860 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 text() for the s
24870 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 ame aggregate fu
24880 6e 63 74 69 6f 6e 20 69 6e 64 65 78 2c 0a 2a 2a nction index,.**
24890 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 the same buffer
248a0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 54 68 is returned. Th
248b0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
248c0 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 of the aggregat
248d0 65 20 63 61 6e 20 75 73 65 0a 2a 2a 20 74 68 65 e can use.** the
248e0 20 72 65 74 75 72 6e 65 64 20 62 75 66 66 65 72 returned buffer
248f0 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 65 20 64 to accumulate d
24900 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 ata..**.** SQLit
24910 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 e automatically
24920 66 72 65 65 73 20 74 68 65 20 61 6c 6c 6f 63 61 frees the alloca
24930 74 65 64 20 62 75 66 66 65 72 20 77 68 65 6e 20 ted buffer when
24940 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a the aggregate.**
24950 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 query concludes
24960 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 ..**.** The firs
24970 74 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 t parameter shou
24980 6c 64 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 ld be a copy of
24990 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
249a0 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 context | SQL fu
249b0 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 nction context]
249c0 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73 that is the firs
249d0 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 t parameter.** t
249e0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 o the callback r
249f0 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c outine that impl
24a00 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 ements the aggre
24a10 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a gate function..*
24a20 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
24a30 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 e must be called
24a40 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 from the same t
24a50 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a hread in which.*
24a60 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 * the aggregate
24a70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 SQL function is
24a80 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 running..**.** R
24a90 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
24aa0 5b 48 31 36 32 31 31 5d 20 5b 48 31 36 32 31 33 [H16211] [H16213
24ab0 5d 20 5b 48 31 36 32 31 35 5d 20 5b 48 31 36 32 ] [H16215] [H162
24ac0 31 37 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 17].*/.void *sql
24ad0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
24ae0 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 ontext(sqlite3_c
24af0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 ontext*, int nBy
24b00 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tes);../*.** CAP
24b10 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 I3REF: User Data
24b20 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b For Functions {
24b30 48 31 36 32 34 30 7d 20 3c 53 32 30 32 30 30 3e H16240} <S20200>
24b40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
24b50 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 e3_user_data() i
24b60 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
24b70 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 a copy of.** th
24b80 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 e pointer that w
24b90 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61 as the pUserData
24ba0 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 parameter (the
24bb0 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 5th parameter).*
24bc0 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 * of the [sqlite
24bd0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
24be0 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c n()].** and [sql
24bf0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
24c00 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e tion16()] routin
24c10 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c es that original
24c20 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 ly.** registered
24c30 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
24c40 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f defined functio
24c50 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 n. {END}.**.** T
24c60 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 his routine must
24c70 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 be called from
24c80 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 the same thread
24c90 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 in which.** the
24ca0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
24cb0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 ned function is
24cc0 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 running..**.** R
24cd0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
24ce0 5b 48 31 36 32 34 33 5d 0a 2a 2f 0a 76 6f 69 64 [H16243].*/.void
24cf0 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 *sqlite3_user_d
24d00 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ata(sqlite3_cont
24d10 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ext*);../*.** CA
24d20 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 PI3REF: Database
24d30 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 Connection For
24d40 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32 35 Functions {H1625
24d50 30 7d 20 3c 53 36 30 36 30 30 3e 3c 53 32 30 32 0} <S60600><S202
24d60 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 00>.**.** The sq
24d70 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 lite3_context_db
24d80 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 _handle() interf
24d90 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f ace returns a co
24da0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 py of.** the poi
24db0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 nter to the [dat
24dc0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
24dd0 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d ] (the 1st param
24de0 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 eter).** of the
24df0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
24e00 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 function()].** a
24e10 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 nd [sqlite3_crea
24e20 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d te_function16()]
24e30 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f routines that o
24e40 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 riginally.** reg
24e50 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c istered the appl
24e60 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 ication defined
24e70 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 function..**.**
24e80 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
24e90 20 5b 48 31 36 32 35 33 5d 0a 2a 2f 0a 73 71 6c [H16253].*/.sql
24ea0 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f ite3 *sqlite3_co
24eb0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 ntext_db_handle(
24ec0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
24ed0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
24ee0 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 EF: Function Aux
24ef0 69 6c 69 61 72 79 20 44 61 74 61 20 7b 48 31 36 iliary Data {H16
24f00 32 37 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 270} <S20200>.**
24f10 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e .** The followin
24f20 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 g two functions
24f30 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73 may be used by s
24f40 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 calar SQL functi
24f50 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 ons to.** associ
24f60 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 ate metadata wit
24f70 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 h argument value
24f80 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 s. If the same v
24f90 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 alue is passed t
24fa0 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e o.** multiple in
24fb0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 vocations of the
24fc0 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 same SQL functi
24fd0 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 on during query
24fe0 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 execution, under
24ff0 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 .** some circums
25000 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 tances the assoc
25010 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d iated metadata m
25020 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e ay be preserved.
25030 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 This may.** be
25040 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c used, for exampl
25050 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 e, to add a regu
25060 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d lar-expression m
25070 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a atching scalar.*
25080 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 * function. The
25090 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e compiled version
250a0 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 of the regular
250b0 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 expression is st
250c0 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 ored as.** metad
250d0 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 ata associated w
250e0 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 ith the SQL valu
250f0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 e passed as the
25100 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 regular expressi
25110 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 on.** pattern.
25120 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 The compiled reg
25130 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 ular expression
25140 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e can be reused on
25150 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 multiple.** inv
25160 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 ocations of the
25170 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f same function so
25180 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e that the origin
25190 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e al pattern strin
251a0 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 g.** does not ne
251b0 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 ed to be recompi
251c0 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f led on each invo
251d0 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 cation..**.** Th
251e0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 e sqlite3_get_au
251f0 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 xdata() interfac
25200 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e e returns a poin
25210 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 ter to the metad
25220 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 ata.** associate
25230 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 d by the sqlite3
25240 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 _set_auxdata() f
25250 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 unction with the
25260 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a Nth argument.**
25270 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 value to the ap
25280 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
25290 64 20 66 75 6e 63 74 69 6f 6e 2e 20 49 66 20 6e d function. If n
252a0 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 o metadata has b
252b0 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e een ever.** been
252c0 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 set for the Nth
252d0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 argument of the
252e0 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 function, or if
252f0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 the correspondi
25300 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 ng.** function p
25310 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 arameter has cha
25320 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d nged since the m
25330 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 eta-data was set
25340 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 ,.** then sqlite
25350 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 3_get_auxdata()
25360 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 returns a NULL p
25370 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 ointer..**.** Th
25380 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 e sqlite3_set_au
25390 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 xdata() interfac
253a0 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 e saves the meta
253b0 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 data.** pointed
253c0 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61 to by its 3rd pa
253d0 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d rameter as the m
253e0 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 etadata for the
253f0 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 N-th.** argument
25400 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 of the applicat
25410 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
25420 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e tion. Subsequen
25430 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 t.** calls to sq
25440 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 lite3_get_auxdat
25450 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e a() might return
25460 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 this data, if i
25470 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 t has.** not bee
25480 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 n destroyed..**
25490 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c If it is not NUL
254a0 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 L, SQLite will i
254b0 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 nvoke the destru
254c0 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e ctor.** function
254d0 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 given by the 4t
254e0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 h parameter to s
254f0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 qlite3_set_auxda
25500 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d ta() on.** the m
25510 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68 65 etadata when the
25520 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 corresponding f
25530 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 unction paramete
25540 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 r changes.** or
25550 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 when the SQL sta
25560 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 tement completes
25570 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 , whichever come
25580 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 s first..**.** S
25590 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f QLite is free to
255a0 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 call the destru
255b0 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 ctor and drop me
255c0 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a tadata on any.**
255d0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e parameter of an
255e0 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e y function at an
255f0 79 20 74 69 6d 65 2e 20 20 54 68 65 20 6f 6e 6c y time. The onl
25600 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 20 74 y guarantee is t
25610 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 hat.** the destr
25620 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 uctor will be ca
25630 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 lled before the
25640 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 6f 70 metadata is drop
25650 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 ped..**.** In pr
25660 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 actice, metadata
25670 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65 is preserved be
25680 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 tween function c
25690 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 alls for.** expr
256a0 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 essions that are
256b0 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d constant at com
256c0 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 pile time. This
256d0 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c includes literal
256e0 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 53 .** values and S
256f0 51 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a QL variables..**
25700 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
25710 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 es must be calle
25720 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 d from the same
25730 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a thread in which.
25740 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 ** the SQL funct
25750 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a ion is running..
25760 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
25770 74 73 3a 0a 2a 2a 20 5b 48 31 36 32 37 32 5d 20 ts:.** [H16272]
25780 5b 48 31 36 32 37 34 5d 20 5b 48 31 36 32 37 36 [H16274] [H16276
25790 5d 20 5b 48 31 36 32 37 37 5d 20 5b 48 31 36 32 ] [H16277] [H162
257a0 37 38 5d 20 5b 48 31 36 32 37 39 5d 0a 2a 2f 0a 78] [H16279].*/.
257b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 void *sqlite3_ge
257c0 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 t_auxdata(sqlite
257d0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 3_context*, int
257e0 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 N);.void sqlite3
257f0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c _set_auxdata(sql
25800 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 ite3_context*, i
25810 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 nt N, void*, voi
25820 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a d (*)(void*));..
25830 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
25840 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e Constants Defin
25850 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 ing Special Dest
25860 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 20 ructor Behavior
25870 7b 48 31 30 32 38 30 7d 20 3c 53 33 30 31 30 30 {H10280} <S30100
25880 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 >.**.** These ar
25890 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 e special values
258a0 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 for the destruc
258b0 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73 tor that is pass
258c0 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 ed in as the.**
258d0 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 final argument t
258e0 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 o routines like
258f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
25900 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74 68 65 blob()]. If the
25910 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 destructor.** a
25920 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 rgument is SQLIT
25930 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 E_STATIC, it mea
25940 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 ns that the cont
25950 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 ent pointer is c
25960 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 onstant.** and w
25970 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 ill never change
25980 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e . It does not n
25990 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f eed to be destro
259a0 79 65 64 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c yed. The.** SQL
259b0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 ITE_TRANSIENT va
259c0 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 lue means that t
259d0 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 he content will
259e0 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e likely change in
259f0 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 .** the near fut
25a00 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c ure and that SQL
25a10 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 ite should make
25a20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 its own private
25a30 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 copy of.** the c
25a40 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 ontent before re
25a50 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 turning..**.** T
25a60 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 he typedef is ne
25a70 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 cessary to work
25a80 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 around problems
25a90 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b in certain.** C+
25aa0 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 + compilers. Se
25ab0 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a e ticket #2191..
25ac0 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 */.typedef void
25ad0 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 (*sqlite3_destru
25ae0 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a ctor_type)(void*
25af0 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 );.#define SQLIT
25b00 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 E_STATIC ((
25b10 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 sqlite3_destruct
25b20 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 or_type)0).#defi
25b30 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 ne SQLITE_TRANSI
25b40 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f ENT ((sqlite3_
25b50 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 destructor_type)
25b60 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 -1)../*.** CAPI3
25b70 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 REF: Setting The
25b80 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 Result Of An SQ
25b90 4c 20 46 75 6e 63 74 69 6f 6e 20 7b 48 31 36 34 L Function {H164
25ba0 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 00} <S20200>.**.
25bb0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
25bc0 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68 s are used by th
25bd0 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 e xFunc or xFina
25be0 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 l callbacks that
25bf0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 .** implement SQ
25c00 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 L functions and
25c10 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 aggregates. See
25c20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 .** [sqlite3_cre
25c30 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 ate_function()]
25c40 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 and [sqlite3_cre
25c50 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 ate_function16()
25c60 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f ].** for additio
25c70 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e nal information.
25c80 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e .**.** These fun
25c90 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 ctions work very
25ca0 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b much like the [
25cb0 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e parameter bindin
25cc0 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 g] family of.**
25cd0 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 functions used t
25ce0 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f o bind values to
25cf0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 host parameters
25d00 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 in prepared sta
25d10 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 tements..** Refe
25d20 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 r to the [SQL pa
25d30 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e rameter] documen
25d40 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 tation for addit
25d50 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f ional informatio
25d60 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c n..**.** The sql
25d70 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 ite3_result_blob
25d80 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 () interface set
25d90 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f s the result fro
25da0 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 m.** an applicat
25db0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
25dc0 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 tion to be the B
25dd0 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e LOB whose conten
25de0 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 t is pointed.**
25df0 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 to by the second
25e00 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 parameter and w
25e10 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 hich is N bytes
25e20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 long where N is
25e30 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 the.** third par
25e40 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 ameter..**.** Th
25e50 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
25e60 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 _zeroblob() inte
25e70 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72 rfaces set the r
25e80 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 esult of.** the
25e90 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
25ea0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 ned function to
25eb0 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 be a BLOB contai
25ec0 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a ning all zero.**
25ed0 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 bytes and N byt
25ee0 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 es in size, wher
25ef0 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 e N is the value
25f00 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 of the 2nd para
25f10 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 meter..**.** The
25f20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
25f30 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 double() interfa
25f40 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 ce sets the resu
25f50 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 lt from.** an ap
25f60 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
25f70 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 d function to be
25f80 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e a floating poin
25f90 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 t value specifie
25fa0 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 d.** by its 2nd
25fb0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 argument..**.**
25fc0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
25fd0 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 lt_error() and s
25fe0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
25ff0 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e ror16() function
26000 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 s.** cause the i
26010 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 mplemented SQL f
26020 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 unction to throw
26030 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a an exception..*
26040 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 * SQLite uses th
26050 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 e string pointed
26060 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e to by the.** 2n
26070 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 d parameter of s
26080 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
26090 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 ror() or sqlite3
260a0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
260b0 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 ).** as the text
260c0 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 of an error mes
260d0 73 61 67 65 2e 20 20 53 51 4c 69 74 65 20 69 6e sage. SQLite in
260e0 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72 terprets the err
260f0 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 or.** message st
26100 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 ring from sqlite
26110 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 3_result_error()
26120 20 61 73 20 55 54 46 2d 38 2e 20 53 51 4c 69 74 as UTF-8. SQLit
26130 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 e.** interprets
26140 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 the string from
26150 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
26160 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d rror16() as UTF-
26170 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 16 in native.**
26180 62 79 74 65 20 6f 72 64 65 72 2e 20 20 49 66 20 byte order. If
26190 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
261a0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 ter to sqlite3_r
261b0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a esult_error().**
261c0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 or sqlite3_resu
261d0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 lt_error16() is
261e0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 negative then SQ
261f0 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 Lite takes as th
26200 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 e error.** messa
26210 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 ge all text up t
26220 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 hrough the first
26230 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e zero character.
26240 0a 2a 2a 20 49 66 20 74 68 65 20 74 68 69 72 64 .** If the third
26250 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
26260 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
26270 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 or() or.** sqlit
26280 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 e3_result_error1
26290 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 6() is non-negat
262a0 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 ive then SQLite
262b0 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a takes that many.
262c0 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 ** bytes (not ch
262d0 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 aracters) from t
262e0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 he 2nd parameter
262f0 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 as the error me
26300 73 73 61 67 65 2e 0a 2a 2a 20 54 68 65 20 73 71 ssage..** The sq
26310 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
26320 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 or() and sqlite3
26330 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
26340 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 ).** routines ma
26350 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 ke a private cop
26360 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d y of the error m
26370 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f essage text befo
26380 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 re.** they retur
26390 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 n. Hence, the c
263a0 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 alling function
263b0 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f can deallocate o
263c0 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 r.** modify the
263d0 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 text after they
263e0 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 return without h
263f0 61 72 6d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 arm..** The sqli
26400 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
26410 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e _code() function
26420 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 changes the err
26430 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 or code.** retur
26440 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 ned by SQLite as
26450 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 a result of an
26460 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 error in a funct
26470 69 6f 6e 2e 20 20 42 79 20 64 65 66 61 75 6c 74 ion. By default
26480 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 ,.** the error c
26490 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 ode is SQLITE_ER
264a0 52 4f 52 2e 20 20 41 20 73 75 62 73 65 71 75 65 ROR. A subseque
264b0 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 nt call to sqlit
264c0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
264d0 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f ).** or sqlite3_
264e0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 result_error16()
264f0 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f resets the erro
26500 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 r code to SQLITE
26510 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 _ERROR..**.** Th
26520 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
26530 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 _toobig() interf
26540 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 ace causes SQLit
26550 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 e to throw an er
26560 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e ror.** indicatin
26570 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 g that a string
26580 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f or BLOB is to lo
26590 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e ng to represent.
265a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
265b0 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 e3_result_nomem(
265c0 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 ) interface caus
265d0 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 es SQLite to thr
265e0 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 ow an error.** i
265f0 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 ndicating that a
26600 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
26610 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a on failed..**.**
26620 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 The sqlite3_res
26630 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 ult_int() interf
26640 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 ace sets the ret
26650 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 urn value.** of
26660 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
26670 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
26680 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 to be the 32-bi
26690 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 t signed integer
266a0 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 .** value given
266b0 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d in the 2nd argum
266c0 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ent..** The sqli
266d0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 te3_result_int64
266e0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 () interface set
266f0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c s the return val
26700 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 ue.** of the app
26710 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
26720 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
26730 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 the 64-bit signe
26740 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c d integer.** val
26750 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 ue given in the
26760 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 2nd argument..**
26770 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
26780 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e result_null() in
26790 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 terface sets the
267a0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a return value.**
267b0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 of the applicat
267c0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
267d0 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e tion to be NULL.
267e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
267f0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 e3_result_text()
26800 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 , sqlite3_result
26810 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 _text16(),.** sq
26820 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
26830 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c t16le(), and sql
26840 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
26850 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 16be() interface
26860 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 s.** set the ret
26870 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 urn value of the
26880 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
26890 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f ined function to
268a0 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 be.** a text st
268b0 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 ring which is re
268c0 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 presented as UTF
268d0 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 -8, UTF-16 nativ
268e0 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a e byte order,.**
268f0 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 UTF-16 little e
26900 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 ndian, or UTF-16
26910 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 big endian, res
26920 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 53 51 pectively..** SQ
26930 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 Lite takes the t
26940 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 ext result from
26950 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
26960 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 from.** the 2nd
26970 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 parameter of the
26980 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
26990 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 text* interfaces
269a0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 ..** If the 3rd
269b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
269c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
269d0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 text* interfaces
269e0 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c .** is negative,
269f0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b then SQLite tak
26a00 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 es result text f
26a10 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 rom the 2nd para
26a20 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 meter.** through
26a30 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 the first zero
26a40 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 character..** If
26a50 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 the 3rd paramet
26a60 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 er to the sqlite
26a70 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 3_result_text* i
26a80 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 nterfaces.** is
26a90 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 non-negative, th
26aa0 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 en as many bytes
26ab0 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 (not characters
26ac0 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a ) of the text.**
26ad0 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 pointed to by t
26ae0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 he 2nd parameter
26af0 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 are taken as th
26b00 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
26b10 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f fined.** functio
26b20 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 n result..** If
26b30 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 the 4th paramete
26b40 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 r to the sqlite3
26b50 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e _result_text* in
26b60 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 terfaces.** or s
26b70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
26b80 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c ob is a non-NULL
26b90 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 pointer, then S
26ba0 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 QLite calls that
26bb0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 .** function as
26bc0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f the destructor o
26bd0 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c n the text or BL
26be0 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 OB result when i
26bf0 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 t has.** finishe
26c00 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 d using that res
26c10 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 ult..** If the 4
26c20 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
26c30 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 the sqlite3_resu
26c40 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 lt_text* interfa
26c50 63 65 73 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 ces or.** sqlite
26c60 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 3_result_blob is
26c70 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e the special con
26c80 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 stant SQLITE_STA
26c90 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 TIC, then SQLite
26ca0 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 .** assumes that
26cb0 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f the text or BLO
26cc0 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 B result is in c
26cd0 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e onstant space an
26ce0 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f d does not.** co
26cf0 70 79 20 74 68 65 20 69 74 20 6f 72 20 63 61 6c py the it or cal
26d00 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 77 l a destructor w
26d10 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 hen it has finis
26d20 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 hed using that r
26d30 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 esult..** If the
26d40 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 4th parameter t
26d50 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 o the sqlite3_re
26d60 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 sult_text* inter
26d70 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 faces.** or sqli
26d80 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 te3_result_blob
26d90 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 is the special c
26da0 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 onstant SQLITE_T
26db0 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e RANSIENT.** then
26dc0 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 SQLite makes a
26dd0 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 copy of the resu
26de0 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 lt into space ob
26df0 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 tained from.** f
26e00 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c rom [sqlite3_mal
26e10 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 loc()] before it
26e20 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 returns..**.**
26e30 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
26e40 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 lt_value() inter
26e50 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 face sets the re
26e60 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 sult of.** the a
26e70 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
26e80 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ed function to b
26e90 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 e a copy the.**
26ea0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c [unprotected sql
26eb0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
26ec0 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20 ct specified by
26ed0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
26ee0 72 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 r. The.** sqlit
26ef0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 e3_result_value(
26f00 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 ) interface make
26f10 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 s a copy of the
26f20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a [sqlite3_value].
26f30 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b ** so that the [
26f40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 sqlite3_value] s
26f50 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 pecified in the
26f60 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 parameter may ch
26f70 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 ange or.** be de
26f80 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 allocated after
26f90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 sqlite3_result_v
26fa0 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 alue() returns w
26fb0 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 ithout harm..**
26fc0 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c A [protected sql
26fd0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
26fe0 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 ct may always be
26ff0 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a used where an.*
27000 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 * [unprotected s
27010 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
27020 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64 ject is required
27030 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b , so either.** k
27040 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f ind of [sqlite3_
27050 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 value] object ca
27060 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74 n be used with t
27070 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a his interface..*
27080 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f *.** If these ro
27090 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 utines are calle
270a0 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 d from within th
270b0 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 e different thre
270c0 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f ad.** than the o
270d0 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 ne containing th
270e0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
270f0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 fined function t
27100 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 hat received.**
27110 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e the [sqlite3_con
27120 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 text] pointer, t
27130 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 he results are u
27140 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
27150 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
27160 20 5b 48 31 36 34 30 33 5d 20 5b 48 31 36 34 30 [H16403] [H1640
27170 36 5d 20 5b 48 31 36 34 30 39 5d 20 5b 48 31 36 6] [H16409] [H16
27180 34 31 32 5d 20 5b 48 31 36 34 31 35 5d 20 5b 48 412] [H16415] [H
27190 31 36 34 31 38 5d 20 5b 48 31 36 34 32 31 5d 20 16418] [H16421]
271a0 5b 48 31 36 34 32 34 5d 0a 2a 2a 20 5b 48 31 36 [H16424].** [H16
271b0 34 32 37 5d 20 5b 48 31 36 34 33 30 5d 20 5b 48 427] [H16430] [H
271c0 31 36 34 33 33 5d 20 5b 48 31 36 34 33 36 5d 20 16433] [H16436]
271d0 5b 48 31 36 34 33 39 5d 20 5b 48 31 36 34 34 32 [H16439] [H16442
271e0 5d 20 5b 48 31 36 34 34 35 5d 20 5b 48 31 36 34 ] [H16445] [H164
271f0 34 38 5d 0a 2a 2a 20 5b 48 31 36 34 35 31 5d 20 48].** [H16451]
27200 5b 48 31 36 34 35 34 5d 20 5b 48 31 36 34 35 37 [H16454] [H16457
27210 5d 20 5b 48 31 36 34 36 30 5d 20 5b 48 31 36 34 ] [H16460] [H164
27220 36 33 5d 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 63].*/.void sqli
27230 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 te3_result_blob(
27240 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
27250 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 , const void*, i
27260 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 nt, void(*)(void
27270 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 *));.void sqlite
27280 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 3_result_double(
27290 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
272a0 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 , double);.void
272b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
272c0 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e rror(sqlite3_con
272d0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 text*, const cha
272e0 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 r*, int);.void s
272f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
27300 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f ror16(sqlite3_co
27310 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f ntext*, const vo
27320 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 id*, int);.void
27330 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
27340 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 rror_toobig(sqli
27350 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 te3_context*);.v
27360 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
27370 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 lt_error_nomem(s
27380 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 qlite3_context*)
27390 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
273a0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 esult_error_code
273b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
273c0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 *, int);.void sq
273d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 lite3_result_int
273e0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
273f0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 *, int);.void sq
27400 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 lite3_result_int
27410 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 64(sqlite3_conte
27420 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 xt*, sqlite3_int
27430 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 64);.void sqlite
27440 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 3_result_null(sq
27450 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b lite3_context*);
27460 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
27470 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 sult_text(sqlite
27480 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 3_context*, cons
27490 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f t char*, int, vo
274a0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 id(*)(void*));.v
274b0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
274c0 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 lt_text16(sqlite
274d0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 3_context*, cons
274e0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f t void*, int, vo
274f0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 id(*)(void*));.v
27500 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
27510 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 lt_text16le(sqli
27520 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f te3_context*, co
27530 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 nst void*, int,v
27540 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
27550 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
27560 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c ult_text16be(sql
27570 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 ite3_context*, c
27580 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c onst void*, int,
27590 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
275a0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
275b0 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 sult_value(sqlit
275c0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c e3_context*, sql
275d0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f ite3_value*);.vo
275e0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
275f0 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 t_zeroblob(sqlit
27600 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 e3_context*, int
27610 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 n);../*.** CAPI
27620 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 3REF: Define New
27630 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 Collating Seque
27640 6e 63 65 73 20 7b 48 31 36 36 30 30 7d 20 3c 53 nces {H16600} <S
27650 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20300>.**.** The
27660 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 se functions are
27670 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77 used to add new
27680 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 collation seque
27690 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b nces to the.** [
276a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
276b0 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 ion] specified a
276c0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 s the first argu
276d0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ment..**.** The
276e0 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20 name of the new
276f0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e collation sequen
27700 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64 20 ce is specified
27710 61 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e as a UTF-8 strin
27720 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 g.** for sqlite3
27730 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
27740 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f n() and sqlite3_
27750 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
27760 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 _v2().** and a U
27770 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72 TF-16 string for
27780 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
27790 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49 collation16(). I
277a0 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 n all cases.** t
277b0 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65 he name is passe
277c0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 d as the second
277d0 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e function argumen
277e0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 t..**.** The thi
277f0 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 rd argument may
27800 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f be one of the co
27810 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f nstants [SQLITE_
27820 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 UTF8],.** [SQLIT
27830 45 5f 55 54 46 31 36 4c 45 5d 2c 20 6f 72 20 5b E_UTF16LE], or [
27840 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c SQLITE_UTF16BE],
27850 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 indicating that
27860 20 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69 the user-suppli
27870 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 ed.** routine ex
27880 70 65 63 74 73 20 74 6f 20 62 65 20 70 61 73 73 pects to be pass
27890 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 ed pointers to s
278a0 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 trings encoded u
278b0 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 sing UTF-8,.** U
278c0 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 TF-16 little-end
278d0 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 ian, or UTF-16 b
278e0 69 67 2d 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 ig-endian, respe
278f0 63 74 69 76 65 6c 79 2e 20 54 68 65 0a 2a 2a 20 ctively. The.**
27900 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d third argument m
27910 69 67 68 74 20 61 6c 73 6f 20 62 65 20 5b 53 51 ight also be [SQ
27920 4c 49 54 45 5f 55 54 46 31 36 5d 20 74 6f 20 69 LITE_UTF16] to i
27930 6e 64 69 63 61 74 65 20 74 68 61 74 20 74 68 65 ndicate that the
27940 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 65 78 70 65 routine.** expe
27950 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 cts pointers to
27960 62 65 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 be UTF-16 string
27970 73 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 s in the native
27980 62 79 74 65 20 6f 72 64 65 72 2c 20 6f 72 20 74 byte order, or t
27990 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 63 he.** argument c
279a0 61 6e 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 an be [SQLITE_UT
279b0 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 69 66 20 F16_ALIGNED] if
279c0 74 68 65 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 the.** the routi
279d0 6e 65 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74 ne expects point
279e0 65 72 73 20 74 6f 20 31 36 2d 62 69 74 20 77 6f ers to 16-bit wo
279f0 72 64 20 61 6c 69 67 6e 65 64 20 73 74 72 69 6e rd aligned strin
27a00 67 73 0a 2a 2a 20 6f 66 20 55 54 46 2d 31 36 20 gs.** of UTF-16
27a10 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 in the native by
27a20 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 te order..**.**
27a30 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 A pointer to the
27a40 20 75 73 65 72 20 73 75 70 70 6c 69 65 64 20 72 user supplied r
27a50 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70 outine must be p
27a60 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 66 assed as the fif
27a70 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 th.** argument.
27a80 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 If it is NULL,
27a90 74 68 69 73 20 69 73 20 74 68 65 20 73 61 6d 65 this is the same
27aa0 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65 as deleting the
27ab0 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 collation.** se
27ac0 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20 quence (so that
27ad0 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 SQLite cannot ca
27ae0 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a ll it anymore)..
27af0 2a 2a 20 45 61 63 68 20 74 69 6d 65 20 74 68 65 ** Each time the
27b00 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 75 70 application sup
27b10 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 plied function i
27b20 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 s invoked, it is
27b30 20 70 61 73 73 65 64 0a 2a 2a 20 61 73 20 69 74 passed.** as it
27b40 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 s first paramete
27b50 72 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 r a copy of the
27b60 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73 20 void* passed as
27b70 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d the fourth argum
27b80 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 ent.** to sqlite
27b90 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
27ba0 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f on() or sqlite3_
27bb0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
27bc0 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 16()..**.** The
27bd0 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 remaining argume
27be0 6e 74 73 20 74 6f 20 74 68 65 20 61 70 70 6c 69 nts to the appli
27bf0 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 cation-supplied
27c00 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20 routine are two
27c10 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 strings,.** each
27c20 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 represented by
27c30 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 a (length, data)
27c40 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 pair and encode
27c50 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e d in the encodin
27c60 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61 g.** that was pa
27c70 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 ssed as the thir
27c80 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 d argument when
27c90 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 the collation se
27ca0 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 quence was.** re
27cb0 67 69 73 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20 gistered. {END}
27cc0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
27cd0 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 defined collati
27ce0 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c on routine shoul
27cf0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67 61 d.** return nega
27d00 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f tive, zero or po
27d10 73 69 74 69 76 65 20 69 66 20 74 68 65 20 66 69 sitive if the fi
27d20 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 rst string is le
27d30 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61 ss than,.** equa
27d40 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 l to, or greater
27d50 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 than the second
27d60 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 string. i.e. (S
27d70 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 TRING1 - STRING2
27d80 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c )..**.** The sql
27d90 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
27da0 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 ation_v2() works
27db0 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 like sqlite3_cr
27dc0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 eate_collation()
27dd0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 .** except that
27de0 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72 it takes an extr
27df0 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 a argument which
27e00 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 is a destructor
27e10 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c for.** the coll
27e20 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 ation. The dest
27e30 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 ructor is called
27e40 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 when the collat
27e50 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f ion is.** destro
27e60 79 65 64 20 61 6e 64 20 69 73 20 70 61 73 73 65 yed and is passe
27e70 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 d a copy of the
27e80 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
27e90 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a void* pointer.*
27ea0 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 * of the sqlite3
27eb0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
27ec0 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 n_v2()..** Colla
27ed0 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f tions are destro
27ee0 79 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 yed when they ar
27ef0 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 e overridden by
27f00 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 later calls to t
27f10 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20 he.** collation
27f20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f creation functio
27f30 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b ns or when the [
27f40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
27f50 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a ion] is closed.*
27f60 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 * using [sqlite3
27f70 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a _close()]..**.**
27f80 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c See also: [sql
27f90 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
27fa0 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 eeded()] and [sq
27fb0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
27fc0 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2a 0a needed16()]..**.
27fd0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
27fe0 0a 2a 2a 20 5b 48 31 36 36 30 33 5d 20 5b 48 31 .** [H16603] [H1
27ff0 36 36 30 34 5d 20 5b 48 31 36 36 30 36 5d 20 5b 6604] [H16606] [
28000 48 31 36 36 30 39 5d 20 5b 48 31 36 36 31 32 5d H16609] [H16612]
28010 20 5b 48 31 36 36 31 35 5d 20 5b 48 31 36 36 31 [H16615] [H1661
28020 38 5d 20 5b 48 31 36 36 32 31 5d 0a 2a 2a 20 5b 8] [H16621].** [
28030 48 31 36 36 32 34 5d 20 5b 48 31 36 36 32 37 5d H16624] [H16627]
28040 20 5b 48 31 36 36 33 30 5d 0a 2a 2f 0a 69 6e 74 [H16630].*/.int
28050 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
28060 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c collation(. sql
28070 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 ite3*, . const
28080 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 char *zName, .
28090 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 int eTextRep, .
280a0 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 void*,. int(*x
280b0 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 Compare)(void*,i
280c0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 nt,const void*,i
280d0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a nt,const void*).
280e0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 );.int sqlite3_c
280f0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f reate_collation_
28100 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 v2(. sqlite3*,
28110 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
28120 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 Name, . int eTe
28130 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c xtRep, . void*,
28140 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 . int(*xCompare
28150 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 )(void*,int,cons
28160 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 t void*,int,cons
28170 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 t void*),. void
28180 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 (*xDestroy)(void
28190 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 *).);.int sqlite
281a0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
281b0 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a on16(. sqlite3*
281c0 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 , . const void
281d0 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 *zName,. int eT
281e0 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a extRep, . void*
281f0 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 ,. int(*xCompar
28200 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e e)(void*,int,con
28210 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e st void*,int,con
28220 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a st void*).);../*
28230 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
28240 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 llation Needed C
28250 61 6c 6c 62 61 63 6b 73 20 7b 48 31 36 37 30 30 allbacks {H16700
28260 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a } <S20300>.**.**
28270 20 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 To avoid having
28280 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c to register all
28290 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 collation seque
282a0 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 nces before a da
282b0 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 tabase.** can be
282c0 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 used, a single
282d0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
282e0 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 n may be registe
282f0 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 red with the.**
28300 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
28310 74 69 6f 6e 5d 20 74 6f 20 62 65 20 63 61 6c 6c tion] to be call
28320 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 ed whenever an u
28330 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 ndefined collati
28340 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 on.** sequence i
28350 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a s required..**.*
28360 2a 20 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f * If the functio
28370 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 n is registered
28380 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 using the sqlite
28390 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 3_collation_need
283a0 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 ed() API,.** the
283b0 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74 n it is passed t
283c0 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 he names of unde
283d0 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 fined collation
283e0 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 sequences as str
283f0 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 ings.** encoded
28400 69 6e 20 55 54 46 2d 38 2e 20 7b 48 31 36 37 30 in UTF-8. {H1670
28410 33 7d 20 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 3} If sqlite3_co
28420 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 llation_needed16
28430 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 () is used,.** t
28440 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 he names are pas
28450 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e sed as UTF-16 in
28460 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 machine native
28470 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 41 byte order..** A
28480 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 call to either
28490 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 function replace
284a0 73 20 61 6e 79 20 65 78 69 73 74 69 6e 67 20 63 s any existing c
284b0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 allback..**.** W
284c0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b hen the callback
284d0 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 is invoked, the
284e0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
284f0 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 passed is a copy
28500 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e .** of the secon
28510 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 d argument to sq
28520 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
28530 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 needed() or.** s
28540 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
28550 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 _needed16(). Th
28560 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
28570 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 t is the databas
28580 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e e.** connection.
28590 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 The third argu
285a0 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b ment is one of [
285b0 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 SQLITE_UTF8], [S
285c0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a QLITE_UTF16BE],.
285d0 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 ** or [SQLITE_UT
285e0 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 F16LE], indicati
285f0 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 ng the most desi
28600 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 rable form of th
28610 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 e collation.** s
28620 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e equence function
28630 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 required. The
28640 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
28650 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 is the name of
28660 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 the.** required
28670 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e collation sequen
28680 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 ce..**.** The ca
28690 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
286a0 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 should register
286b0 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c the desired coll
286c0 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b ation using.** [
286d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
286e0 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 ollation()], [sq
286f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
28700 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a lation16()], or.
28710 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 ** [sqlite3_crea
28720 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 te_collation_v2(
28730 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 )]..**.** Requir
28740 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 37 ements:.** [H167
28750 30 32 5d 20 5b 48 31 36 37 30 34 5d 20 5b 48 31 02] [H16704] [H1
28760 36 37 30 36 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 6706].*/.int sql
28770 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
28780 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 eeded(. sqlite3
28790 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 *, . void*, .
287a0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 void(*)(void*,sq
287b0 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 lite3*,int eText
287c0 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 Rep,const char*)
287d0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .);.int sqlite3_
287e0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 collation_needed
287f0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 16(. sqlite3*,
28800 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 . void*,. void
28810 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 (*)(void*,sqlite
28820 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 3*,int eTextRep,
28830 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a const void*).);.
28840 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 ./*.** Specify t
28850 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e he key for an en
28860 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65 crypted database
28870 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 . This routine
28880 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c should be.** cal
28890 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20 led right after
288a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a sqlite3_open()..
288b0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 **.** The code t
288c0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 o implement this
288d0 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 API is not avai
288e0 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 lable in the pub
288f0 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f lic release.** o
28900 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 f SQLite..*/.int
28910 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 sqlite3_key(.
28920 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
28930 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
28940 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 * Database to be
28950 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f rekeyed */. co
28960 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 nst void *pKey,
28970 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 int nKey /*
28980 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f The key */.);../
28990 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 *.** Change the
289a0 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 key on an open d
289b0 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 atabase. If the
289c0 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 current databas
289d0 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 e is not.** encr
289e0 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 ypted, this rout
289f0 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 ine will encrypt
28a00 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 it. If pNew==0
28a10 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 or nNew==0, the
28a20 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 .** database is
28a30 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a decrypted..**.**
28a40 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 The code to imp
28a50 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 lement this API
28a60 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 is not available
28a70 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 in the public r
28a80 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c elease.** of SQL
28a90 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ite..*/.int sqli
28aa0 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c te3_rekey(. sql
28ab0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
28ac0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 /* D
28ad0 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 atabase to be re
28ae0 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 keyed */. const
28af0 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 void *pKey, int
28b00 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 nKey /* The
28b10 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a new key */.);..
28b20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
28b30 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f Suspend Executio
28b40 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 n For A Short Ti
28b50 6d 65 20 7b 48 31 30 35 33 30 7d 20 3c 53 34 30 me {H10530} <S40
28b60 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 410>.**.** The s
28b70 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 qlite3_sleep() f
28b80 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 unction causes t
28b90 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 he current threa
28ba0 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 d to suspend exe
28bb0 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 cution.** for at
28bc0 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 least a number
28bd0 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 of milliseconds
28be0 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 specified in its
28bf0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a parameter..**.*
28c00 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 * If the operati
28c10 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e ng system does n
28c20 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 ot support sleep
28c30 20 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a requests with.*
28c40 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 * millisecond ti
28c50 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 me resolution, t
28c60 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c hen the time wil
28c70 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 l be rounded up
28c80 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 to.** the neares
28c90 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 t second. The nu
28ca0 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 mber of millisec
28cb0 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 onds of sleep ac
28cc0 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 tually.** reques
28cd0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 ted from the ope
28ce0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 rating system is
28cf0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
28d00 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e SQLite implemen
28d10 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 ts this interfac
28d20 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 e by calling the
28d30 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 xSleep().** met
28d40 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 hod of the defau
28d50 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d lt [sqlite3_vfs]
28d60 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 52 object..**.** R
28d70 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 equirements: [H1
28d80 30 35 33 33 5d 20 5b 48 31 30 35 33 36 5d 0a 2a 0533] [H10536].*
28d90 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c /.int sqlite3_sl
28da0 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a eep(int);../*.**
28db0 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 CAPI3REF: Name
28dc0 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f Of The Folder Ho
28dd0 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 lding Temporary
28de0 46 69 6c 65 73 20 7b 48 31 30 33 31 30 7d 20 3c Files {H10310} <
28df0 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 49 66 S20000>.**.** If
28e00 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 this global var
28e10 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f iable is made to
28e20 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 point to a stri
28e30 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 ng which is.** t
28e40 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c he name of a fol
28e50 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 der (a.k.a. dire
28e60 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c ctory), then all
28e70 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 temporary files
28e80 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 .** created by S
28e90 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 70 6c QLite will be pl
28ea0 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 aced in that dir
28eb0 65 63 74 6f 72 79 2e 20 20 49 66 20 74 68 69 73 ectory. If this
28ec0 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 variable.** is
28ed0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 a NULL pointer,
28ee0 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66 then SQLite perf
28ef0 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f orms a search fo
28f00 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 r an appropriate
28f10 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 .** temporary fi
28f20 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a le directory..**
28f30 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 .** It is not sa
28f40 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f fe to read or mo
28f50 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 dify this variab
28f60 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 le in more than
28f70 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 one.** thread at
28f80 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20 a time. It is
28f90 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 not safe to read
28fa0 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 or modify this
28fb0 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 variable.** if a
28fc0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
28fd0 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 ction] is being
28fe0 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65 used at the same
28ff0 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72 time in a separ
29000 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a ate.** thread..*
29010 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 * It is intended
29020 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 that this varia
29030 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a ble be set once.
29040 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 ** as part of pr
29050 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 ocess initializa
29060 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 tion and before
29070 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 any SQLite inter
29080 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 face.** routines
29090 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 have been calle
290a0 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 d and that this
290b0 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 variable remain
290c0 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 unchanged.** the
290d0 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 reafter..**.** T
290e0 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 he [temp_store_d
290f0 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d irectory pragma]
29100 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73 may modify this
29110 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61 variable and ca
29120 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 use.** it to poi
29130 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 nt to memory obt
29140 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 ained from [sqli
29150 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 46 75 te3_malloc]. Fu
29160 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 rthermore,.** th
29170 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 e [temp_store_di
29180 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 rectory pragma]
29190 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20 74 always assumes t
291a0 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a hat any string.*
291b0 2a 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 * that this vari
291c0 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 able points to i
291d0 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 s held in memory
291e0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a obtained from .
291f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c ** [sqlite3_mall
29200 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67 oc] and the prag
29210 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 ma may attempt t
29220 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f o free that memo
29230 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c ry.** using [sql
29240 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 ite3_free]..** H
29250 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76 61 ence, if this va
29260 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 riable is modifi
29270 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74 ed directly, eit
29280 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65 her it should be
29290 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 .** made NULL or
292a0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 made to point t
292b0 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 o memory obtaine
292c0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
292d0 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c malloc].** or el
292e0 73 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 se the use of th
292f0 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 e [temp_store_di
29300 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 rectory pragma]
29310 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 should be avoide
29320 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 d..*/.SQLITE_EXT
29330 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 ERN char *sqlite
29340 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3_temp_directory
29350 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
29360 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f F: Test For Auto
29370 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 20 7b 48 31 -Commit Mode {H1
29380 32 39 33 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2930} <S60200>.*
29390 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 * KEYWORDS: {aut
293a0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a ocommit mode}.**
293b0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
293c0 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 get_autocommit()
293d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
293e0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a ns non-zero or.*
293f0 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 * zero if the gi
29400 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e ven database con
29410 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 nection is or is
29420 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d not in autocomm
29430 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 it mode,.** resp
29440 65 63 74 69 76 65 6c 79 2e 20 20 41 75 74 6f 63 ectively. Autoc
29450 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e ommit mode is on
29460 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 by default..**
29470 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 Autocommit mode
29480 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 is disabled by a
29490 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 [BEGIN] stateme
294a0 6e 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 nt..** Autocommi
294b0 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 t mode is re-ena
294c0 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 bled by a [COMMI
294d0 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d T] or [ROLLBACK]
294e0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 ..**.** If certa
294f0 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f in kinds of erro
29500 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 rs occur on a st
29510 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 atement within a
29520 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 multi-statement
29530 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 .** transaction
29540 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e (errors includin
29550 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c g [SQLITE_FULL],
29560 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c [SQLITE_IOERR],
29570 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 .** [SQLITE_NOME
29580 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 M], [SQLITE_BUSY
29590 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 ], and [SQLITE_I
295a0 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 NTERRUPT]) then
295b0 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 the.** transacti
295c0 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c on might be roll
295d0 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 ed back automati
295e0 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 cally. The only
295f0 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 way to.** find
29600 6f 75 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 out whether SQLi
29610 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 te automatically
29620 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 rolled back the
29630 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 transaction aft
29640 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 er.** an error i
29650 73 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 s to use this fu
29660 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 nction..**.** If
29670 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 another thread
29680 63 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f changes the auto
29690 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 commit status of
296a0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a the database.**
296b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c connection whil
296c0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 e this routine i
296d0 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 s running, then
296e0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
296f0 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 .** is undefined
29700 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
29710 65 6e 74 73 3a 20 5b 48 31 32 39 33 31 5d 20 5b ents: [H12931] [
29720 48 31 32 39 33 32 5d 20 5b 48 31 32 39 33 33 5d H12932] [H12933]
29730 20 5b 48 31 32 39 33 34 5d 0a 2a 2f 0a 69 6e 74 [H12934].*/.int
29740 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 sqlite3_get_aut
29750 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a ocommit(sqlite3*
29760 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
29770 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74 EF: Find The Dat
29780 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 abase Handle Of
29790 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 A Prepared State
297a0 6d 65 6e 74 20 7b 48 31 33 31 32 30 7d 20 3c 53 ment {H13120} <S
297b0 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 60600>.**.** The
297c0 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 sqlite3_db_hand
297d0 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 le interface ret
297e0 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 urns the [databa
297f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 se connection] h
29800 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 andle.** to whic
29810 68 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 h a [prepared st
29820 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 atement] belongs
29830 2e 20 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 . The [database
29840 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 connection].**
29850 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
29860 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 te3_db_handle is
29870 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 the same [datab
29880 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
29890 74 68 61 74 20 77 61 73 20 74 68 65 20 66 69 72 that was the fir
298a0 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 st argument.** t
298b0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 o the [sqlite3_p
298c0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c repare_v2()] cal
298d0 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e l (or its varian
298e0 74 73 29 20 74 68 61 74 20 77 61 73 20 75 73 65 ts) that was use
298f0 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 d to.** create t
29900 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 he statement in
29910 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e the first place.
29920 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
29930 6e 74 73 3a 20 5b 48 31 33 31 32 33 5d 0a 2a 2f nts: [H13123].*/
29940 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 .sqlite3 *sqlite
29950 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 3_db_handle(sqli
29960 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a te3_stmt*);../*.
29970 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e ** CAPI3REF: Fin
29980 64 20 74 68 65 20 6e 65 78 74 20 70 72 65 70 61 d the next prepa
29990 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 7b 48 red statement {H
299a0 31 33 31 34 30 7d 20 3c 53 36 30 36 30 30 3e 0a 13140} <S60600>.
299b0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 **.** This inter
299c0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 face returns a p
299d0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 65 ointer to the ne
299e0 78 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 xt [prepared sta
299f0 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a tement] after.**
29a00 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74 65 pStmt associate
29a10 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 d with the [data
29a20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
29a30 20 70 44 62 2e 20 20 49 66 20 70 53 74 6d 74 20 pDb. If pStmt
29a40 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 is NULL.** then
29a50 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 this interface r
29a60 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
29a70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 70 72 to the first pr
29a80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
29a90 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 .** associated w
29aa0 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65 ith the database
29ab0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e connection pDb.
29ac0 20 20 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64 If no prepared
29ad0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 statement.** sa
29ae0 74 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64 tisfies the cond
29af0 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 itions of this r
29b00 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72 outine, it retur
29b10 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 ns NULL..**.** T
29b20 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
29b30 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 nection] pointer
29b40 20 44 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a D in a call to.
29b50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 ** [sqlite3_next
29b60 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 _stmt(D,S)] must
29b70 20 72 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 refer to an ope
29b80 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f n database.** co
29b90 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 nnection and in
29ba0 70 61 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20 particular must
29bb0 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f not be a NULL po
29bc0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 inter..**.** Req
29bd0 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 33 31 uirements: [H131
29be0 34 33 5d 20 5b 48 31 33 31 34 36 5d 20 5b 48 31 43] [H13146] [H1
29bf0 33 31 34 39 5d 20 5b 48 31 33 31 35 32 5d 0a 2a 3149] [H13152].*
29c00 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a /.sqlite3_stmt *
29c10 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d sqlite3_next_stm
29c20 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 t(sqlite3 *pDb,
29c30 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
29c40 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tmt);../*.** CAP
29c50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e I3REF: Commit An
29c60 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 d Rollback Notif
29c70 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b ication Callback
29c80 73 20 7b 48 31 32 39 35 30 7d 20 3c 53 36 30 34 s {H12950} <S604
29c90 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 00>.**.** The sq
29ca0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f lite3_commit_hoo
29cb0 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 k() interface re
29cc0 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 gisters a callba
29cd0 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 ck.** function t
29ce0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 o be invoked whe
29cf0 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 never a transact
29d00 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 ion is committed
29d10 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 ..** Any callbac
29d20 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 k set by a previ
29d30 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 ous call to sqli
29d40 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 te3_commit_hook(
29d50 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d ).** for the sam
29d60 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
29d70 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 ction is overrid
29d80 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 den..** The sqli
29d90 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f te3_rollback_hoo
29da0 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 k() interface re
29db0 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 gisters a callba
29dc0 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 ck.** function t
29dd0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 o be invoked whe
29de0 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 never a transact
29df0 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 ion is committed
29e00 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 ..** Any callbac
29e10 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 k set by a previ
29e20 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 ous call to sqli
29e30 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 te3_commit_hook(
29e40 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d ).** for the sam
29e50 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
29e60 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 ction is overrid
29e70 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 70 41 72 67 den..** The pArg
29e80 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 argument is pas
29e90 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 sed through to t
29ea0 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 he callback..**
29eb0 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 If the callback
29ec0 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b on a commit hook
29ed0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e function return
29ee0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 s non-zero,.** t
29ef0 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 hen the commit i
29f00 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f s converted into
29f10 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a a rollback..**.
29f20 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 ** If another fu
29f30 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 nction was previ
29f40 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 ously registered
29f50 2c 20 69 74 73 0a 2a 2a 20 70 41 72 67 20 76 61 , its.** pArg va
29f60 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e lue is returned.
29f70 20 20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c Otherwise NULL
29f80 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
29f90 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b .** The callback
29fa0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
29fb0 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 must not do anyt
29fc0 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d hing that will m
29fd0 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 odify.** the dat
29fe0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
29ff0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 that invoked th
2a000 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 e callback. Any
2a010 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d actions.** to m
2a020 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 odify the databa
2a030 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 se connection mu
2a040 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75 st be deferred u
2a050 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a ntil after the.*
2a060 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 * completion of
2a070 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 the [sqlite3_ste
2a080 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 p()] call that t
2a090 72 69 67 67 65 72 65 64 20 74 68 65 20 63 6f 6d riggered the com
2a0a0 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 mit.** or rollba
2a0b0 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66 ck hook in the f
2a0c0 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e irst place..** N
2a0d0 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 ote that [sqlite
2a0e0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
2a0f0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 and [sqlite3_ste
2a100 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 p()] both modify
2a110 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 their.** databa
2a120 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 se connections f
2a130 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f or the meaning o
2a140 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 f "modify" in th
2a150 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a is paragraph..**
2a160 0a 2a 2a 20 52 65 67 69 73 74 65 72 69 6e 67 20 .** Registering
2a170 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 a NULL function
2a180 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c disables the cal
2a190 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 lback..**.** For
2a1a0 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 the purposes of
2a1b0 20 74 68 69 73 20 41 50 49 2c 20 61 20 74 72 61 this API, a tra
2a1c0 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64 nsaction is said
2a1d0 20 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a to have been.**
2a1e0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 rolled back if
2a1f0 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c an explicit "ROL
2a200 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 LBACK" statement
2a210 20 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72 is executed, or
2a220 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 .** an error or
2a230 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65 constraint cause
2a240 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f s an implicit ro
2a250 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e llback to occur.
2a260 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b .** The rollback
2a270 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 callback is not
2a280 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 invoked if a tr
2a290 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 ansaction is.**
2a2a0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f automatically ro
2a2b0 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 lled back becaus
2a2c0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 e the database c
2a2d0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f onnection is clo
2a2e0 73 65 64 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c sed..** The roll
2a2f0 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 back callback is
2a300 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 not invoked if
2a310 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 a transaction is
2a320 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 .** rolled back
2a330 62 65 63 61 75 73 65 20 61 20 63 6f 6d 6d 69 74 because a commit
2a340 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
2a350 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 ed non-zero..**
2a360 3c 74 6f 64 6f 3e 20 43 68 65 63 6b 20 6f 6e 20 <todo> Check on
2a370 74 68 69 73 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a this </todo>.**.
2a380 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
2a390 0a 2a 2a 20 5b 48 31 32 39 35 31 5d 20 5b 48 31 .** [H12951] [H1
2a3a0 32 39 35 32 5d 20 5b 48 31 32 39 35 33 5d 20 5b 2952] [H12953] [
2a3b0 48 31 32 39 35 34 5d 20 5b 48 31 32 39 35 35 5d H12954] [H12955]
2a3c0 0a 2a 2a 20 5b 48 31 32 39 36 31 5d 20 5b 48 31 .** [H12961] [H1
2a3d0 32 39 36 32 5d 20 5b 48 31 32 39 36 33 5d 20 5b 2962] [H12963] [
2a3e0 48 31 32 39 36 34 5d 0a 2a 2f 0a 76 6f 69 64 20 H12964].*/.void
2a3f0 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f *sqlite3_commit_
2a400 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 hook(sqlite3*, i
2a410 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f nt(*)(void*), vo
2a420 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 id*);.void *sqli
2a430 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f te3_rollback_hoo
2a440 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 k(sqlite3*, void
2a450 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 (*)(void *), voi
2a460 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d*);../*.** CAPI
2a470 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67 3REF: Data Chang
2a480 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 e Notification C
2a490 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 37 30 allbacks {H12970
2a4a0 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a } <S60400>.**.**
2a4b0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 The sqlite3_upd
2a4c0 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 ate_hook() inter
2a4d0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 face registers a
2a4e0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
2a4f0 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b on.** with the [
2a500 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2a510 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 64 20 ion] identified
2a520 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 by the first arg
2a530 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 ument.** to be i
2a540 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 nvoked whenever
2a550 61 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 a row is updated
2a560 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 , inserted or de
2a570 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 leted..** Any ca
2a580 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 llback set by a
2a590 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f previous call to
2a5a0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a this function.*
2a5b0 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 * for the same d
2a5c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2a5d0 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e on is overridden
2a5e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f ..**.** The seco
2a5f0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 nd argument is a
2a600 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
2a610 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f function to invo
2a620 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 ke when a.** row
2a630 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 is updated, ins
2a640 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 erted or deleted
2a650 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 ..** The first a
2a660 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 rgument to the c
2a670 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 allback is a cop
2a680 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 y of the third a
2a690 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 rgument.** to sq
2a6a0 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f lite3_update_hoo
2a6b0 6b 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f k()..** The seco
2a6c0 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 nd callback argu
2a6d0 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b ment is one of [
2a6e0 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 SQLITE_INSERT],
2a6f0 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c [SQLITE_DELETE],
2a700 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 .** or [SQLITE_U
2a710 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e PDATE], dependin
2a720 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 g on the operati
2a730 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74 on that caused t
2a740 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 he callback.** t
2a750 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a o be invoked..**
2a760 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 The third and f
2a770 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 ourth arguments
2a780 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
2a790 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 contain pointers
2a7a0 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 to the.** datab
2a7b0 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 ase and table na
2a7c0 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 me containing th
2a7d0 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a e affected row..
2a7e0 2a 2a 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c ** The final cal
2a7f0 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 lback parameter
2a800 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f is the [rowid] o
2a810 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 49 6e f the row..** In
2a820 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20 the case of an
2a830 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 update, this is
2a840 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74 65 the [rowid] afte
2a850 72 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b r the update tak
2a860 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 es place..**.**
2a870 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 The update hook
2a880 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 is not invoked w
2a890 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 hen internal sys
2a8a0 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a tem tables are.*
2a8b0 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e * modified (i.e.
2a8c0 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 sqlite_master a
2a8d0 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e nd sqlite_sequen
2a8e0 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 ce)..**.** The u
2a8f0 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 pdate hook imple
2a900 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e mentation must n
2a910 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 ot do anything t
2a920 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a hat will modify.
2a930 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ** the database
2a940 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 connection that
2a950 69 6e 76 6f 6b 65 64 20 74 68 65 20 75 70 64 61 invoked the upda
2a960 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 te hook. Any ac
2a970 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 tions.** to modi
2a980 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 fy the database
2a990 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 connection must
2a9a0 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 be deferred unti
2a9b0 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 l after the.** c
2a9c0 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 ompletion of the
2a9d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
2a9e0 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 ] call that trig
2a9f0 67 65 72 65 64 20 74 68 65 20 75 70 64 61 74 65 gered the update
2aa00 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 hook..** Note t
2aa10 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 hat [sqlite3_pre
2aa20 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b pare_v2()] and [
2aa30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
2aa40 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 both modify thei
2aa50 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f r.** database co
2aa60 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 nnections for th
2aa70 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f e meaning of "mo
2aa80 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 dify" in this pa
2aa90 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 49 ragraph..**.** I
2aaa0 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 f another functi
2aab0 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c on was previousl
2aac0 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69 74 y registered, it
2aad0 73 20 70 41 72 67 20 76 61 6c 75 65 0a 2a 2a 20 s pArg value.**
2aae0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 is returned. Ot
2aaf0 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 herwise NULL is
2ab00 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
2ab10 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
2ab20 20 5b 48 31 32 39 37 31 5d 20 5b 48 31 32 39 37 [H12971] [H1297
2ab30 33 5d 20 5b 48 31 32 39 37 35 5d 20 5b 48 31 32 3] [H12975] [H12
2ab40 39 37 37 5d 20 5b 48 31 32 39 37 39 5d 20 5b 48 977] [H12979] [H
2ab50 31 32 39 38 31 5d 20 5b 48 31 32 39 38 33 5d 20 12981] [H12983]
2ab60 5b 48 31 32 39 38 36 5d 0a 2a 2f 0a 76 6f 69 64 [H12986].*/.void
2ab70 20 2a 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 *sqlite3_update
2ab80 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 _hook(. sqlite3
2ab90 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f *, . void(*)(vo
2aba0 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 id *,int ,char c
2abb0 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 onst *,char cons
2abc0 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 t *,sqlite3_int6
2abd0 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 4),. void*.);..
2abe0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2abf0 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c Enable Or Disabl
2ac00 65 20 53 68 61 72 65 64 20 50 61 67 65 72 20 43 e Shared Pager C
2ac10 61 63 68 65 20 7b 48 31 30 33 33 30 7d 20 3c 53 ache {H10330} <S
2ac20 33 30 39 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 30900>.** KEYWOR
2ac30 44 53 3a 20 7b 73 68 61 72 65 64 20 63 61 63 68 DS: {shared cach
2ac40 65 7d 20 7b 73 68 61 72 65 64 20 63 61 63 68 65 e} {shared cache
2ac50 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 mode}.**.** Thi
2ac60 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 s routine enable
2ac70 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 s or disables th
2ac80 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74 68 65 e sharing of the
2ac90 20 64 61 74 61 62 61 73 65 20 63 61 63 68 65 0a database cache.
2aca0 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20 64 61 ** and schema da
2acb0 74 61 20 73 74 72 75 63 74 75 72 65 73 20 62 65 ta structures be
2acc0 74 77 65 65 6e 20 5b 64 61 74 61 62 61 73 65 20 tween [database
2acd0 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 63 6f 6e connection | con
2ace0 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 nections].** to
2acf0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
2ad00 65 2e 20 53 68 61 72 69 6e 67 20 69 73 20 65 6e e. Sharing is en
2ad10 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 abled if the arg
2ad20 75 6d 65 6e 74 20 69 73 20 74 72 75 65 0a 2a 2a ument is true.**
2ad30 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66 and disabled if
2ad40 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 the argument is
2ad50 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 43 61 false..**.** Ca
2ad60 63 68 65 20 73 68 61 72 69 6e 67 20 69 73 20 65 che sharing is e
2ad70 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 73 61 62 nabled and disab
2ad80 6c 65 64 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 led for an entir
2ad90 65 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 e process..** Th
2ada0 69 73 20 69 73 20 61 20 63 68 61 6e 67 65 20 61 is is a change a
2adb0 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 s of SQLite vers
2adc0 69 6f 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 70 72 ion 3.5.0. In pr
2add0 69 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 ior versions of
2ade0 53 51 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 72 69 SQLite,.** shari
2adf0 6e 67 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f ng was enabled o
2ae00 72 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 65 r disabled for e
2ae10 61 63 68 20 74 68 72 65 61 64 20 73 65 70 61 72 ach thread separ
2ae20 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ately..**.** The
2ae30 20 63 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d cache sharing m
2ae40 6f 64 65 20 73 65 74 20 62 79 20 74 68 69 73 20 ode set by this
2ae50 69 6e 74 65 72 66 61 63 65 20 65 66 66 65 63 74 interface effect
2ae60 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 s all subsequent
2ae70 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 .** calls to [sq
2ae80 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b lite3_open()], [
2ae90 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
2aea0 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 )], and [sqlite3
2aeb0 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 _open16()]..** E
2aec0 78 69 73 74 69 6e 67 20 64 61 74 61 62 61 73 65 xisting database
2aed0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e connections con
2aee0 74 69 6e 75 65 20 75 73 65 20 74 68 65 20 73 68 tinue use the sh
2aef0 61 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 aring mode.** th
2af00 61 74 20 77 61 73 20 69 6e 20 65 66 66 65 63 74 at was in effect
2af10 20 61 74 20 74 68 65 20 74 69 6d 65 20 74 68 65 at the time the
2af20 79 20 77 65 72 65 20 6f 70 65 6e 65 64 2e 0a 2a y were opened..*
2af30 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 *.** Virtual tab
2af40 6c 65 73 20 63 61 6e 6e 6f 74 20 62 65 20 75 73 les cannot be us
2af50 65 64 20 77 69 74 68 20 61 20 73 68 61 72 65 64 ed with a shared
2af60 20 63 61 63 68 65 2e 20 20 57 68 65 6e 20 73 68 cache. When sh
2af70 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 ared.** cache is
2af80 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b 73 enabled, the [s
2af90 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f qlite3_create_mo
2afa0 64 75 6c 65 28 29 5d 20 41 50 49 20 75 73 65 64 dule()] API used
2afb0 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 to register.**
2afc0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 77 virtual tables w
2afd0 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 ill always retur
2afe0 6e 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a n an error..**.*
2aff0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 * This routine r
2b000 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
2b010 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63 K] if shared cac
2b020 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f he was enabled o
2b030 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 r disabled.** su
2b040 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 ccessfully. An
2b050 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 [error code] is
2b060 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69 returned otherwi
2b070 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65 64 se..**.** Shared
2b080 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c cache is disabl
2b090 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20 42 ed by default. B
2b0a0 75 74 20 74 68 69 73 20 6d 69 67 68 74 20 63 68 ut this might ch
2b0b0 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72 ange in.** futur
2b0c0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 e releases of SQ
2b0d0 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69 Lite. Applicati
2b0e0 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20 61 62 ons that care ab
2b0f0 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 out shared.** ca
2b100 63 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75 che setting shou
2b110 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c 69 63 ld set it explic
2b120 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 itly..**.** See
2b130 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74 65 20 53 Also: [SQLite S
2b140 68 61 72 65 64 2d 43 61 63 68 65 20 4d 6f 64 65 hared-Cache Mode
2b150 5d 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ].**.** Requirem
2b160 65 6e 74 73 3a 20 5b 48 31 30 33 33 31 5d 20 5b ents: [H10331] [
2b170 48 31 30 33 33 36 5d 20 5b 48 31 30 33 33 37 5d H10336] [H10337]
2b180 20 5b 48 31 30 33 33 39 5d 0a 2a 2f 0a 69 6e 74 [H10339].*/.int
2b190 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f sqlite3_enable_
2b1a0 73 68 61 72 65 64 5f 63 61 63 68 65 28 69 6e 74 shared_cache(int
2b1b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2b1c0 45 46 3a 20 41 74 74 65 6d 70 74 20 54 6f 20 46 EF: Attempt To F
2b1d0 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72 79 20 ree Heap Memory
2b1e0 7b 48 31 37 33 34 30 7d 20 3c 53 33 30 32 32 30 {H17340} <S30220
2b1f0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 >.**.** The sqli
2b200 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f te3_release_memo
2b210 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 ry() interface a
2b220 74 74 65 6d 70 74 73 20 74 6f 20 66 72 65 65 20 ttempts to free
2b230 4e 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 68 65 N bytes.** of he
2b240 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 ap memory by dea
2b250 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 llocating non-es
2b260 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 20 61 sential memory a
2b270 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 llocations.** he
2b280 6c 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61 ld by the databa
2b290 73 65 20 6c 69 62 72 61 72 79 2e 20 7b 45 4e 44 se library. {END
2b2a0 7d 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 20 74 } Memory used t
2b2b0 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73 65 o cache database
2b2c0 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 69 6d 70 .** pages to imp
2b2d0 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 rove performance
2b2e0 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f is an example o
2b2f0 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 f non-essential
2b300 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 73 71 6c 69 74 memory..** sqlit
2b310 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 e3_release_memor
2b320 79 28 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 y() returns the
2b330 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
2b340 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 0a actually freed,.
2b350 2a 2a 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 ** which might b
2b360 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 20 74 e more or less t
2b370 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 han the amount r
2b380 65 71 75 65 73 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 equested..**.**
2b390 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 Requirements: [H
2b3a0 31 37 33 34 31 5d 20 5b 48 31 37 33 34 32 5d 0a 17341] [H17342].
2b3b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 */.int sqlite3_r
2b3c0 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e elease_memory(in
2b3d0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
2b3e0 52 45 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 REF: Impose A Li
2b3f0 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 mit On Heap Size
2b400 20 7b 48 31 37 33 35 30 7d 20 3c 53 33 30 32 32 {H17350} <S3022
2b410 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 0>.**.** The sql
2b420 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c ite3_soft_heap_l
2b430 69 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 imit() interface
2b440 20 70 6c 61 63 65 73 20 61 20 22 73 6f 66 74 22 places a "soft"
2b450 20 6c 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68 65 limit.** on the
2b460 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 amount of heap
2b470 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 memory that may
2b480 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 be allocated by
2b490 53 51 4c 69 74 65 2e 0a 2a 2a 20 49 66 20 61 6e SQLite..** If an
2b4a0 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61 internal alloca
2b4b0 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 tion is requeste
2b4c0 64 20 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63 d that would exc
2b4d0 65 65 64 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 eed the.** soft
2b4e0 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c heap limit, [sql
2b4f0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d ite3_release_mem
2b500 6f 72 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 ory()] is invoke
2b510 64 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f 72 65 d one or.** more
2b520 20 74 69 6d 65 73 20 74 6f 20 66 72 65 65 20 75 times to free u
2b530 70 20 73 6f 6d 65 20 73 70 61 63 65 20 62 65 66 p some space bef
2b540 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 ore the allocati
2b550 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e on is performed.
2b560 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 6d 69 74 .**.** The limit
2b570 20 69 73 20 63 61 6c 6c 65 64 20 22 73 6f 66 74 is called "soft
2b580 22 2c 20 62 65 63 61 75 73 65 20 69 66 20 5b 73 ", because if [s
2b590 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d qlite3_release_m
2b5a0 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63 61 6e 6e emory()].** cann
2b5b0 6f 74 20 66 72 65 65 20 73 75 66 66 69 63 69 65 ot free sufficie
2b5c0 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65 nt memory to pre
2b5d0 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 74 20 66 vent the limit f
2b5e0 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 65 65 64 rom being exceed
2b5f0 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 ed,.** the memor
2b600 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 y is allocated a
2b610 6e 79 77 61 79 20 61 6e 64 20 74 68 65 20 63 75 nyway and the cu
2b620 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20 rrent operation
2b630 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 proceeds..**.**
2b640 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65 A negative or ze
2b650 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 6d ro value for N m
2b660 65 61 6e 73 20 74 68 61 74 20 74 68 65 72 65 20 eans that there
2b670 69 73 20 6e 6f 20 73 6f 66 74 20 68 65 61 70 20 is no soft heap
2b680 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 limit and.** [sq
2b690 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 lite3_release_me
2b6a0 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c mory()] will onl
2b6b0 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e y be called when
2b6c0 20 6d 65 6d 6f 72 79 20 69 73 20 65 78 68 61 75 memory is exhau
2b6d0 73 74 65 64 2e 0a 2a 2a 20 54 68 65 20 64 65 66 sted..** The def
2b6e0 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 ault value for t
2b6f0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d he soft heap lim
2b700 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a it is zero..**.*
2b710 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 * SQLite makes a
2b720 20 62 65 73 74 20 65 66 66 6f 72 74 20 74 6f 20 best effort to
2b730 68 6f 6e 6f 72 20 74 68 65 20 73 6f 66 74 20 68 honor the soft h
2b740 65 61 70 20 6c 69 6d 69 74 2e 0a 2a 2a 20 42 75 eap limit..** Bu
2b750 74 20 69 66 20 74 68 65 20 73 6f 66 74 20 68 65 t if the soft he
2b760 61 70 20 6c 69 6d 69 74 20 63 61 6e 6e 6f 74 20 ap limit cannot
2b770 62 65 20 68 6f 6e 6f 72 65 64 2c 20 65 78 65 63 be honored, exec
2b780 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f ution will.** co
2b790 6e 74 69 6e 75 65 20 77 69 74 68 6f 75 74 20 65 ntinue without e
2b7a0 72 72 6f 72 20 6f 72 20 6e 6f 74 69 66 69 63 61 rror or notifica
2b7b0 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 73 20 77 tion. This is w
2b7c0 68 79 20 74 68 65 20 6c 69 6d 69 74 20 69 73 0a hy the limit is.
2b7d0 2a 2a 20 63 61 6c 6c 65 64 20 61 20 22 73 6f 66 ** called a "sof
2b7e0 74 22 20 6c 69 6d 69 74 2e 20 20 49 74 20 69 73 t" limit. It is
2b7f0 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a advisory only..
2b800 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 **.** Prior to S
2b810 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e QLite version 3.
2b820 35 2e 30 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 5.0, this routin
2b830 65 20 6f 6e 6c 79 20 63 6f 6e 73 74 72 61 69 6e e only constrain
2b840 65 64 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a ed the memory.**
2b850 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 61 20 allocated by a
2b860 73 69 6e 67 6c 65 20 74 68 72 65 61 64 20 2d 20 single thread -
2b870 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 the same thread
2b880 69 6e 20 77 68 69 63 68 20 74 68 69 73 20 72 6f in which this ro
2b890 75 74 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 utine.** runs.
2b8a0 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 Beginning with S
2b8b0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e QLite version 3.
2b8c0 35 2e 30 2c 20 74 68 65 20 73 6f 66 74 20 68 65 5.0, the soft he
2b8d0 61 70 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 61 ap limit is.** a
2b8e0 70 70 6c 69 65 64 20 74 6f 20 61 6c 6c 20 74 68 pplied to all th
2b8f0 72 65 61 64 73 2e 20 54 68 65 20 76 61 6c 75 65 reads. The value
2b900 20 73 70 65 63 69 66 69 65 64 20 66 6f 72 20 74 specified for t
2b910 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d he soft heap lim
2b920 69 74 0a 2a 2a 20 69 73 20 61 6e 20 75 70 70 65 it.** is an uppe
2b930 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 74 r bound on the t
2b940 6f 74 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f otal memory allo
2b950 63 61 74 69 6f 6e 20 66 6f 72 20 61 6c 6c 20 74 cation for all t
2b960 68 72 65 61 64 73 2e 20 49 6e 0a 2a 2a 20 76 65 hreads. In.** ve
2b970 72 73 69 6f 6e 20 33 2e 35 2e 30 20 74 68 65 72 rsion 3.5.0 ther
2b980 65 20 69 73 20 6e 6f 20 6d 65 63 68 61 6e 69 73 e is no mechanis
2b990 6d 20 66 6f 72 20 6c 69 6d 69 74 69 6e 67 20 74 m for limiting t
2b9a0 68 65 20 68 65 61 70 20 75 73 61 67 65 20 66 6f he heap usage fo
2b9b0 72 0a 2a 2a 20 69 6e 64 69 76 69 64 75 61 6c 20 r.** individual
2b9c0 74 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 52 threads..**.** R
2b9d0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
2b9e0 5b 48 31 36 33 35 31 5d 20 5b 48 31 36 33 35 32 [H16351] [H16352
2b9f0 5d 20 5b 48 31 36 33 35 33 5d 20 5b 48 31 36 33 ] [H16353] [H163
2ba00 35 34 5d 20 5b 48 31 36 33 35 35 5d 20 5b 48 31 54] [H16355] [H1
2ba10 36 33 35 38 5d 0a 2a 2f 0a 76 6f 69 64 20 73 71 6358].*/.void sq
2ba20 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f lite3_soft_heap_
2ba30 6c 69 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a limit(int);../*.
2ba40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 ** CAPI3REF: Ext
2ba50 72 61 63 74 20 4d 65 74 61 64 61 74 61 20 41 62 ract Metadata Ab
2ba60 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 out A Column Of
2ba70 41 20 54 61 62 6c 65 20 7b 48 31 32 38 35 30 7d A Table {H12850}
2ba80 20 3c 53 36 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S60300>.**.**
2ba90 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 This routine ret
2baa0 75 72 6e 73 20 6d 65 74 61 64 61 74 61 20 61 62 urns metadata ab
2bab0 6f 75 74 20 61 20 73 70 65 63 69 66 69 63 20 63 out a specific c
2bac0 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 69 olumn of a speci
2bad0 66 69 63 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 fic.** database
2bae0 74 61 62 6c 65 20 61 63 63 65 73 73 69 62 6c 65 table accessible
2baf0 20 75 73 69 6e 67 20 74 68 65 20 5b 64 61 74 61 using the [data
2bb00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
2bb10 20 68 61 6e 64 6c 65 0a 2a 2a 20 70 61 73 73 65 handle.** passe
2bb20 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 66 d as the first f
2bb30 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 unction argument
2bb40 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6c 75 ..**.** The colu
2bb50 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 mn is identified
2bb60 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 2c 20 by the second,
2bb70 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 third and fourth
2bb80 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 0a 2a parameters to.*
2bb90 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e * this function.
2bba0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 The second para
2bbb0 6d 65 74 65 72 20 69 73 20 65 69 74 68 65 72 20 meter is either
2bbc0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
2bbd0 64 61 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 database.** (i.e
2bbe0 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 . "main", "temp"
2bbf0 20 6f 72 20 61 6e 20 61 74 74 61 63 68 65 64 20 or an attached
2bc00 64 61 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69 database) contai
2bc10 6e 69 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 ning the specifi
2bc20 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e ed.** table or N
2bc30 55 4c 4c 2e 20 49 66 20 69 74 20 69 73 20 4e 55 ULL. If it is NU
2bc40 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 LL, then all att
2bc50 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 20 ached databases
2bc60 61 72 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 are searched.**
2bc70 66 6f 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 for the table us
2bc80 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 ing the same alg
2bc90 6f 72 69 74 68 6d 20 75 73 65 64 20 62 79 20 74 orithm used by t
2bca0 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 he database engi
2bcb0 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 ne to.** resolve
2bcc0 20 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 unqualified tab
2bcd0 6c 65 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a le references..*
2bce0 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 *.** The third a
2bcf0 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 nd fourth parame
2bd00 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e ters to this fun
2bd10 63 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 ction are the ta
2bd20 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a ble and column.*
2bd30 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 * name of the de
2bd40 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 sired column, re
2bd50 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 spectively. Neit
2bd60 68 65 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 her of these par
2bd70 61 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62 ameters.** may b
2bd80 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65 e NULL..**.** Me
2bd90 74 61 64 61 74 61 20 69 73 20 72 65 74 75 72 6e tadata is return
2bda0 65 64 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f ed by writing to
2bdb0 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 the memory loca
2bdc0 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73 20 tions passed as
2bdd0 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73 the 5th.** and s
2bde0 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 ubsequent parame
2bdf0 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e ters to this fun
2be00 63 74 69 6f 6e 2e 20 41 6e 79 20 6f 66 20 74 68 ction. Any of th
2be10 65 73 65 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 ese arguments ma
2be20 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e y be.** NULL, in
2be30 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 which case the
2be40 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c corresponding el
2be50 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64 61 74 ement of metadat
2be60 61 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a a is omitted..**
2be70 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
2be80 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 .** <table borde
2be90 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 r="1">.** <tr><t
2bea0 68 3e 20 50 61 72 61 6d 65 74 65 72 20 3c 74 68 h> Parameter <th
2beb0 3e 20 4f 75 74 70 75 74 3c 62 72 3e 54 79 70 65 > Output<br>Type
2bec0 20 3c 74 68 3e 20 20 44 65 73 63 72 69 70 74 69 <th> Descripti
2bed0 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 on.**.** <tr><td
2bee0 3e 20 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 > 5th <td> const
2bef0 20 63 68 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 char* <td> Data
2bf00 20 74 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 type.** <tr><td
2bf10 3e 20 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 > 6th <td> const
2bf20 20 63 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 char* <td> Name
2bf30 20 6f 66 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c of default coll
2bf40 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a ation sequence.*
2bf50 2a 20 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c * <tr><td> 7th <
2bf60 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 td> int
2bf70 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c <td> True if col
2bf80 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 umn has a NOT NU
2bf90 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a LL constraint.**
2bfa0 20 3c 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 <tr><td> 8th <t
2bfb0 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c d> int <
2bfc0 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 td> True if colu
2bfd0 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 mn is part of th
2bfe0 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a e PRIMARY KEY.**
2bff0 20 3c 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 <tr><td> 9th <t
2c000 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c d> int <
2c010 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 td> True if colu
2c020 6d 6e 20 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 mn is [AUTOINCRE
2c030 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 MENT].** </table
2c040 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 >.** </blockquot
2c050 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d e>.**.** The mem
2c060 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 ory pointed to b
2c070 79 20 74 68 65 20 63 68 61 72 61 63 74 65 72 20 y the character
2c080 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 pointers returne
2c090 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65 63 d for the.** dec
2c0a0 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e laration type an
2c0b0 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 d collation sequ
2c0c0 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e ence is valid on
2c0d0 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 ly until the nex
2c0e0 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 t.** call to any
2c0f0 20 53 51 4c 69 74 65 20 41 50 49 20 66 75 6e 63 SQLite API func
2c100 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 tion..**.** If t
2c110 68 65 20 73 70 65 63 69 66 69 65 64 20 74 61 62 he specified tab
2c120 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79 20 61 le is actually a
2c130 20 76 69 65 77 2c 20 61 6e 20 5b 65 72 72 6f 72 view, an [error
2c140 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e code] is return
2c150 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 ed..**.** If the
2c160 20 73 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d specified colum
2c170 6e 20 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f n is "rowid", "o
2c180 69 64 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 id" or "_rowid_"
2c190 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e 54 45 and an.** [INTE
2c1a0 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d GER PRIMARY KEY]
2c1b0 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e column has been
2c1c0 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c explicitly decl
2c1d0 61 72 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f ared, then the o
2c1e0 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 utput.** paramet
2c1f0 65 72 73 20 61 72 65 20 73 65 74 20 66 6f 72 20 ers are set for
2c200 74 68 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64 the explicitly d
2c210 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 eclared column.
2c220 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a If there is no.*
2c230 2a 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 * explicitly dec
2c240 6c 61 72 65 64 20 5b 49 4e 54 45 47 45 52 20 50 lared [INTEGER P
2c250 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 RIMARY KEY] colu
2c260 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 mn, then the out
2c270 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 put.** parameter
2c280 73 20 61 72 65 20 73 65 74 20 61 73 20 66 6f 6c s are set as fol
2c290 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 lows:.**.** <pre
2c2a0 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61 20 74 79 >.** data ty
2c2b0 70 65 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a pe: "INTEGER".**
2c2c0 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 collation s
2c2d0 65 71 75 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 equence: "BINARY
2c2e0 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c ".** not nul
2c2f0 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d l: 0.** prim
2c300 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 ary key: 1.**
2c310 20 20 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 auto increment
2c320 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a : 0.** </pre>.**
2c330 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f .** This functio
2c340 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f n may load one o
2c350 72 20 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 66 r more schemas f
2c360 72 6f 6d 20 64 61 74 61 62 61 73 65 20 66 69 6c rom database fil
2c370 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 es. If an.** err
2c380 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 or occurs during
2c390 20 74 68 69 73 20 70 72 6f 63 65 73 73 2c 20 6f this process, o
2c3a0 72 20 69 66 20 74 68 65 20 72 65 71 75 65 73 74 r if the request
2c3b0 65 64 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 ed table or colu
2c3c0 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 mn.** cannot be
2c3d0 66 6f 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f 72 found, an [error
2c3e0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e code] is return
2c3f0 65 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 ed and an error
2c400 6d 65 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a 20 message left.**
2c410 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 in the [database
2c420 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 6f connection] (to
2c430 20 62 65 20 72 65 74 72 69 65 76 65 64 20 75 73 be retrieved us
2c440 69 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72 6d ing sqlite3_errm
2c450 73 67 28 29 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 sg())..**.** Thi
2c460 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 s API is only av
2c470 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c ailable if the l
2c480 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 ibrary was compi
2c490 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 led with the.**
2c4a0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 [SQLITE_ENABLE_C
2c4b0 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 OLUMN_METADATA]
2c4c0 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 C-preprocessor s
2c4d0 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a ymbol defined..*
2c4e0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 /.int sqlite3_ta
2c4f0 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 ble_column_metad
2c500 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20 2a ata(. sqlite3 *
2c510 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 db,
2c520 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e /* Connection
2c530 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
2c540 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 st char *zDbName
2c550 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 , /* Data
2c560 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c base name or NUL
2c570 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 L */. const cha
2c580 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 r *zTableName,
2c590 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 /* Table name
2c5a0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
2c5b0 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 *zColumnName,
2c5c0 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 /* Column name
2c5d0 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 */. char const
2c5e0 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20 20 **pzDataType,
2c5f0 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 /* OUTPUT: Dec
2c600 6c 61 72 65 64 20 64 61 74 61 20 74 79 70 65 20 lared data type
2c610 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 */. char const
2c620 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 **pzCollSeq,
2c630 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c /* OUTPUT: Coll
2c640 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e ation sequence n
2c650 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e ame */. int *pN
2c660 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 otNull,
2c670 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 /* OUTPUT:
2c680 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c True if NOT NULL
2c690 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69 73 constraint exis
2c6a0 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 ts */. int *pPr
2c6b0 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20 20 imaryKey,
2c6c0 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 /* OUTPUT: T
2c6d0 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 rue if column pa
2c6e0 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e rt of PK */. in
2c6f0 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20 20 t *pAutoinc
2c700 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 /* OUT
2c710 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c PUT: True if col
2c720 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 umn is auto-incr
2c730 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a ement */.);../*.
2c740 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 ** CAPI3REF: Loa
2c750 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 20 7b d An Extension {
2c760 48 31 32 36 30 30 7d 20 3c 53 32 30 35 30 30 3e H12600} <S20500>
2c770 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 .**.** This inte
2c780 72 66 61 63 65 20 6c 6f 61 64 73 20 61 6e 20 53 rface loads an S
2c790 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 QLite extension
2c7a0 6c 69 62 72 61 72 79 20 66 72 6f 6d 20 74 68 65 library from the
2c7b0 20 6e 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a named file..**.
2c7c0 2a 2a 20 7b 48 31 32 36 30 31 7d 20 54 68 65 20 ** {H12601} The
2c7d0 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 sqlite3_load_ext
2c7e0 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 ension() interfa
2c7f0 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 6c ce attempts to l
2c800 6f 61 64 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 oad an.**
2c810 20 20 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 SQLite extens
2c820 69 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 ion library cont
2c830 61 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c ained in the fil
2c840 65 20 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b e zFile..**.** {
2c850 48 31 32 36 30 32 7d 20 54 68 65 20 65 6e 74 72 H12602} The entr
2c860 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72 6f 63 y point is zProc
2c870 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 33 7d ..**.** {H12603}
2c880 20 7a 50 72 6f 63 20 6d 61 79 20 62 65 20 30 2c zProc may be 0,
2c890 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 in which case t
2c8a0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 65 he name of the e
2c8b0 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 20 20 ntry point.**
2c8c0 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 73 20 defaults
2c8d0 74 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 to "sqlite3_exte
2c8e0 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 0a nsion_init"..**.
2c8f0 2a 2a 20 7b 48 31 32 36 30 34 7d 20 54 68 65 20 ** {H12604} The
2c900 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 sqlite3_load_ext
2c910 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 ension() interfa
2c920 63 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 0a ce shall return.
2c930 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c ** [SQL
2c940 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 ITE_OK] on succe
2c950 73 73 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45 ss and [SQLITE_E
2c960 52 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68 69 RROR] if somethi
2c970 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a ng goes wrong..*
2c980 2a 0a 2a 2a 20 7b 48 31 32 36 30 35 7d 20 49 66 *.** {H12605} If
2c990 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 an error occurs
2c9a0 20 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73 and pzErrMsg is
2c9b0 20 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74 68 65 not 0, then the
2c9c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
2c9d0 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e lite3_load_exten
2c9e0 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 sion()] interfac
2c9f0 65 20 73 68 61 6c 6c 20 61 74 74 65 6d 70 74 20 e shall attempt
2ca00 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 to.** f
2ca10 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 20 77 69 ill *pzErrMsg wi
2ca20 74 68 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 th error message
2ca30 20 74 65 78 74 20 73 74 6f 72 65 64 20 69 6e 20 text stored in
2ca40 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 memory.**
2ca50 20 20 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d obtained from
2ca60 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
2ca70 28 29 5d 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20 ()]. {END} The
2ca80 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e calling function
2ca90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 6f .** sho
2caa0 75 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d 65 uld free this me
2cab0 6d 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e 67 20 mory by calling
2cac0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
2cad0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 36 7d ..**.** {H12606}
2cae0 20 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 Extension loadi
2caf0 6e 67 20 6d 75 73 74 20 62 65 20 65 6e 61 62 6c ng must be enabl
2cb00 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 ed using.**
2cb10 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 6e [sqlite3_en
2cb20 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 able_load_extens
2cb30 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 ion()] prior to
2cb40 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 calling this API
2cb50 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 74 ,.** ot
2cb60 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 herwise an error
2cb70 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 will be returne
2cb80 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 d..*/.int sqlite
2cb90 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 3_load_extension
2cba0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
2cbb0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 /* Loa
2cbc0 64 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 d the extension
2cbd0 69 6e 74 6f 20 74 68 69 73 20 64 61 74 61 62 61 into this databa
2cbe0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f se connection */
2cbf0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
2cc00 46 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 File, /* Name
2cc10 20 6f 66 20 74 68 65 20 73 68 61 72 65 64 20 6c of the shared l
2cc20 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e ibrary containin
2cc30 67 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 g extension */.
2cc40 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 const char *zPr
2cc50 6f 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 oc, /* Entry
2cc60 70 6f 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20 point. Derived
2cc70 66 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 from zFile if 0
2cc80 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 */. char **pzEr
2cc90 72 4d 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75 rMsg /* Pu
2cca0 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 t error message
2ccb0 68 65 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f here if not 0 */
2ccc0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
2ccd0 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 REF: Enable Or D
2cce0 69 73 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e isable Extension
2ccf0 20 4c 6f 61 64 69 6e 67 20 7b 48 31 32 36 32 30 Loading {H12620
2cd00 7d 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a } <S20500>.**.**
2cd10 20 53 6f 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 So as not to op
2cd20 65 6e 20 73 65 63 75 72 69 74 79 20 68 6f 6c 65 en security hole
2cd30 73 20 69 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 s in older appli
2cd40 63 61 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 cations that are
2cd50 0a 2a 2a 20 75 6e 70 72 65 70 61 72 65 64 20 74 .** unprepared t
2cd60 6f 20 64 65 61 6c 20 77 69 74 68 20 65 78 74 65 o deal with exte
2cd70 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 nsion loading, a
2cd80 6e 64 20 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 nd as a means of
2cd90 20 64 69 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 disabling.** ex
2cda0 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 tension loading
2cdb0 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 while evaluating
2cdc0 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 user-entered SQ
2cdd0 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 L, the following
2cde0 20 41 50 49 0a 2a 2a 20 69 73 20 70 72 6f 76 69 API.** is provi
2cdf0 64 65 64 20 74 6f 20 74 75 72 6e 20 74 68 65 20 ded to turn the
2ce00 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 [sqlite3_load_ex
2ce10 74 65 6e 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 tension()] mecha
2ce20 6e 69 73 6d 20 6f 6e 20 61 6e 64 20 6f 66 66 2e nism on and off.
2ce30 0a 2a 2a 0a 2a 2a 20 45 78 74 65 6e 73 69 6f 6e .**.** Extension
2ce40 20 6c 6f 61 64 69 6e 67 20 69 73 20 6f 66 66 20 loading is off
2ce50 62 79 20 64 65 66 61 75 6c 74 2e 20 53 65 65 20 by default. See
2ce60 74 69 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a ticket #1863..**
2ce70 0a 2a 2a 20 7b 48 31 32 36 32 31 7d 20 43 61 6c .** {H12621} Cal
2ce80 6c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e l the sqlite3_en
2ce90 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 able_load_extens
2cea0 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65 20 77 69 ion() routine wi
2ceb0 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 20 th onoff==1.**
2cec0 20 20 20 20 20 20 20 20 74 6f 20 74 75 72 6e 20 to turn
2ced0 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e extension loadin
2cee0 67 20 6f 6e 20 61 6e 64 20 63 61 6c 6c 20 69 74 g on and call it
2cef0 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 30 20 74 with onoff==0 t
2cf00 6f 20 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 o turn.**
2cf10 20 20 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61 it back off a
2cf20 67 61 69 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 gain..**.** {H12
2cf30 36 32 32 7d 20 45 78 74 65 6e 73 69 6f 6e 20 6c 622} Extension l
2cf40 6f 61 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79 oading is off by
2cf50 20 64 65 66 61 75 6c 74 2e 0a 2a 2f 0a 69 6e 74 default..*/.int
2cf60 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f sqlite3_enable_
2cf70 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73 load_extension(s
2cf80 71 6c 69 74 65 33 20 2a 64 62 2c 20 69 6e 74 20 qlite3 *db, int
2cf90 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 onoff);../*.** C
2cfa0 41 50 49 33 52 45 46 3a 20 41 75 74 6f 6d 61 74 API3REF: Automat
2cfb0 69 63 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45 ically Load An E
2cfc0 78 74 65 6e 73 69 6f 6e 73 20 7b 48 31 32 36 34 xtensions {H1264
2cfd0 30 7d 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a 0} <S20500>.**.*
2cfe0 2a 20 54 68 69 73 20 41 50 49 20 63 61 6e 20 62 * This API can b
2cff0 65 20 69 6e 76 6f 6b 65 64 20 61 74 20 70 72 6f e invoked at pro
2d000 67 72 61 6d 20 73 74 61 72 74 75 70 20 69 6e 20 gram startup in
2d010 6f 72 64 65 72 20 74 6f 20 72 65 67 69 73 74 65 order to registe
2d020 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 r.** one or more
2d030 20 73 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b statically link
2d040 65 64 20 65 78 74 65 6e 73 69 6f 6e 73 20 74 68 ed extensions th
2d050 61 74 20 77 69 6c 6c 20 62 65 20 61 76 61 69 6c at will be avail
2d060 61 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e able.** to all n
2d070 65 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ew [database con
2d080 6e 65 63 74 69 6f 6e 73 5d 2e 20 7b 45 4e 44 7d nections]. {END}
2d090 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
2d0a0 69 6e 65 20 73 74 6f 72 65 73 20 61 20 70 6f 69 ine stores a poi
2d0b0 6e 74 65 72 20 74 6f 20 74 68 65 20 65 78 74 65 nter to the exte
2d0c0 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 61 72 72 61 nsion in an arra
2d0d0 79 20 74 68 61 74 20 69 73 0a 2a 2a 20 6f 62 74 y that is.** obt
2d0e0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 ained from [sqli
2d0f0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 te3_malloc()].
2d100 49 66 20 79 6f 75 20 72 75 6e 20 61 20 6d 65 6d If you run a mem
2d110 6f 72 79 20 6c 65 61 6b 20 63 68 65 63 6b 65 72 ory leak checker
2d120 0a 2a 2a 20 6f 6e 20 79 6f 75 72 20 70 72 6f 67 .** on your prog
2d130 72 61 6d 20 61 6e 64 20 69 74 20 72 65 70 6f 72 ram and it repor
2d140 74 73 20 61 20 6c 65 61 6b 20 62 65 63 61 75 73 ts a leak becaus
2d150 65 20 6f 66 20 74 68 69 73 20 61 72 72 61 79 2c e of this array,
2d160 20 69 6e 76 6f 6b 65 0a 2a 2a 20 5b 73 71 6c 69 invoke.** [sqli
2d170 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 te3_reset_auto_e
2d180 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f xtension()] prio
2d190 72 20 74 6f 20 73 68 75 74 64 6f 77 6e 20 74 6f r to shutdown to
2d1a0 20 66 72 65 65 20 74 68 65 20 6d 65 6d 6f 72 79 free the memory
2d1b0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34 31 7d ..**.** {H12641}
2d1c0 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 This function r
2d1d0 65 67 69 73 74 65 72 73 20 61 6e 20 65 78 74 65 egisters an exte
2d1e0 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e nsion entry poin
2d1f0 74 20 74 68 61 74 20 69 73 0a 2a 2a 20 20 20 20 t that is.**
2d200 20 20 20 20 20 20 61 75 74 6f 6d 61 74 69 63 61 automatica
2d210 6c 6c 79 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e lly invoked when
2d220 65 76 65 72 20 61 20 6e 65 77 20 5b 64 61 74 61 ever a new [data
2d230 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
2d240 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 .** is
2d250 6f 70 65 6e 65 64 20 75 73 69 6e 67 20 5b 73 71 opened using [sq
2d260 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b lite3_open()], [
2d270 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
2d280 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f ],.** o
2d290 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f r [sqlite3_open_
2d2a0 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 v2()]..**.** {H1
2d2b0 32 36 34 32 7d 20 44 75 70 6c 69 63 61 74 65 20 2642} Duplicate
2d2c0 65 78 74 65 6e 73 69 6f 6e 73 20 61 72 65 20 64 extensions are d
2d2d0 65 74 65 63 74 65 64 20 73 6f 20 63 61 6c 6c 69 etected so calli
2d2e0 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a ng this routine.
2d2f0 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 75 6c 74 ** mult
2d300 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68 20 iple times with
2d310 74 68 65 20 73 61 6d 65 20 65 78 74 65 6e 73 69 the same extensi
2d320 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 0a on is harmless..
2d330 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34 33 7d 20 54 **.** {H12643} T
2d340 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 his routine stor
2d350 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 es a pointer to
2d360 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e the extension in
2d370 20 61 6e 20 61 72 72 61 79 0a 2a 2a 20 20 20 20 an array.**
2d380 20 20 20 20 20 20 74 68 61 74 20 69 73 20 6f 62 that is ob
2d390 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c tained from [sql
2d3a0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a ite3_malloc()]..
2d3b0 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34 34 7d 20 41 **.** {H12644} A
2d3c0 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 utomatic extensi
2d3d0 6f 6e 73 20 61 70 70 6c 79 20 61 63 72 6f 73 73 ons apply across
2d3e0 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f all threads..*/
2d3f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 75 74 .int sqlite3_aut
2d400 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 o_extension(void
2d410 20 28 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29 28 (*xEntryPoint)(
2d420 76 6f 69 64 29 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 void));../*.** C
2d430 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 API3REF: Reset A
2d440 75 74 6f 6d 61 74 69 63 20 45 78 74 65 6e 73 69 utomatic Extensi
2d450 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b 48 31 32 36 on Loading {H126
2d460 36 30 7d 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 60} <S20500>.**.
2d470 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e ** This function
2d480 20 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 70 72 disables all pr
2d490 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 eviously registe
2d4a0 72 65 64 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a red automatic.**
2d4b0 20 65 78 74 65 6e 73 69 6f 6e 73 2e 20 7b 45 4e extensions. {EN
2d4c0 44 7d 20 20 49 74 20 75 6e 64 6f 65 73 20 74 68 D} It undoes th
2d4d0 65 20 65 66 66 65 63 74 20 6f 66 20 61 6c 6c 20 e effect of all
2d4e0 70 72 69 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 prior.** [sqlite
2d4f0 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 3_auto_extension
2d500 28 29 5d 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a ()] calls..**.**
2d510 20 7b 48 31 32 36 36 31 7d 20 54 68 69 73 20 66 {H12661} This f
2d520 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 unction disables
2d530 20 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 all previously
2d540 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 20 registered.**
2d550 20 20 20 20 20 20 20 61 75 74 6f 6d 61 74 69 63 automatic
2d560 20 65 78 74 65 6e 73 69 6f 6e 73 2e 0a 2a 2a 0a extensions..**.
2d570 2a 2a 20 7b 48 31 32 36 36 32 7d 20 54 68 69 73 ** {H12662} This
2d580 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c function disabl
2d590 65 73 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74 es automatic ext
2d5a0 65 6e 73 69 6f 6e 73 20 69 6e 20 61 6c 6c 20 74 ensions in all t
2d5b0 68 72 65 61 64 73 2e 0a 2a 2f 0a 76 6f 69 64 20 hreads..*/.void
2d5c0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75 sqlite3_reset_au
2d5d0 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 to_extension(voi
2d5e0 64 29 3b 0a 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a 20 45 d);../*.****** E
2d5f0 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 XPERIMENTAL - su
2d600 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 bject to change
2d610 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a without notice *
2d620 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a *************.**
2d630 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 .** The interfac
2d640 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c e to the virtual
2d650 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d -table mechanism
2d660 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f is currently co
2d670 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 nsidered.** to b
2d680 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 e experimental.
2d690 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d The interface m
2d6a0 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 ight change in i
2d6b0 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 ncompatible ways
2d6c0 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 ..** If this is
2d6d0 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f a problem for yo
2d6e0 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 u, do not use th
2d6f0 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 e interface at t
2d700 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 his time..**.**
2d710 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c When the virtual
2d720 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d -table mechanism
2d730 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 stabilizes, we
2d740 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 will declare the
2d750 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 .** interface fi
2d760 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 xed, support it
2d770 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e indefinitely, an
2d780 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f d remove this co
2d790 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a mment..*/../*.**
2d7a0 20 53 74 72 75 63 74 75 72 65 73 20 75 73 65 64 Structures used
2d7b0 20 62 79 20 74 68 65 20 76 69 72 74 75 61 6c 20 by the virtual
2d7c0 74 61 62 6c 65 20 69 6e 74 65 72 66 61 63 65 0a table interface.
2d7d0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
2d7e0 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 73 t sqlite3_vtab s
2d7f0 71 6c 69 74 65 33 5f 76 74 61 62 3b 0a 74 79 70 qlite3_vtab;.typ
2d800 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
2d810 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 te3_index_info s
2d820 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 qlite3_index_inf
2d830 6f 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 o;.typedef struc
2d840 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 t sqlite3_vtab_c
2d850 75 72 73 6f 72 20 73 71 6c 69 74 65 33 5f 76 74 ursor sqlite3_vt
2d860 61 62 5f 63 75 72 73 6f 72 3b 0a 74 79 70 65 64 ab_cursor;.typed
2d870 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
2d880 33 5f 6d 6f 64 75 6c 65 20 73 71 6c 69 74 65 33 3_module sqlite3
2d890 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 _module;../*.**
2d8a0 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 CAPI3REF: Virtua
2d8b0 6c 20 54 61 62 6c 65 20 4f 62 6a 65 63 74 20 7b l Table Object {
2d8c0 48 31 38 30 30 30 7d 20 3c 53 32 30 34 30 30 3e H18000} <S20400>
2d8d0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 .** KEYWORDS: sq
2d8e0 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 76 69 lite3_module {vi
2d8f0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 rtual table modu
2d900 6c 65 7d 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e le}.** EXPERIMEN
2d910 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 TAL.**.** This s
2d920 74 72 75 63 74 75 72 65 2c 20 73 6f 6d 65 74 69 tructure, someti
2d930 6d 65 73 20 63 61 6c 6c 65 64 20 61 20 61 20 22 mes called a a "
2d940 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f virtual table mo
2d950 64 75 6c 65 22 2c 20 0a 2a 2a 20 64 65 66 69 6e dule", .** defin
2d960 65 73 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 es the implement
2d970 61 74 69 6f 6e 20 6f 66 20 61 20 5b 76 69 72 74 ation of a [virt
2d980 75 61 6c 20 74 61 62 6c 65 73 5d 2e 20 20 0a 2a ual tables]. .*
2d990 2a 20 54 68 69 73 20 73 74 72 75 63 74 75 72 65 * This structure
2d9a0 20 63 6f 6e 73 69 73 74 73 20 6d 6f 73 74 6c 79 consists mostly
2d9b0 20 6f 66 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 of methods for
2d9c0 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a the module..**.*
2d9d0 2a 20 41 20 76 69 72 74 75 61 6c 20 74 61 62 6c * A virtual tabl
2d9e0 65 20 6d 6f 64 75 6c 65 20 69 73 20 63 72 65 61 e module is crea
2d9f0 74 65 64 20 62 79 20 66 69 6c 6c 69 6e 67 20 69 ted by filling i
2da00 6e 20 61 20 70 65 72 73 69 73 74 65 6e 74 0a 2a n a persistent.*
2da10 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 * instance of th
2da20 69 73 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 is structure and
2da30 20 70 61 73 73 69 6e 67 20 61 20 70 6f 69 6e 74 passing a point
2da40 65 72 20 74 6f 20 74 68 61 74 20 69 6e 73 74 61 er to that insta
2da50 6e 63 65 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 nce.** to [sqlit
2da60 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 e3_create_module
2da70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
2da80 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 create_module_v2
2da90 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 72 65 67 69 ()]..** The regi
2daa0 73 74 72 61 74 69 6f 6e 20 72 65 6d 61 69 6e 73 stration remains
2dab0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 69 74 20 valid until it
2dac0 69 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 is replaced by a
2dad0 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 6d 6f different.** mo
2dae0 64 75 6c 65 20 6f 72 20 75 6e 74 69 6c 20 74 68 dule or until th
2daf0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
2db00 65 63 74 69 6f 6e 5d 20 63 6c 6f 73 65 73 2e 20 ection] closes.
2db10 20 54 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 The content.**
2db20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 of this structur
2db30 65 20 6d 75 73 74 20 6e 6f 74 20 63 68 61 6e 67 e must not chang
2db40 65 20 77 68 69 6c 65 20 69 74 20 69 73 20 72 65 e while it is re
2db50 67 69 73 74 65 72 65 64 20 77 69 74 68 0a 2a 2a gistered with.**
2db60 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f any database co
2db70 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 74 72 nnection..*/.str
2db80 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 uct sqlite3_modu
2db90 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 le {. int iVers
2dba0 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72 ion;. int (*xCr
2dbb0 65 61 74 65 29 28 73 71 6c 69 74 65 33 2a 2c 20 eate)(sqlite3*,
2dbc0 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 void *pAux,.
2dbd0 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 int a
2dbe0 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 rgc, const char
2dbf0 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 *const*argv,.
2dc00 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 sqli
2dc10 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 te3_vtab **ppVTa
2dc20 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e b, char**);. in
2dc30 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71 t (*xConnect)(sq
2dc40 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 lite3*, void *pA
2dc50 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 ux,.
2dc60 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e int argc, con
2dc70 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 st char *const*a
2dc80 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 rgv,.
2dc90 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 sqlite3_vtab
2dca0 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a **ppVTab, char*
2dcb0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 73 *);. int (*xBes
2dcc0 74 49 6e 64 65 78 29 28 73 71 6c 69 74 65 33 5f tIndex)(sqlite3_
2dcd0 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c vtab *pVTab, sql
2dce0 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a ite3_index_info*
2dcf0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 69 73 63 );. int (*xDisc
2dd00 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 5f onnect)(sqlite3_
2dd10 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 vtab *pVTab);.
2dd20 69 6e 74 20 28 2a 78 44 65 73 74 72 6f 79 29 28 int (*xDestroy)(
2dd30 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 sqlite3_vtab *pV
2dd40 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f Tab);. int (*xO
2dd50 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 pen)(sqlite3_vta
2dd60 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 b *pVTab, sqlite
2dd70 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a 3_vtab_cursor **
2dd80 70 70 43 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74 ppCursor);. int
2dd90 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 (*xClose)(sqlit
2dda0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 e3_vtab_cursor*)
2ddb0 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 74 65 ;. int (*xFilte
2ddc0 72 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f r)(sqlite3_vtab_
2ddd0 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78 cursor*, int idx
2dde0 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 Num, const char
2ddf0 2a 69 64 78 53 74 72 2c 0a 20 20 20 20 20 20 20 *idxStr,.
2de00 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 int arg
2de10 63 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 c, sqlite3_value
2de20 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69 6e 74 20 **argv);. int
2de30 28 2a 78 4e 65 78 74 29 28 73 71 6c 69 74 65 33 (*xNext)(sqlite3
2de40 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a _vtab_cursor*);.
2de50 20 20 69 6e 74 20 28 2a 78 45 6f 66 29 28 73 71 int (*xEof)(sq
2de60 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f lite3_vtab_curso
2de70 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f r*);. int (*xCo
2de80 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 lumn)(sqlite3_vt
2de90 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 ab_cursor*, sqli
2dea0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
2deb0 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77 t);. int (*xRow
2dec0 69 64 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 id)(sqlite3_vtab
2ded0 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 _cursor*, sqlite
2dee0 33 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69 64 29 3_int64 *pRowid)
2def0 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70 64 61 74 ;. int (*xUpdat
2df00 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 e)(sqlite3_vtab
2df10 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f *, int, sqlite3_
2df20 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65 value **, sqlite
2df30 33 5f 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e 3_int64 *);. in
2df40 74 20 28 2a 78 42 65 67 69 6e 29 28 73 71 6c 69 t (*xBegin)(sqli
2df50 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 te3_vtab *pVTab)
2df60 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 ;. int (*xSync)
2df70 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 (sqlite3_vtab *p
2df80 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 VTab);. int (*x
2df90 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74 65 33 5f Commit)(sqlite3_
2dfa0 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 vtab *pVTab);.
2dfb0 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 int (*xRollback)
2dfc0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 (sqlite3_vtab *p
2dfd0 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 VTab);. int (*x
2dfe0 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73 71 FindFunction)(sq
2dff0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 lite3_vtab *pVta
2e000 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e b, int nArg, con
2e010 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a st 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 20 20 76 6f 69 64 20 28 2a 2a 70 void (**p
2e040 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 xFunc)(sqlite3_c
2e050 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 ontext*,int,sqli
2e060 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 te3_value**),.
2e070 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2e080 20 20 20 20 20 76 6f 69 64 20 2a 2a 70 70 41 72 void **ppAr
2e090 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e g);. int (*xRen
2e0a0 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 ame)(sqlite3_vta
2e0b0 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74 20 b *pVtab, const
2e0c0 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a char *zNew);.};.
2e0d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2e0e0 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 Virtual Table I
2e0f0 6e 64 65 78 69 6e 67 20 49 6e 66 6f 72 6d 61 74 ndexing Informat
2e100 69 6f 6e 20 7b 48 31 38 31 30 30 7d 20 3c 53 32 ion {H18100} <S2
2e110 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 0400>.** KEYWORD
2e120 53 3a 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 S: sqlite3_index
2e130 5f 69 6e 66 6f 0a 2a 2a 20 45 58 50 45 52 49 4d _info.** EXPERIM
2e140 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ENTAL.**.** The
2e150 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e sqlite3_index_in
2e160 66 6f 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 fo structure and
2e170 20 69 74 73 20 73 75 62 73 74 72 75 63 74 75 72 its substructur
2e180 65 73 20 69 73 20 75 73 65 64 20 74 6f 0a 2a 2a es is used to.**
2e190 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 74 69 6f pass informatio
2e1a0 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65 63 65 69 n into and recei
2e1b0 76 65 20 74 68 65 20 72 65 70 6c 79 20 66 72 6f ve the reply fro
2e1c0 6d 20 74 68 65 20 5b 78 42 65 73 74 49 6e 64 65 m the [xBestInde
2e1d0 78 5d 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 x].** method of
2e1e0 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 a [virtual table
2e1f0 20 6d 6f 64 75 6c 65 5d 2e 20 20 54 68 65 20 66 module]. The f
2e200 69 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e ields under **In
2e210 70 75 74 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a puts** are the.*
2e220 2a 20 69 6e 70 75 74 73 20 74 6f 20 78 42 65 73 * inputs to xBes
2e230 74 49 6e 64 65 78 20 61 6e 64 20 61 72 65 20 72 tIndex and are r
2e240 65 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74 ead-only. xBest
2e250 49 6e 64 65 78 20 69 6e 73 65 72 74 73 20 69 74 Index inserts it
2e260 73 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 s.** results int
2e270 6f 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a o the **Outputs*
2e280 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 * fields..**.**
2e290 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b The aConstraint[
2e2a0 5d 20 61 72 72 61 79 20 72 65 63 6f 72 64 73 20 ] array records
2e2b0 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e WHERE clause con
2e2c0 73 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65 20 straints of the
2e2d0 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 form:.**.** <pre
2e2e0 3e 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c >column OP expr<
2e2f0 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 /pre>.**.** wher
2e300 65 20 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c e OP is =, <,
2e310 20 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72 <=, >, or
2e320 20 26 67 74 3b 3d 2e 20 20 54 68 65 20 70 61 72 >=. The par
2e330 74 69 63 75 6c 61 72 20 6f 70 65 72 61 74 6f 72 ticular operator
2e340 20 69 73 0a 2a 2a 20 73 74 6f 72 65 64 20 69 6e is.** stored in
2e350 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f aConstraint[].o
2e360 70 2e 20 20 54 68 65 20 69 6e 64 65 78 20 6f 66 p. The index of
2e370 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73 the column is s
2e380 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61 43 6f 6e tored in.** aCon
2e390 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d straint[].iColum
2e3a0 6e 2e 20 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b n. aConstraint[
2e3b0 5d 2e 75 73 61 62 6c 65 20 69 73 20 54 52 55 45 ].usable is TRUE
2e3c0 20 69 66 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 if the.** expr
2e3d0 6f 6e 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e on the right-han
2e3e0 64 20 73 69 64 65 20 63 61 6e 20 62 65 20 65 76 d side can be ev
2e3f0 61 6c 75 61 74 65 64 20 28 61 6e 64 20 74 68 75 aluated (and thu
2e400 73 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 s the constraint
2e410 0a 2a 2a 20 69 73 20 75 73 61 62 6c 65 29 20 61 .** is usable) a
2e420 6e 64 20 66 61 6c 73 65 20 69 66 20 69 74 20 63 nd false if it c
2e430 61 6e 6e 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 annot..**.** The
2e440 20 6f 70 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d optimizer autom
2e450 61 74 69 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 atically inverts
2e460 20 74 65 72 6d 73 20 6f 66 20 74 68 65 20 66 6f terms of the fo
2e470 72 6d 20 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 rm "expr OP colu
2e480 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 mn".** and makes
2e490 20 6f 74 68 65 72 20 73 69 6d 70 6c 69 66 69 63 other simplific
2e4a0 61 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 57 48 ations to the WH
2e4b0 45 52 45 20 63 6c 61 75 73 65 20 69 6e 20 61 6e ERE clause in an
2e4c0 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 attempt to.** g
2e4d0 65 74 20 61 73 20 6d 61 6e 79 20 57 48 45 52 45 et as many WHERE
2e4e0 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e clause terms in
2e4f0 74 6f 20 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 to the form show
2e500 6e 20 61 62 6f 76 65 20 61 73 20 70 6f 73 73 69 n above as possi
2e510 62 6c 65 2e 0a 2a 2a 20 54 68 65 20 61 43 6f 6e ble..** The aCon
2e520 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 straint[] array
2e530 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 57 48 45 only reports WHE
2e540 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 RE clause terms
2e550 69 6e 20 74 68 65 20 63 6f 72 72 65 63 74 0a 2a in the correct.*
2e560 2a 20 66 6f 72 6d 20 74 68 61 74 20 72 65 66 65 * form that refe
2e570 72 20 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 r to the particu
2e580 6c 61 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c lar virtual tabl
2e590 65 20 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e e being queried.
2e5a0 0a 2a 2a 0a 2a 2a 20 49 6e 66 6f 72 6d 61 74 69 .**.** Informati
2e5b0 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 on about the ORD
2e5c0 45 52 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 ER BY clause is
2e5d0 73 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 stored in aOrder
2e5e0 42 79 5b 5d 2e 0a 2a 2a 20 45 61 63 68 20 74 65 By[]..** Each te
2e5f0 72 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72 rm of aOrderBy r
2e600 65 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 ecords a column
2e610 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 of the ORDER BY
2e620 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 clause..**.** Th
2e630 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 20 6d e [xBestIndex] m
2e640 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 ethod must fill
2e650 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 aConstraintUsage
2e660 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 [] with informat
2e670 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 ion.** about wha
2e680 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 t parameters to
2e690 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e pass to xFilter.
2e6a0 20 20 49 66 20 61 72 67 76 49 6e 64 65 78 3e 30 If argvIndex>0
2e6b0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67 then.** the rig
2e6c0 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 ht-hand side of
2e6d0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e the correspondin
2e6e0 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 g aConstraint[]
2e6f0 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 is evaluated.**
2e700 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 and becomes the
2e710 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65 6e 74 argvIndex-th ent
2e720 72 79 20 69 6e 20 61 72 67 76 2e 20 20 49 66 20 ry in argv. If
2e730 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 aConstraintUsage
2e740 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72 [].omit.** is tr
2e750 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6e ue, then the con
2e760 73 74 72 61 69 6e 74 20 69 73 20 61 73 73 75 6d straint is assum
2e770 65 64 20 74 6f 20 62 65 20 66 75 6c 6c 79 20 68 ed to be fully h
2e780 61 6e 64 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a andled by the.**
2e790 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 virtual table a
2e7a0 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 63 6b 65 nd is not checke
2e7b0 64 20 61 67 61 69 6e 20 62 79 20 53 51 4c 69 74 d again by SQLit
2e7c0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 64 78 e..**.** The idx
2e7d0 4e 75 6d 20 61 6e 64 20 69 64 78 50 74 72 20 76 Num and idxPtr v
2e7e0 61 6c 75 65 73 20 61 72 65 20 72 65 63 6f 72 64 alues are record
2e7f0 65 64 20 61 6e 64 20 70 61 73 73 65 64 20 69 6e ed and passed in
2e800 74 6f 20 74 68 65 0a 2a 2a 20 5b 78 46 69 6c 74 to the.** [xFilt
2e810 65 72 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2a 20 5b er] method..** [
2e820 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 sqlite3_free()]
2e830 69 73 20 75 73 65 64 20 74 6f 20 66 72 65 65 20 is used to free
2e840 69 64 78 50 74 72 20 69 66 20 61 6e 64 20 6f 6e idxPtr if and on
2e850 6c 79 20 69 66 66 0a 2a 2a 20 6e 65 65 64 54 6f ly iff.** needTo
2e860 46 72 65 65 49 64 78 50 74 72 20 69 73 20 74 72 FreeIdxPtr is tr
2e870 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 72 ue..**.** The or
2e880 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d 65 derByConsumed me
2e890 61 6e 73 20 74 68 61 74 20 6f 75 74 70 75 74 20 ans that output
2e8a0 66 72 6f 6d 20 5b 78 46 69 6c 74 65 72 5d 2f 5b from [xFilter]/[
2e8b0 78 4e 65 78 74 5d 20 77 69 6c 6c 20 6f 63 63 75 xNext] will occu
2e8c0 72 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72 r in.** the corr
2e8d0 65 63 74 20 6f 72 64 65 72 20 74 6f 20 73 61 74 ect order to sat
2e8e0 69 73 66 79 20 74 68 65 20 4f 52 44 45 52 20 42 isfy the ORDER B
2e8f0 59 20 63 6c 61 75 73 65 20 73 6f 20 74 68 61 74 Y clause so that
2e900 20 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 no separate.**
2e910 73 6f 72 74 69 6e 67 20 73 74 65 70 20 69 73 20 sorting step is
2e920 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 required..**.**
2e930 54 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 The estimatedCos
2e940 74 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65 73 t value is an es
2e950 74 69 6d 61 74 65 20 6f 66 20 74 68 65 20 63 6f timate of the co
2e960 73 74 20 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a st of doing the.
2e970 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 6c 6f ** particular lo
2e980 6f 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20 73 63 okup. A full sc
2e990 61 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 77 69 an of a table wi
2e9a0 74 68 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f th N entries sho
2e9b0 75 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f uld have.** a co
2e9c0 73 74 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61 st of N. A bina
2e9d0 72 79 20 73 65 61 72 63 68 20 6f 66 20 61 20 74 ry search of a t
2e9e0 61 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69 65 able of N entrie
2e9f0 73 20 73 68 6f 75 6c 64 20 68 61 76 65 20 61 0a s should have a.
2ea00 2a 2a 20 63 6f 73 74 20 6f 66 20 61 70 70 72 6f ** cost of appro
2ea10 78 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e ximately log(N).
2ea20 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 .*/.struct sqlit
2ea30 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a e3_index_info {.
2ea40 20 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20 /* Inputs */.
2ea50 20 69 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74 int nConstraint
2ea60 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e ; /* N
2ea70 75 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73 umber of entries
2ea80 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 20 in aConstraint
2ea90 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 */. struct sqli
2eaa0 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 te3_index_constr
2eab0 61 69 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74 20 aint {. int
2eac0 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 iColumn;
2ead0 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 /* Column
2eae0 6f 6e 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 on left-hand sid
2eaf0 65 20 6f 66 20 63 6f 6e 73 74 72 61 69 6e 74 20 e of constraint
2eb00 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 */. unsigned
2eb10 20 63 68 61 72 20 6f 70 3b 20 20 20 20 20 20 20 char op;
2eb20 20 20 2f 2a 20 43 6f 6e 73 74 72 61 69 6e 74 20 /* Constraint
2eb30 6f 70 65 72 61 74 6f 72 20 2a 2f 0a 20 20 20 20 operator */.
2eb40 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 75 unsigned char u
2eb50 73 61 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54 72 sable; /* Tr
2eb60 75 65 20 69 66 20 74 68 69 73 20 63 6f 6e 73 74 ue if this const
2eb70 72 61 69 6e 74 20 69 73 20 75 73 61 62 6c 65 20 raint is usable
2eb80 2a 2f 0a 20 20 20 20 20 69 6e 74 20 69 54 65 72 */. int iTer
2eb90 6d 4f 66 66 73 65 74 3b 20 20 20 20 20 20 20 20 mOffset;
2eba0 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e /* Used intern
2ebb0 61 6c 6c 79 20 2d 20 78 42 65 73 74 49 6e 64 65 ally - xBestInde
2ebc0 78 20 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65 20 x should ignore
2ebd0 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 */. } *aConstra
2ebe0 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20 20 int;
2ebf0 2f 2a 20 54 61 62 6c 65 20 6f 66 20 57 48 45 52 /* Table of WHER
2ec00 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 E clause constra
2ec10 69 6e 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 4f ints */. int nO
2ec20 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 rderBy;
2ec30 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f /* Number o
2ec40 66 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20 4f f terms in the O
2ec50 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a RDER BY clause *
2ec60 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 /. struct sqlit
2ec70 65 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62 79 e3_index_orderby
2ec80 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c {. int iCol
2ec90 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 umn;
2eca0 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 /* Column numb
2ecb0 65 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 er */. unsig
2ecc0 6e 65 64 20 63 68 61 72 20 64 65 73 63 3b 20 20 ned char desc;
2ecd0 20 20 20 20 20 2f 2a 20 54 72 75 65 20 66 6f 72 /* True for
2ece0 20 44 45 53 43 2e 20 20 46 61 6c 73 65 20 66 6f DESC. False fo
2ecf0 72 20 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 61 r ASC. */. } *a
2ed00 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 OrderBy;
2ed10 20 20 20 20 20 20 20 2f 2a 20 54 68 65 20 4f 52 /* The OR
2ed20 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f DER BY clause */
2ed30 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f . /* Outputs */
2ed40 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 . struct sqlite
2ed50 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 3_index_constrai
2ed60 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20 20 20 69 nt_usage {. i
2ed70 6e 74 20 61 72 67 76 49 6e 64 65 78 3b 20 20 20 nt argvIndex;
2ed80 20 20 20 20 20 20 20 20 2f 2a 20 69 66 20 3e 30 /* if >0
2ed90 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 , constraint is
2eda0 70 61 72 74 20 6f 66 20 61 72 67 76 20 74 6f 20 part of argv to
2edb0 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75 xFilter */. u
2edc0 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 6d 69 nsigned char omi
2edd0 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f t; /* Do no
2ede0 74 20 63 6f 64 65 20 61 20 74 65 73 74 20 66 6f t code a test fo
2edf0 72 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e r this constrain
2ee00 74 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 t */. } *aConst
2ee10 72 61 69 6e 74 55 73 61 67 65 3b 0a 20 20 69 6e raintUsage;. in
2ee20 74 20 69 64 78 4e 75 6d 3b 20 20 20 20 20 20 20 t idxNum;
2ee30 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 /* Numb
2ee40 65 72 20 75 73 65 64 20 74 6f 20 69 64 65 6e 74 er used to ident
2ee50 69 66 79 20 74 68 65 20 69 6e 64 65 78 20 2a 2f ify the index */
2ee60 0a 20 20 63 68 61 72 20 2a 69 64 78 53 74 72 3b . char *idxStr;
2ee70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
2ee80 20 53 74 72 69 6e 67 2c 20 70 6f 73 73 69 62 6c String, possibl
2ee90 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
2eea0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a sqlite3_malloc *
2eeb0 2f 0a 20 20 69 6e 74 20 6e 65 65 64 54 6f 46 72 /. int needToFr
2eec0 65 65 49 64 78 53 74 72 3b 20 20 20 20 20 20 2f eeIdxStr; /
2eed0 2a 20 46 72 65 65 20 69 64 78 53 74 72 20 75 73 * Free idxStr us
2eee0 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 ing sqlite3_free
2eef0 28 29 20 69 66 20 74 72 75 65 20 2a 2f 0a 20 20 () if true */.
2ef00 69 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 int orderByConsu
2ef10 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 med; /* Tr
2ef20 75 65 20 69 66 20 6f 75 74 70 75 74 20 69 73 20 ue if output is
2ef30 61 6c 72 65 61 64 79 20 6f 72 64 65 72 65 64 20 already ordered
2ef40 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 65 73 74 69 */. double esti
2ef50 6d 61 74 65 64 43 6f 73 74 3b 20 20 20 20 20 20 matedCost;
2ef60 2f 2a 20 45 73 74 69 6d 61 74 65 64 20 63 6f 73 /* Estimated cos
2ef70 74 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 20 t of using this
2ef80 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 23 64 65 66 index */.};.#def
2ef90 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 ine SQLITE_INDEX
2efa0 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 20 _CONSTRAINT_EQ
2efb0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 2.#define SQLI
2efc0 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 TE_INDEX_CONSTRA
2efd0 49 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 65 66 INT_GT 4.#def
2efe0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 ine SQLITE_INDEX
2eff0 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20 20 _CONSTRAINT_LE
2f000 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8.#define SQLI
2f010 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 TE_INDEX_CONSTRA
2f020 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 64 65 INT_LT 16.#de
2f030 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 fine SQLITE_INDE
2f040 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45 20 X_CONSTRAINT_GE
2f050 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53 51 32.#define SQ
2f060 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 LITE_INDEX_CONST
2f070 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a 0a RAINT_MATCH 64..
2f080 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2f090 52 65 67 69 73 74 65 72 20 41 20 56 69 72 74 75 Register A Virtu
2f0a0 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 al Table Impleme
2f0b0 6e 74 61 74 69 6f 6e 20 7b 48 31 38 32 30 30 7d ntation {H18200}
2f0c0 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50 <S20400>.** EXP
2f0d0 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 ERIMENTAL.**.**
2f0e0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 This routine is
2f0f0 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 used to register
2f100 20 61 20 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 a new [virtual
2f110 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 6e 61 table module] na
2f120 6d 65 2e 0a 2a 2a 20 4d 6f 64 75 6c 65 20 6e 61 me..** Module na
2f130 6d 65 73 20 6d 75 73 74 20 62 65 20 72 65 67 69 mes must be regi
2f140 73 74 65 72 65 64 20 62 65 66 6f 72 65 0a 2a 2a stered before.**
2f150 20 63 72 65 61 74 69 6e 67 20 61 20 6e 65 77 20 creating a new
2f160 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 [virtual table]
2f170 75 73 69 6e 67 20 74 68 65 20 6d 6f 64 75 6c 65 using the module
2f180 2c 20 6f 72 20 62 65 66 6f 72 65 20 75 73 69 6e , or before usin
2f190 67 20 61 0a 2a 2a 20 70 72 65 65 78 69 73 74 69 g a.** preexisti
2f1a0 6e 67 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c ng [virtual tabl
2f1b0 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c e] for the modul
2f1c0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 6f 64 e..**.** The mod
2f1d0 75 6c 65 20 6e 61 6d 65 20 69 73 20 72 65 67 69 ule name is regi
2f1e0 73 74 65 72 65 64 20 6f 6e 20 74 68 65 20 5b 64 stered on the [d
2f1f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2f200 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 0a 2a 2a on] specified.**
2f210 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 by the first pa
2f220 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6e 61 rameter. The na
2f230 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 me of the module
2f240 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 is given by the
2f250 20 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 .** second para
2f260 6d 65 74 65 72 2e 20 20 54 68 65 20 74 68 69 72 meter. The thir
2f270 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 d parameter is a
2f280 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 74 pointer to.** t
2f290 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
2f2a0 6e 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 n of the [virtua
2f2b0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e l table module].
2f2c0 20 20 20 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a The fourth.**
2f2d0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e parameter is an
2f2e0 20 61 72 62 69 74 72 61 72 79 20 63 6c 69 65 6e arbitrary clien
2f2f0 74 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 t data pointer t
2f300 68 61 74 20 69 73 20 70 61 73 73 65 64 20 74 68 hat is passed th
2f310 72 6f 75 67 68 0a 2a 2a 20 69 6e 74 6f 20 74 68 rough.** into th
2f320 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 20 e [xCreate] and
2f330 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f [xConnect] metho
2f340 64 73 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 ds of the virtua
2f350 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 0a 2a l table module.*
2f360 2a 20 77 68 65 6e 20 61 20 6e 65 77 20 76 69 72 * when a new vir
2f370 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20 62 65 tual table is be
2f380 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 20 6f being created o
2f390 72 20 72 65 69 6e 69 74 69 61 6c 69 7a 65 64 2e r reinitialized.
2f3a0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 .**.** This inte
2f3b0 72 66 61 63 65 20 68 61 73 20 65 78 61 63 74 6c rface has exactl
2f3c0 79 20 74 68 65 20 73 61 6d 65 20 65 66 66 65 63 y the same effec
2f3d0 74 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 t as calling.**
2f3e0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
2f3f0 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 20 77 69 74 module_v2()] wit
2f400 68 20 61 20 4e 55 4c 4c 20 63 6c 69 65 6e 74 20 h a NULL client
2f410 64 61 74 61 20 64 65 73 74 72 75 63 74 6f 72 2e data destructor.
2f420 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 .*/.SQLITE_EXPER
2f430 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 IMENTAL int sqli
2f440 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c te3_create_modul
2f450 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 e(. sqlite3 *db
2f460 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
2f470 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 /* SQLite connec
2f480 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 tion to register
2f490 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a module with */.
2f4a0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e const char *zN
2f4b0 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 ame, /*
2f4c0 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 Name of the modu
2f4d0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 le */. const sq
2f4e0 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c lite3_module *p,
2f4f0 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f /* Methods fo
2f500 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a r the module */.
2f510 20 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44 void *pClientD
2f520 61 74 61 20 20 20 20 20 20 20 20 20 20 2f 2a 20 ata /*
2f530 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 Client data for
2f540 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 xCreate/xConnect
2f550 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.);../*.** CA
2f560 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 PI3REF: Register
2f570 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 A Virtual Table
2f580 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 Implementation
2f590 7b 48 31 38 32 31 30 7d 20 3c 53 32 30 34 30 30 {H18210} <S20400
2f5a0 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 >.** EXPERIMENTA
2f5b0 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 L.**.** This rou
2f5c0 74 69 6e 65 20 69 73 20 69 64 65 6e 74 69 63 61 tine is identica
2f5d0 6c 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 l to the [sqlite
2f5e0 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 3_create_module(
2f5f0 29 5d 20 6d 65 74 68 6f 64 2c 0a 2a 2a 20 65 78 )] method,.** ex
2f600 63 65 70 74 20 74 68 61 74 20 69 74 20 68 61 73 cept that it has
2f610 20 61 6e 20 65 78 74 72 61 20 70 61 72 61 6d 65 an extra parame
2f620 74 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 0a ter to specify .
2f630 2a 2a 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 ** a destructor
2f640 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 74 68 65 function for the
2f650 20 63 6c 69 65 6e 74 20 64 61 74 61 20 70 6f 69 client data poi
2f660 6e 74 65 72 2e 20 20 53 51 4c 69 74 65 20 77 69 nter. SQLite wi
2f670 6c 6c 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 ll.** invoke the
2f680 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 destructor func
2f690 74 69 6f 6e 20 28 69 66 20 69 74 20 69 73 20 6e tion (if it is n
2f6a0 6f 74 20 4e 55 4c 4c 29 20 77 68 65 6e 20 53 51 ot NULL) when SQ
2f6b0 4c 69 74 65 0a 2a 2a 20 6e 6f 20 6c 6f 6e 67 65 Lite.** no longe
2f6c0 72 20 6e 65 65 64 73 20 74 68 65 20 70 43 6c 69 r needs the pCli
2f6d0 65 6e 74 44 61 74 61 20 70 6f 69 6e 74 65 72 2e entData pointer.
2f6e0 20 20 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 .*/.SQLITE_EXP
2f6f0 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 ERIMENTAL int sq
2f700 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 lite3_create_mod
2f710 75 6c 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 ule_v2(. sqlite
2f720 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
2f730 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 /* SQLite c
2f740 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 onnection to reg
2f750 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 ister module wit
2f760 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 h */. const cha
2f770 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 r *zName,
2f780 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 /* Name of the
2f790 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e module */. con
2f7a0 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c st sqlite3_modul
2f7b0 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f e *p, /* Metho
2f7c0 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c ds for the modul
2f7d0 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c e */. void *pCl
2f7e0 69 65 6e 74 44 61 74 61 2c 20 20 20 20 20 20 20 ientData,
2f7f0 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 /* Client data
2f800 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f for xCreate/xCo
2f810 6e 6e 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 nnect */. void(
2f820 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a *xDestroy)(void*
2f830 29 20 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 ) /* Module
2f840 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 destructor funct
2f850 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a ion */.);../*.**
2f860 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 CAPI3REF: Virtu
2f870 61 6c 20 54 61 62 6c 65 20 49 6e 73 74 61 6e 63 al Table Instanc
2f880 65 20 4f 62 6a 65 63 74 20 7b 48 31 38 30 31 30 e Object {H18010
2f890 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 } <S20400>.** KE
2f8a0 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f YWORDS: sqlite3_
2f8b0 76 74 61 62 0a 2a 2a 20 45 58 50 45 52 49 4d 45 vtab.** EXPERIME
2f8c0 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 NTAL.**.** Every
2f8d0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 [virtual table
2f8e0 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e module] implemen
2f8f0 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 tation uses a su
2f900 62 63 6c 61 73 73 0a 2a 2a 20 6f 66 20 74 68 65 bclass.** of the
2f910 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 following struc
2f920 74 75 72 65 20 74 6f 20 64 65 73 63 72 69 62 65 ture to describe
2f930 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 69 6e a particular in
2f940 73 74 61 6e 63 65 0a 2a 2a 20 6f 66 20 74 68 65 stance.** of the
2f950 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d [virtual table]
2f960 2e 20 20 45 61 63 68 20 73 75 62 63 6c 61 73 73 . Each subclass
2f970 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69 6c will.** be tail
2f980 6f 72 65 64 20 74 6f 20 74 68 65 20 73 70 65 63 ored to the spec
2f990 69 66 69 63 20 6e 65 65 64 73 20 6f 66 20 74 68 ific needs of th
2f9a0 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 e module impleme
2f9b0 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 ntation..** The
2f9c0 70 75 72 70 6f 73 65 20 6f 66 20 74 68 69 73 20 purpose of this
2f9d0 73 75 70 65 72 63 6c 61 73 73 20 69 73 20 74 6f superclass is to
2f9e0 20 64 65 66 69 6e 65 20 63 65 72 74 61 69 6e 20 define certain
2f9f0 66 69 65 6c 64 73 20 74 68 61 74 20 61 72 65 0a fields that are.
2fa00 2a 2a 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c ** common to all
2fa10 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e module implemen
2fa20 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 56 tations..**.** V
2fa30 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6d 65 irtual tables me
2fa40 74 68 6f 64 73 20 63 61 6e 20 73 65 74 20 61 6e thods can set an
2fa50 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 62 error message b
2fa60 79 20 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a y assigning a.**
2fa70 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 string obtained
2fa80 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
2fa90 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 7a 45 72 printf()] to zEr
2faa0 72 4d 73 67 2e 20 20 54 68 65 20 6d 65 74 68 6f rMsg. The metho
2fab0 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 d should.** take
2fac0 20 63 61 72 65 20 74 68 61 74 20 61 6e 79 20 70 care that any p
2fad0 72 69 6f 72 20 73 74 72 69 6e 67 20 69 73 20 66 rior string is f
2fae0 72 65 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 reed by a call t
2faf0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 o [sqlite3_free(
2fb00 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 )].** prior to a
2fb10 73 73 69 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 ssigning a new s
2fb20 74 72 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 tring to zErrMsg
2fb30 2e 20 20 41 66 74 65 72 20 74 68 65 20 65 72 72 . After the err
2fb40 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 or message.** is
2fb50 20 64 65 6c 69 76 65 72 65 64 20 75 70 20 74 6f delivered up to
2fb60 20 74 68 65 20 63 6c 69 65 6e 74 20 61 70 70 6c the client appl
2fb70 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 ication, the str
2fb80 69 6e 67 20 77 69 6c 6c 20 62 65 20 61 75 74 6f ing will be auto
2fb90 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 matically.** fre
2fba0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 66 72 ed by sqlite3_fr
2fbb0 65 65 28 29 20 61 6e 64 20 74 68 65 20 7a 45 72 ee() and the zEr
2fbc0 72 4d 73 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 rMsg field will
2fbd0 62 65 20 7a 65 72 6f 65 64 2e 0a 2a 2f 0a 73 74 be zeroed..*/.st
2fbe0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 ruct sqlite3_vta
2fbf0 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 b {. const sqli
2fc00 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64 te3_module *pMod
2fc10 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f 64 ule; /* The mod
2fc20 75 6c 65 20 66 6f 72 20 74 68 69 73 20 76 69 72 ule for this vir
2fc30 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 20 tual table */.
2fc40 69 6e 74 20 6e 52 65 66 3b 20 20 20 20 20 20 20 int nRef;
2fc50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2fc60 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c /* Used internal
2fc70 6c 79 20 2a 2f 0a 20 20 63 68 61 72 20 2a 7a 45 ly */. char *zE
2fc80 72 72 4d 73 67 3b 20 20 20 20 20 20 20 20 20 20 rrMsg;
2fc90 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 /* Error
2fca0 20 6d 65 73 73 61 67 65 20 66 72 6f 6d 20 73 71 message from sq
2fcb0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 lite3_mprintf()
2fcc0 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 */. /* Virtual
2fcd0 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 table implementa
2fce0 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 tions will typic
2fcf0 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f ally add additio
2fd00 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b nal fields */.};
2fd10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2fd20 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 : Virtual Table
2fd30 43 75 72 73 6f 72 20 4f 62 6a 65 63 74 20 20 7b Cursor Object {
2fd40 48 31 38 30 32 30 7d 20 3c 53 32 30 34 30 30 3e H18020} <S20400>
2fd50 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 .** KEYWORDS: sq
2fd60 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f lite3_vtab_curso
2fd70 72 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 r {virtual table
2fd80 20 63 75 72 73 6f 72 7d 0a 2a 2a 20 45 58 50 45 cursor}.** EXPE
2fd90 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 45 RIMENTAL.**.** E
2fda0 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20 74 61 very [virtual ta
2fdb0 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c ble module] impl
2fdc0 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 ementation uses
2fdd0 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 a subclass of th
2fde0 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 e.** following s
2fdf0 74 72 75 63 74 75 72 65 20 74 6f 20 64 65 73 63 tructure to desc
2fe00 72 69 62 65 20 63 75 72 73 6f 72 73 20 74 68 61 ribe cursors tha
2fe10 74 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65 t point into the
2fe20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 .** [virtual tab
2fe30 6c 65 5d 20 61 6e 64 20 61 72 65 20 75 73 65 64 le] and are used
2fe40 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74 68 72 6f .** to loop thro
2fe50 75 67 68 20 74 68 65 20 76 69 72 74 75 61 6c 20 ugh the virtual
2fe60 74 61 62 6c 65 2e 20 20 43 75 72 73 6f 72 73 20 table. Cursors
2fe70 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e are created usin
2fe80 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 g the.** [sqlite
2fe90 33 5f 6d 6f 64 75 6c 65 2e 78 4f 70 65 6e 20 7c 3_module.xOpen |
2fea0 20 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 6f xOpen] method o
2feb0 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 61 6e 64 f the module and
2fec0 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 0a 2a are destroyed.*
2fed0 2a 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 * by the [sqlite
2fee0 33 5f 6d 6f 64 75 6c 65 2e 78 43 6c 6f 73 65 20 3_module.xClose
2fef0 7c 20 78 43 6c 6f 73 65 5d 20 6d 65 74 68 6f 64 | xClose] method
2ff00 2e 20 20 43 75 73 73 6f 72 73 20 61 72 65 20 75 . Cussors are u
2ff10 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 78 sed.** by the [x
2ff20 46 69 6c 74 65 72 5d 2c 20 5b 78 4e 65 78 74 5d Filter], [xNext]
2ff30 2c 20 5b 78 45 6f 66 5d 2c 20 5b 78 43 6f 6c 75 , [xEof], [xColu
2ff40 6d 6e 5d 2c 20 61 6e 64 20 5b 78 52 6f 77 69 64 mn], and [xRowid
2ff50 5d 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 ] methods.** of
2ff60 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 the module. Eac
2ff70 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 h module impleme
2ff80 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 64 65 66 ntation will def
2ff90 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 ine.** the conte
2ffa0 6e 74 20 6f 66 20 61 20 63 75 72 73 6f 72 20 73 nt of a cursor s
2ffb0 74 72 75 63 74 75 72 65 20 74 6f 20 73 75 69 74 tructure to suit
2ffc0 20 69 74 73 20 6f 77 6e 20 6e 65 65 64 73 2e 0a its own needs..
2ffd0 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75 70 65 72 **.** This super
2ffe0 63 6c 61 73 73 20 65 78 69 73 74 73 20 69 6e 20 class exists in
2fff0 6f 72 64 65 72 20 74 6f 20 64 65 66 69 6e 65 20 order to define
30000 66 69 65 6c 64 73 20 6f 66 20 74 68 65 20 63 75 fields of the cu
30010 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20 61 72 65 rsor that.** are
30020 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 common to all i
30030 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a mplementations..
30040 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 */.struct sqlite
30050 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a 3_vtab_cursor {.
30060 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a sqlite3_vtab *
30070 70 56 74 61 62 3b 20 20 20 20 20 20 2f 2a 20 56 pVtab; /* V
30080 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6f 66 20 irtual table of
30090 74 68 69 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20 this cursor */.
300a0 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c /* Virtual tabl
300b0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
300c0 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 s will typically
300d0 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 add additional
300e0 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a fields */.};../*
300f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
30100 63 6c 61 72 65 20 54 68 65 20 53 63 68 65 6d 61 clare The Schema
30110 20 4f 66 20 41 20 56 69 72 74 75 61 6c 20 54 61 Of A Virtual Ta
30120 62 6c 65 20 7b 48 31 38 32 38 30 7d 20 3c 53 32 ble {H18280} <S2
30130 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 0400>.** EXPERIM
30140 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ENTAL.**.** The
30150 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 20 5b 78 [xCreate] and [x
30160 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73 Connect] methods
30170 20 6f 66 20 61 0a 2a 2a 20 5b 76 69 72 74 75 61 of a.** [virtua
30180 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 l table module]
30190 63 61 6c 6c 20 74 68 69 73 20 69 6e 74 65 72 66 call this interf
301a0 61 63 65 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72 ace.** to declar
301b0 65 20 74 68 65 20 66 6f 72 6d 61 74 20 28 74 68 e the format (th
301c0 65 20 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 61 e names and data
301d0 74 79 70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c types of the col
301e0 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20 umns) of.** the
301f0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 74 virtual tables t
30200 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a hey implement..*
30210 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d /.SQLITE_EXPERIM
30220 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 ENTAL int sqlite
30230 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 73 3_declare_vtab(s
30240 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 qlite3*, const c
30250 68 61 72 20 2a 7a 53 51 4c 29 3b 0a 0a 2f 2a 0a har *zSQL);../*.
30260 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 76 65 ** CAPI3REF: Ove
30270 72 6c 6f 61 64 20 41 20 46 75 6e 63 74 69 6f 6e rload A Function
30280 20 46 6f 72 20 41 20 56 69 72 74 75 61 6c 20 54 For A Virtual T
30290 61 62 6c 65 20 7b 48 31 38 33 30 30 7d 20 3c 53 able {H18300} <S
302a0 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 20400>.** EXPERI
302b0 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 56 69 72 MENTAL.**.** Vir
302c0 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 20 tual tables can
302d0 70 72 6f 76 69 64 65 20 61 6c 74 65 72 6e 61 74 provide alternat
302e0 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ive implementati
302f0 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 ons of functions
30300 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 78 .** using the [x
30310 46 69 6e 64 46 75 6e 63 74 69 6f 6e 5d 20 6d 65 FindFunction] me
30320 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 76 69 72 thod of the [vir
30330 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c tual table modul
30340 65 5d 2e 20 20 0a 2a 2a 20 42 75 74 20 67 6c 6f e]. .** But glo
30350 62 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 bal versions of
30360 74 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a those functions.
30370 2a 2a 20 6d 75 73 74 20 65 78 69 73 74 20 69 6e ** must exist in
30380 20 6f 72 64 65 72 20 74 6f 20 62 65 20 6f 76 65 order to be ove
30390 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 rloaded..**.** T
303a0 68 69 73 20 41 50 49 20 6d 61 6b 65 73 20 73 75 his API makes su
303b0 72 65 20 61 20 67 6c 6f 62 61 6c 20 76 65 72 73 re a global vers
303c0 69 6f 6e 20 6f 66 20 61 20 66 75 6e 63 74 69 6f ion of a functio
303d0 6e 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 n with a particu
303e0 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 lar.** name and
303f0 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65 number of parame
30400 74 65 72 73 20 65 78 69 73 74 73 2e 20 20 49 66 ters exists. If
30410 20 6e 6f 20 73 75 63 68 20 66 75 6e 63 74 69 6f no such functio
30420 6e 20 65 78 69 73 74 73 0a 2a 2a 20 62 65 66 6f n exists.** befo
30430 72 65 20 74 68 69 73 20 41 50 49 20 69 73 20 63 re this API is c
30440 61 6c 6c 65 64 2c 20 61 20 6e 65 77 20 66 75 6e alled, a new fun
30450 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64 ction is created
30460 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 . The implement
30470 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 ation.** of the
30480 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c 77 new function alw
30490 61 79 73 20 63 61 75 73 65 73 20 61 6e 20 65 78 ays causes an ex
304a0 63 65 70 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 ception to be th
304b0 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 rown. So.** the
304c0 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 new function is
304d0 20 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61 6e not good for an
304e0 79 74 68 69 6e 67 20 62 79 20 69 74 73 65 6c 66 ything by itself
304f0 2e 20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 . Its only.** p
30500 75 72 70 6f 73 65 20 69 73 20 74 6f 20 62 65 20 urpose is to be
30510 61 20 70 6c 61 63 65 68 6f 6c 64 65 72 20 66 75 a placeholder fu
30520 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 61 6e 20 nction that can
30530 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a be overloaded.**
30540 20 62 79 20 61 20 5b 76 69 72 74 75 61 6c 20 74 by a [virtual t
30550 61 62 6c 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 able]..*/.SQLITE
30560 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e _EXPERIMENTAL in
30570 74 20 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f t sqlite3_overlo
30580 61 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69 ad_function(sqli
30590 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 te3*, const char
305a0 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 *zFuncName, int
305b0 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 nArg);../*.** T
305c0 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 he interface to
305d0 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c the virtual-tabl
305e0 65 20 6d 65 63 68 61 6e 69 73 6d 20 64 65 66 69 e mechanism defi
305f0 6e 65 64 20 61 62 6f 76 65 20 28 62 61 63 6b 20 ned above (back
30600 75 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 up.** to a comme
30610 6e 74 20 72 65 6d 61 72 6b 61 62 6c 79 20 73 69 nt remarkably si
30620 6d 69 6c 61 72 20 74 6f 20 74 68 69 73 20 6f 6e milar to this on
30630 65 29 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 e) is currently
30640 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f considered.** to
30650 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c be experimental
30660 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 . The interface
30670 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e might change in
30680 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 incompatible wa
30690 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 ys..** If this i
306a0 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 s a problem for
306b0 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 you, do not use
306c0 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 the interface at
306d0 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a this time..**.*
306e0 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 * When the virtu
306f0 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 al-table mechani
30700 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 sm stabilizes, w
30710 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 e will declare t
30720 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 he.** interface
30730 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 fixed, support i
30740 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 t indefinitely,
30750 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 and remove this
30760 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a comment..**.****
30770 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 ** EXPERIMENTAL
30780 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 - subject to cha
30790 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 nge without noti
307a0 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ce *************
307b0 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 *.*/../*.** CAPI
307c0 33 52 45 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 3REF: A Handle T
307d0 6f 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 20 7b o An Open BLOB {
307e0 48 31 37 38 30 30 7d 20 3c 53 33 30 32 33 30 3e H17800} <S30230>
307f0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 42 .** KEYWORDS: {B
30800 4c 4f 42 20 68 61 6e 64 6c 65 7d 20 7b 42 4c 4f LOB handle} {BLO
30810 42 20 68 61 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a B handles}.**.**
30820 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 An instance of
30830 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 this object repr
30840 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 42 esents an open B
30850 4c 4f 42 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 LOB on which.**
30860 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 [sqlite3_blob_op
30870 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c en | incremental
30880 20 42 4c 4f 42 20 49 2f 4f 5d 20 63 61 6e 20 62 BLOB I/O] can b
30890 65 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 20 e performed..**
308a0 4f 62 6a 65 63 74 73 20 6f 66 20 74 68 69 73 20 Objects of this
308b0 74 79 70 65 20 61 72 65 20 63 72 65 61 74 65 64 type are created
308c0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f by [sqlite3_blo
308d0 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 b_open()].** and
308e0 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 destroyed by [s
308f0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 qlite3_blob_clos
30900 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 e()]..** The [sq
30910 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 lite3_blob_read(
30920 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
30930 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 69 6e blob_write()] in
30940 74 65 72 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20 terfaces.** can
30950 62 65 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 be used to read
30960 6f 72 20 77 72 69 74 65 20 73 6d 61 6c 6c 20 73 or write small s
30970 75 62 73 65 63 74 69 6f 6e 73 20 6f 66 20 74 68 ubsections of th
30980 65 20 42 4c 4f 42 2e 0a 2a 2a 20 54 68 65 20 5b e BLOB..** The [
30990 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 sqlite3_blob_byt
309a0 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 es()] interface
309b0 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 returns the size
309c0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 69 6e 20 of the BLOB in
309d0 62 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 bytes..*/.typede
309e0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
309f0 5f 62 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c _blob sqlite3_bl
30a00 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 ob;../*.** CAPI3
30a10 52 45 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 REF: Open A BLOB
30a20 20 46 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c For Incremental
30a30 20 49 2f 4f 20 7b 48 31 37 38 31 30 7d 20 3c 53 I/O {H17810} <S
30a40 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 30230>.**.** Thi
30a50 73 20 69 6e 74 65 72 66 61 63 65 73 20 6f 70 65 s interfaces ope
30a60 6e 73 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c ns a [BLOB handl
30a70 65 20 7c 20 68 61 6e 64 6c 65 5d 20 74 6f 20 74 e | handle] to t
30a80 68 65 20 42 4c 4f 42 20 6c 6f 63 61 74 65 64 0a he BLOB located.
30a90 2a 2a 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c 20 ** in row iRow,
30aa0 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 column zColumn,
30ab0 74 61 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 table zTable in
30ac0 64 61 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a database zDb;.**
30ad0 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c in other words,
30ae0 20 74 68 65 20 73 61 6d 65 20 42 4c 4f 42 20 74 the same BLOB t
30af0 68 61 74 20 77 6f 75 6c 64 20 62 65 20 73 65 6c hat would be sel
30b00 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 ected by:.**.**
30b10 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c <pre>.** SEL
30b20 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d ECT zColumn FROM
30b30 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 zDb.zTable WHER
30b40 45 20 5b 72 6f 77 69 64 5d 20 3d 20 69 52 6f 77 E [rowid] = iRow
30b50 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 20 7b 45 4e 44 ;.** </pre> {END
30b60 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 }.**.** If the f
30b70 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 69 lags parameter i
30b80 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 s non-zero, the
30b90 74 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e the BLOB is open
30ba0 65 64 20 66 6f 72 20 72 65 61 64 0a 2a 2a 20 61 ed for read.** a
30bb0 6e 64 20 77 72 69 74 65 20 61 63 63 65 73 73 2e nd write access.
30bc0 20 49 66 20 69 74 20 69 73 20 7a 65 72 6f 2c 20 If it is zero,
30bd0 74 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e the BLOB is open
30be0 65 64 20 66 6f 72 20 72 65 61 64 20 61 63 63 65 ed for read acce
30bf0 73 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 ss..**.** Note t
30c00 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 hat the database
30c10 20 6e 61 6d 65 20 69 73 20 6e 6f 74 20 74 68 65 name is not the
30c20 20 66 69 6c 65 6e 61 6d 65 20 74 68 61 74 20 63 filename that c
30c30 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 64 ontains.** the d
30c40 61 74 61 62 61 73 65 20 62 75 74 20 72 61 74 68 atabase but rath
30c50 65 72 20 74 68 65 20 73 79 6d 62 6f 6c 69 63 20 er the symbolic
30c60 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 name of the data
30c70 62 61 73 65 20 74 68 61 74 0a 2a 2a 20 69 73 20 base that.** is
30c80 61 73 73 69 67 6e 65 64 20 77 68 65 6e 20 74 68 assigned when th
30c90 65 20 64 61 74 61 62 61 73 65 20 69 73 20 63 6f e database is co
30ca0 6e 6e 65 63 74 65 64 20 75 73 69 6e 67 20 5b 41 nnected using [A
30cb0 54 54 41 43 48 5d 2e 0a 2a 2a 20 46 6f 72 20 74 TTACH]..** For t
30cc0 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 he main database
30cd0 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 62 file, the datab
30ce0 61 73 65 20 6e 61 6d 65 20 69 73 20 22 6d 61 69 ase name is "mai
30cf0 6e 22 2e 0a 2a 2a 20 46 6f 72 20 54 45 4d 50 20 n"..** For TEMP
30d00 74 61 62 6c 65 73 2c 20 74 68 65 20 64 61 74 61 tables, the data
30d10 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22 74 65 base name is "te
30d20 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 mp"..**.** On su
30d30 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f ccess, [SQLITE_O
30d40 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 K] is returned a
30d50 6e 64 20 74 68 65 20 6e 65 77 20 5b 42 4c 4f 42 nd the new [BLOB
30d60 20 68 61 6e 64 6c 65 5d 20 69 73 20 77 72 69 74 handle] is writ
30d70 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c 6f ten.** to *ppBlo
30d80 62 2e 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 b. Otherwise an
30d90 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 [error code] is
30da0 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 79 returned and any
30db0 20 76 61 6c 75 65 20 77 72 69 74 74 65 6e 0a 2a value written.*
30dc0 2a 20 74 6f 20 2a 70 70 42 6c 6f 62 20 73 68 6f * to *ppBlob sho
30dd0 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 uld not be used
30de0 62 79 20 74 68 65 20 63 61 6c 6c 65 72 2e 0a 2a by the caller..*
30df0 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 * This function
30e00 73 65 74 73 20 74 68 65 20 5b 64 61 74 61 62 61 sets the [databa
30e10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65 se connection] e
30e20 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 rror code and me
30e30 73 73 61 67 65 0a 2a 2a 20 61 63 63 65 73 73 69 ssage.** accessi
30e40 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33 ble via [sqlite3
30e50 5f 65 72 72 63 6f 64 65 28 29 5d 20 61 6e 64 20 _errcode()] and
30e60 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 [sqlite3_errmsg(
30e70 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 )]..**.** If the
30e80 20 72 6f 77 20 74 68 61 74 20 61 20 42 4c 4f 42 row that a BLOB
30e90 20 68 61 6e 64 6c 65 20 70 6f 69 6e 74 73 20 74 handle points t
30ea0 6f 20 69 73 20 6d 6f 64 69 66 69 65 64 20 62 79 o is modified by
30eb0 20 61 6e 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 2c an.** [UPDATE],
30ec0 20 5b 44 45 4c 45 54 45 5d 2c 20 6f 72 20 62 79 [DELETE], or by
30ed0 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 73 [ON CONFLICT] s
30ee0 69 64 65 2d 65 66 66 65 63 74 73 0a 2a 2a 20 74 ide-effects.** t
30ef0 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 68 61 6e hen the BLOB han
30f00 64 6c 65 20 69 73 20 6d 61 72 6b 65 64 20 61 73 dle is marked as
30f10 20 22 65 78 70 69 72 65 64 22 2e 0a 2a 2a 20 54 "expired"..** T
30f20 68 69 73 20 69 73 20 74 72 75 65 20 69 66 20 61 his is true if a
30f30 6e 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 ny column of the
30f40 20 72 6f 77 20 69 73 20 63 68 61 6e 67 65 64 2c row is changed,
30f50 20 65 76 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a even a column.*
30f60 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 74 68 65 * other than the
30f70 20 6f 6e 65 20 74 68 65 20 42 4c 4f 42 20 68 61 one the BLOB ha
30f80 6e 64 6c 65 20 69 73 20 6f 70 65 6e 20 6f 6e 2e ndle is open on.
30f90 0a 2a 2a 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 .** Calls to [sq
30fa0 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 lite3_blob_read(
30fb0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
30fc0 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 66 6f blob_write()] fo
30fd0 72 0a 2a 2a 20 61 20 65 78 70 69 72 65 64 20 42 r.** a expired B
30fe0 4c 4f 42 20 68 61 6e 64 6c 65 20 66 61 69 6c 20 LOB handle fail
30ff0 77 69 74 68 20 61 6e 20 72 65 74 75 72 6e 20 63 with an return c
31000 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 ode of [SQLITE_A
31010 42 4f 52 54 5d 2e 0a 2a 2a 20 43 68 61 6e 67 65 BORT]..** Change
31020 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 61 s written into a
31030 20 42 4c 4f 42 20 70 72 69 6f 72 20 74 6f 20 74 BLOB prior to t
31040 68 65 20 42 4c 4f 42 20 65 78 70 69 72 69 6e 67 he BLOB expiring
31050 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c are not.** roll
31060 62 61 63 6b 20 62 79 20 74 68 65 20 65 78 70 69 back by the expi
31070 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 42 4c ration of the BL
31080 4f 42 2e 20 20 53 75 63 68 20 63 68 61 6e 67 65 OB. Such change
31090 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c s will eventuall
310a0 79 0a 2a 2a 20 63 6f 6d 6d 69 74 20 69 66 20 74 y.** commit if t
310b0 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 he transaction c
310c0 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 ontinues to comp
310d0 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 letion..**.** Re
310e0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
310f0 48 31 37 38 31 33 5d 20 5b 48 31 37 38 31 34 5d H17813] [H17814]
31100 20 5b 48 31 37 38 31 36 5d 20 5b 48 31 37 38 31 [H17816] [H1781
31110 39 5d 20 5b 48 31 37 38 32 31 5d 20 5b 48 31 37 9] [H17821] [H17
31120 38 32 34 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 824].*/.int sqli
31130 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 te3_blob_open(.
31140 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e sqlite3*,. con
31150 73 74 20 63 68 61 72 20 2a 7a 44 62 2c 0a 20 20 st char *zDb,.
31160 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 const char *zTab
31170 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 le,. const char
31180 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c *zColumn,. sql
31190 69 74 65 33 5f 69 6e 74 36 34 20 69 52 6f 77 2c ite3_int64 iRow,
311a0 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 0a 20 20 . int flags,.
311b0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 sqlite3_blob **p
311c0 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 pBlob.);../*.**
311d0 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 65 20 CAPI3REF: Close
311e0 41 20 42 4c 4f 42 20 48 61 6e 64 6c 65 20 7b 48 A BLOB Handle {H
311f0 31 37 38 33 30 7d 20 3c 53 33 30 32 33 30 3e 0a 17830} <S30230>.
31200 2a 2a 0a 2a 2a 20 43 6c 6f 73 65 73 20 61 6e 20 **.** Closes an
31210 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c open [BLOB handl
31220 65 5d 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 69 6e e]..**.** Closin
31230 67 20 61 20 42 4c 4f 42 20 73 68 61 6c 6c 20 63 g a BLOB shall c
31240 61 75 73 65 20 74 68 65 20 63 75 72 72 65 6e 74 ause the current
31250 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 transaction to
31260 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66 20 74 68 65 commit.** if the
31270 72 65 20 61 72 65 20 6e 6f 20 6f 74 68 65 72 20 re are no other
31280 42 4c 4f 42 73 2c 20 6e 6f 20 70 65 6e 64 69 6e BLOBs, no pendin
31290 67 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 g prepared state
312a0 6d 65 6e 74 73 2c 20 61 6e 64 20 74 68 65 0a 2a ments, and the.*
312b0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
312c0 63 74 69 6f 6e 20 69 73 20 69 6e 20 5b 61 75 74 ction is in [aut
312d0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 5d 2e 0a 2a ocommit mode]..*
312e0 2a 20 49 66 20 61 6e 79 20 77 72 69 74 65 73 20 * If any writes
312f0 77 65 72 65 20 6d 61 64 65 20 74 6f 20 74 68 65 were made to the
31300 20 42 4c 4f 42 2c 20 74 68 65 79 20 6d 69 67 68 BLOB, they migh
31310 74 20 62 65 20 68 65 6c 64 20 69 6e 20 63 61 63 t be held in cac
31320 68 65 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20 he.** until the
31330 63 6c 6f 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 close operation
31340 69 66 20 74 68 65 79 20 77 69 6c 6c 20 66 69 74 if they will fit
31350 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 43 6c . {END}.**.** Cl
31360 6f 73 69 6e 67 20 74 68 65 20 42 4c 4f 42 20 6f osing the BLOB o
31370 66 74 65 6e 20 66 6f 72 63 65 73 20 74 68 65 20 ften forces the
31380 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 75 74 20 74 changes.** out t
31390 6f 20 64 69 73 6b 20 61 6e 64 20 73 6f 20 69 66 o disk and so if
313a0 20 61 6e 79 20 49 2f 4f 20 65 72 72 6f 72 73 20 any I/O errors
313b0 6f 63 63 75 72 2c 20 74 68 65 79 20 77 69 6c 6c occur, they will
313c0 20 6c 69 6b 65 6c 79 20 6f 63 63 75 72 0a 2a 2a likely occur.**
313d0 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 at the time whe
313e0 6e 20 74 68 65 20 42 4c 4f 42 20 69 73 20 63 6c n the BLOB is cl
313f0 6f 73 65 64 2e 20 20 7b 48 31 37 38 33 33 7d 20 osed. {H17833}
31400 41 6e 79 20 65 72 72 6f 72 73 20 74 68 61 74 20 Any errors that
31410 6f 63 63 75 72 20 64 75 72 69 6e 67 0a 2a 2a 20 occur during.**
31420 63 6c 6f 73 69 6e 67 20 61 72 65 20 72 65 70 6f closing are repo
31430 72 74 65 64 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 rted as a non-ze
31440 72 6f 20 72 65 74 75 72 6e 20 76 61 6c 75 65 2e ro return value.
31450 0a 2a 2a 0a 2a 2a 20 54 68 65 20 42 4c 4f 42 20 .**.** The BLOB
31460 69 73 20 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 is closed uncond
31470 69 74 69 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e itionally. Even
31480 20 69 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 if this routine
31490 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 returns.** an e
314a0 72 72 6f 72 20 63 6f 64 65 2c 20 74 68 65 20 42 rror code, the B
314b0 4c 4f 42 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f LOB is still clo
314c0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 sed..**.** Requi
314d0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 rements:.** [H17
314e0 38 33 33 5d 20 5b 48 31 37 38 33 36 5d 20 5b 48 833] [H17836] [H
314f0 31 37 38 33 39 5d 0a 2a 2f 0a 69 6e 74 20 73 71 17839].*/.int sq
31500 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 lite3_blob_close
31510 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 (sqlite3_blob *)
31520 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
31530 46 3a 20 52 65 74 75 72 6e 20 54 68 65 20 53 69 F: Return The Si
31540 7a 65 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c ze Of An Open BL
31550 4f 42 20 7b 48 31 37 38 34 30 7d 20 3c 53 33 30 OB {H17840} <S30
31560 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 230>.**.** Retur
31570 6e 73 20 74 68 65 20 73 69 7a 65 20 69 6e 20 62 ns the size in b
31580 79 74 65 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 ytes of the BLOB
31590 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 accessible via
315a0 74 68 65 20 6f 70 65 6e 0a 2a 2a 20 5b 5d 42 4c the open.** []BL
315b0 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 20 69 74 OB handle] in it
315c0 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e s only argument.
315d0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
315e0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 34 33 5d nts:.** [H17843]
315f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
31600 62 6c 6f 62 5f 62 79 74 65 73 28 73 71 6c 69 74 blob_bytes(sqlit
31610 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a e3_blob *);../*.
31620 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 61 ** CAPI3REF: Rea
31630 64 20 44 61 74 61 20 46 72 6f 6d 20 41 20 42 4c d Data From A BL
31640 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 OB Incrementally
31650 20 7b 48 31 37 38 35 30 7d 20 3c 53 33 30 32 33 {H17850} <S3023
31660 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 0>.**.** This fu
31670 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 nction is used t
31680 6f 20 72 65 61 64 20 64 61 74 61 20 66 72 6f 6d o read data from
31690 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 an open [BLOB h
316a0 61 6e 64 6c 65 5d 20 69 6e 74 6f 20 61 0a 2a 2a andle] into a.**
316b0 20 63 61 6c 6c 65 72 2d 73 75 70 70 6c 69 65 64 caller-supplied
316c0 20 62 75 66 66 65 72 2e 20 4e 20 62 79 74 65 73 buffer. N bytes
316d0 20 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f 70 of data are cop
316e0 69 65 64 20 69 6e 74 6f 20 62 75 66 66 65 72 20 ied into buffer
316f0 5a 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 6f 70 Z.** from the op
31700 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e en BLOB, startin
31710 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66 g at offset iOff
31720 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 6f 66 set..**.** If of
31730 66 73 65 74 20 69 4f 66 66 73 65 74 20 69 73 20 fset iOffset is
31740 6c 65 73 73 20 74 68 61 6e 20 4e 20 62 79 74 65 less than N byte
31750 73 20 66 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f s from the end o
31760 66 20 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b f the BLOB,.** [
31770 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 SQLITE_ERROR] is
31780 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f returned and no
31790 20 64 61 74 61 20 69 73 20 72 65 61 64 2e 20 20 data is read.
317a0 49 66 20 4e 20 6f 72 20 69 4f 66 66 73 65 74 20 If N or iOffset
317b0 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 is.** less than
317c0 7a 65 72 6f 2c 20 5b 53 51 4c 49 54 45 5f 45 52 zero, [SQLITE_ER
317d0 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 ROR] is returned
317e0 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 and no data is
317f0 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 read..**.** An a
31800 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 66 ttempt to read f
31810 72 6f 6d 20 61 6e 20 65 78 70 69 72 65 64 20 5b rom an expired [
31820 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 BLOB handle] fai
31830 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 ls with an.** er
31840 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c ror code of [SQL
31850 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a ITE_ABORT]..**.*
31860 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 53 51 * On success, SQ
31870 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 LITE_OK is retur
31880 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 ned..** Otherwis
31890 65 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 e, an [error cod
318a0 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 e] or an [extend
318b0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 ed error code] i
318c0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
318d0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
318e0 2a 2a 20 5b 48 31 37 38 35 33 5d 20 5b 48 31 37 ** [H17853] [H17
318f0 38 35 36 5d 20 5b 48 31 37 38 35 39 5d 20 5b 48 856] [H17859] [H
31900 31 37 38 36 32 5d 20 5b 48 31 37 38 36 33 5d 20 17862] [H17863]
31910 5b 48 31 37 38 36 35 5d 20 5b 48 31 37 38 36 38 [H17865] [H17868
31920 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ].*/.int sqlite3
31930 5f 62 6c 6f 62 5f 72 65 61 64 28 73 71 6c 69 74 _blob_read(sqlit
31940 65 33 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 e3_blob *, void
31950 2a 5a 2c 20 69 6e 74 20 4e 2c 20 69 6e 74 20 69 *Z, int N, int i
31960 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 Offset);../*.**
31970 43 41 50 49 33 52 45 46 3a 20 57 72 69 74 65 20 CAPI3REF: Write
31980 44 61 74 61 20 49 6e 74 6f 20 41 20 42 4c 4f 42 Data Into A BLOB
31990 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b Incrementally {
319a0 48 31 37 38 37 30 7d 20 3c 53 33 30 32 33 30 3e H17870} <S30230>
319b0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 .**.** This func
319c0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 tion is used to
319d0 77 72 69 74 65 20 64 61 74 61 20 69 6e 74 6f 20 write data into
319e0 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 an open [BLOB ha
319f0 6e 64 6c 65 5d 20 66 72 6f 6d 20 61 0a 2a 2a 20 ndle] from a.**
31a00 63 61 6c 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 caller-supplied
31a10 62 75 66 66 65 72 2e 20 4e 20 62 79 74 65 73 20 buffer. N bytes
31a20 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 of data are copi
31a30 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 66 66 ed from the buff
31a40 65 72 20 5a 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 er Z.** into the
31a50 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72 open BLOB, star
31a60 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69 ting at offset i
31a70 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 Offset..**.** If
31a80 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c the [BLOB handl
31a90 65 5d 20 70 61 73 73 65 64 20 61 73 20 74 68 65 e] passed as the
31aa0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
31ab0 77 61 73 20 6e 6f 74 20 6f 70 65 6e 65 64 20 66 was not opened f
31ac0 6f 72 0a 2a 2a 20 77 72 69 74 69 6e 67 20 28 74 or.** writing (t
31ad0 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 he flags paramet
31ae0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 er to [sqlite3_b
31af0 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 77 61 73 20 lob_open()] was
31b00 7a 65 72 6f 29 2c 0a 2a 2a 20 74 68 69 73 20 66 zero),.** this f
31b10 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
31b20 5b 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 [SQLITE_READONLY
31b30 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 ]..**.** This fu
31b40 6e 63 74 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 nction may only
31b50 6d 6f 64 69 66 79 20 74 68 65 20 63 6f 6e 74 65 modify the conte
31b60 6e 74 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 3b nts of the BLOB;
31b70 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f it is.** not po
31b80 73 73 69 62 6c 65 20 74 6f 20 69 6e 63 72 65 61 ssible to increa
31b90 73 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 se the size of a
31ba0 20 42 4c 4f 42 20 75 73 69 6e 67 20 74 68 69 73 BLOB using this
31bb0 20 41 50 49 2e 0a 2a 2a 20 49 66 20 6f 66 66 73 API..** If offs
31bc0 65 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 et iOffset is le
31bd0 73 73 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20 ss than N bytes
31be0 66 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 from the end of
31bf0 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 the BLOB,.** [SQ
31c00 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 LITE_ERROR] is r
31c10 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 eturned and no d
31c20 61 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e 20 ata is written.
31c30 20 49 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 If N is.** less
31c40 20 74 68 61 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 than zero [SQLI
31c50 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 TE_ERROR] is ret
31c60 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 urned and no dat
31c70 61 20 69 73 20 77 72 69 74 74 65 6e 2e 0a 2a 2a a is written..**
31c80 0a 2a 2a 20 41 6e 20 61 74 74 65 6d 70 74 20 74 .** An attempt t
31c90 6f 20 77 72 69 74 65 20 74 6f 20 61 6e 20 65 78 o write to an ex
31ca0 70 69 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 pired [BLOB hand
31cb0 6c 65 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 le] fails with a
31cc0 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 n.** error code
31cd0 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 of [SQLITE_ABORT
31ce0 5d 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 ]. Writes to th
31cf0 65 20 42 4c 4f 42 20 74 68 61 74 20 6f 63 63 75 e BLOB that occu
31d00 72 72 65 64 0a 2a 2a 20 62 65 66 6f 72 65 20 74 rred.** before t
31d10 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d he [BLOB handle]
31d20 20 65 78 70 69 72 65 64 20 61 72 65 20 6e 6f 74 expired are not
31d30 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79 20 rolled back by
31d40 74 68 65 0a 2a 2a 20 65 78 70 69 72 61 74 69 6f the.** expiratio
31d50 6e 20 6f 66 20 74 68 65 20 68 61 6e 64 6c 65 2c n of the handle,
31d60 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 though of cours
31d70 65 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20 e those changes
31d80 6d 69 67 68 74 0a 2a 2a 20 68 61 76 65 20 62 65 might.** have be
31d90 65 6e 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 en overwritten b
31da0 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 y the statement
31db0 74 68 61 74 20 65 78 70 69 72 65 64 20 74 68 65 that expired the
31dc0 20 42 4c 4f 42 20 68 61 6e 64 6c 65 0a 2a 2a 20 BLOB handle.**
31dd0 6f 72 20 62 79 20 6f 74 68 65 72 20 69 6e 64 65 or by other inde
31de0 70 65 6e 64 65 6e 74 20 73 74 61 74 65 6d 65 6e pendent statemen
31df0 74 73 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 ts..**.** On suc
31e00 63 65 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 cess, SQLITE_OK
31e10 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 is returned..**
31e20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20 20 5b Otherwise, an [
31e30 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 error code] or a
31e40 6e 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f n [extended erro
31e50 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 r code] is retur
31e60 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 ned..**.** Requi
31e70 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 rements:.** [H17
31e80 38 37 33 5d 20 5b 48 31 37 38 37 34 5d 20 5b 48 873] [H17874] [H
31e90 31 37 38 37 35 5d 20 5b 48 31 37 38 37 36 5d 20 17875] [H17876]
31ea0 5b 48 31 37 38 37 37 5d 20 5b 48 31 37 38 37 39 [H17877] [H17879
31eb0 5d 20 5b 48 31 37 38 38 32 5d 20 5b 48 31 37 38 ] [H17882] [H178
31ec0 38 35 5d 0a 2a 2a 20 5b 48 31 37 38 38 38 5d 0a 85].** [H17888].
31ed0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 */.int sqlite3_b
31ee0 6c 6f 62 5f 77 72 69 74 65 28 73 71 6c 69 74 65 lob_write(sqlite
31ef0 33 5f 62 6c 6f 62 20 2a 2c 20 63 6f 6e 73 74 20 3_blob *, const
31f00 76 6f 69 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 void *z, int n,
31f10 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f int iOffset);../
31f20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 *.** CAPI3REF: V
31f30 69 72 74 75 61 6c 20 46 69 6c 65 20 53 79 73 74 irtual File Syst
31f40 65 6d 20 4f 62 6a 65 63 74 73 20 7b 48 31 31 32 em Objects {H112
31f50 30 30 7d 20 3c 53 32 30 31 30 30 3e 0a 2a 2a 0a 00} <S20100>.**.
31f60 2a 2a 20 41 20 76 69 72 74 75 61 6c 20 66 69 6c ** A virtual fil
31f70 65 73 79 73 74 65 6d 20 28 56 46 53 29 20 69 73 esystem (VFS) is
31f80 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 an [sqlite3_vfs
31f90 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 74 68 61 74 ] object.** that
31fa0 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 6f 20 SQLite uses to
31fb0 69 6e 74 65 72 61 63 74 0a 2a 2a 20 77 69 74 68 interact.** with
31fc0 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 the underlying
31fd0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d operating system
31fe0 2e 20 20 4d 6f 73 74 20 53 51 4c 69 74 65 20 62 . Most SQLite b
31ff0 75 69 6c 64 73 20 63 6f 6d 65 20 77 69 74 68 20 uilds come with
32000 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 64 65 66 61 a.** single defa
32010 75 6c 74 20 56 46 53 20 74 68 61 74 20 69 73 20 ult VFS that is
32020 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 appropriate for
32030 74 68 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 the host compute
32040 72 2e 0a 2a 2a 20 4e 65 77 20 56 46 53 65 73 20 r..** New VFSes
32050 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 can be registere
32060 64 20 61 6e 64 20 65 78 69 73 74 69 6e 67 20 56 d and existing V
32070 46 53 65 73 20 63 61 6e 20 62 65 20 75 6e 72 65 FSes can be unre
32080 67 69 73 74 65 72 65 64 2e 0a 2a 2a 20 54 68 65 gistered..** The
32090 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 following inter
320a0 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 faces are provid
320b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ed..**.** The sq
320c0 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 lite3_vfs_find()
320d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
320e0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
320f0 61 20 56 46 53 20 67 69 76 65 6e 20 69 74 73 20 a VFS given its
32100 6e 61 6d 65 2e 0a 2a 2a 20 4e 61 6d 65 73 20 61 name..** Names a
32110 72 65 20 63 61 73 65 20 73 65 6e 73 69 74 69 76 re case sensitiv
32120 65 2e 0a 2a 2a 20 4e 61 6d 65 73 20 61 72 65 20 e..** Names are
32130 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
32140 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a UTF-8 strings..*
32150 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f * If there is no
32160 20 6d 61 74 63 68 2c 20 61 20 4e 55 4c 4c 20 70 match, a NULL p
32170 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e ointer is return
32180 65 64 2e 0a 2a 2a 20 49 66 20 7a 56 66 73 4e 61 ed..** If zVfsNa
32190 6d 65 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 me is NULL then
321a0 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 the default VFS
321b0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a is returned..**.
321c0 2a 2a 20 4e 65 77 20 56 46 53 65 73 20 61 72 65 ** New VFSes are
321d0 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 registered with
321e0 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 sqlite3_vfs_reg
321f0 69 73 74 65 72 28 29 2e 0a 2a 2a 20 45 61 63 68 ister()..** Each
32200 20 6e 65 77 20 56 46 53 20 62 65 63 6f 6d 65 73 new VFS becomes
32210 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 the default VFS
32220 20 69 66 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 if the makeDflt
32230 20 66 6c 61 67 20 69 73 20 73 65 74 2e 0a 2a 2a flag is set..**
32240 20 54 68 65 20 73 61 6d 65 20 56 46 53 20 63 61 The same VFS ca
32250 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 n be registered
32260 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77 multiple times w
32270 69 74 68 6f 75 74 20 69 6e 6a 75 72 79 2e 0a 2a ithout injury..*
32280 2a 20 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78 69 * To make an exi
32290 73 74 69 6e 67 20 56 46 53 20 69 6e 74 6f 20 74 sting VFS into t
322a0 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 2c 20 he default VFS,
322b0 72 65 67 69 73 74 65 72 20 69 74 20 61 67 61 69 register it agai
322c0 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6d 61 n.** with the ma
322d0 6b 65 44 66 6c 74 20 66 6c 61 67 20 73 65 74 2e keDflt flag set.
322e0 20 20 49 66 20 74 77 6f 20 64 69 66 66 65 72 65 If two differe
322f0 6e 74 20 56 46 53 65 73 20 77 69 74 68 20 74 68 nt VFSes with th
32300 65 0a 2a 2a 20 73 61 6d 65 20 6e 61 6d 65 20 61 e.** same name a
32310 72 65 20 72 65 67 69 73 74 65 72 65 64 2c 20 74 re registered, t
32320 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 he behavior is u
32330 6e 64 65 66 69 6e 65 64 2e 20 20 49 66 20 61 0a ndefined. If a.
32340 2a 2a 20 56 46 53 20 69 73 20 72 65 67 69 73 74 ** VFS is regist
32350 65 72 65 64 20 77 69 74 68 20 61 20 6e 61 6d 65 ered with a name
32360 20 74 68 61 74 20 69 73 20 4e 55 4c 4c 20 6f 72 that is NULL or
32370 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 an empty string
32380 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 ,.** then the be
32390 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 havior is undefi
323a0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 55 6e 72 65 67 ned..**.** Unreg
323b0 69 73 74 65 72 20 61 20 56 46 53 20 77 69 74 68 ister a VFS with
323c0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 the sqlite3_vfs
323d0 5f 75 6e 72 65 67 69 73 74 65 72 28 29 20 69 6e _unregister() in
323e0 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 66 20 74 terface..** If t
323f0 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 he default VFS i
32400 73 20 75 6e 72 65 67 69 73 74 65 72 65 64 2c 20 s unregistered,
32410 61 6e 6f 74 68 65 72 20 56 46 53 20 69 73 20 63 another VFS is c
32420 68 6f 73 65 6e 20 61 73 0a 2a 2a 20 74 68 65 20 hosen as.** the
32430 64 65 66 61 75 6c 74 2e 20 20 54 68 65 20 63 68 default. The ch
32440 6f 69 63 65 20 66 6f 72 20 74 68 65 20 6e 65 77 oice for the new
32450 20 56 46 53 20 69 73 20 61 72 62 69 74 72 61 72 VFS is arbitrar
32460 79 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 y..**.** Require
32470 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 31 32 30 ments:.** [H1120
32480 33 5d 20 5b 48 31 31 32 30 36 5d 20 5b 48 31 31 3] [H11206] [H11
32490 32 30 39 5d 20 5b 48 31 31 32 31 32 5d 20 5b 48 209] [H11212] [H
324a0 31 31 32 31 35 5d 20 5b 48 31 31 32 31 38 5d 0a 11215] [H11218].
324b0 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 66 73 20 2a */.sqlite3_vfs *
324c0 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 sqlite3_vfs_find
324d0 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 (const char *zVf
324e0 73 4e 61 6d 65 29 3b 0a 69 6e 74 20 73 71 6c 69 sName);.int sqli
324f0 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 te3_vfs_register
32500 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 (sqlite3_vfs*, i
32510 6e 74 20 6d 61 6b 65 44 66 6c 74 29 3b 0a 69 6e nt makeDflt);.in
32520 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e t sqlite3_vfs_un
32530 72 65 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 register(sqlite3
32540 5f 76 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 _vfs*);../*.** C
32550 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 65 73 API3REF: Mutexes
32560 20 7b 48 31 37 30 30 30 7d 20 3c 53 32 30 30 30 {H17000} <S2000
32570 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 0>.**.** The SQL
32580 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 ite core uses th
32590 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 ese routines for
325a0 20 74 68 72 65 61 64 0a 2a 2a 20 73 79 6e 63 68 thread.** synch
325b0 72 6f 6e 69 7a 61 74 69 6f 6e 2e 20 54 68 6f 75 ronization. Thou
325c0 67 68 20 74 68 65 79 20 61 72 65 20 69 6e 74 65 gh they are inte
325d0 6e 64 65 64 20 66 6f 72 20 69 6e 74 65 72 6e 61 nded for interna
325e0 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69 l.** use by SQLi
325f0 74 65 2c 20 63 6f 64 65 20 74 68 61 74 20 6c 69 te, code that li
32600 6e 6b 73 20 61 67 61 69 6e 73 74 20 53 51 4c 69 nks against SQLi
32610 74 65 20 69 73 0a 2a 2a 20 70 65 72 6d 69 74 74 te is.** permitt
32620 65 64 20 74 6f 20 75 73 65 20 61 6e 79 20 6f 66 ed to use any of
32630 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e these routines.
32640 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 .**.** The SQLit
32650 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 63 6f e source code co
32660 6e 74 61 69 6e 73 20 6d 75 6c 74 69 70 6c 65 20 ntains multiple
32670 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a implementations.
32680 2a 2a 20 6f 66 20 74 68 65 73 65 20 6d 75 74 65 ** of these mute
32690 78 20 72 6f 75 74 69 6e 65 73 2e 20 20 41 6e 20 x routines. An
326a0 61 70 70 72 6f 70 72 69 61 74 65 20 69 6d 70 6c appropriate impl
326b0 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 ementation.** is
326c0 20 73 65 6c 65 63 74 65 64 20 61 75 74 6f 6d 61 selected automa
326d0 74 69 63 61 6c 6c 79 20 61 74 20 63 6f 6d 70 69 tically at compi
326e0 6c 65 2d 74 69 6d 65 2e 20 20 54 68 65 20 66 6f le-time. The fo
326f0 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 69 6d 70 6c 65 llowing.** imple
32700 6d 65 6e 74 61 74 69 6f 6e 73 20 61 72 65 20 61 mentations are a
32710 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 vailable in the
32720 53 51 4c 69 74 65 20 63 6f 72 65 3a 0a 2a 2a 0a SQLite core:.**.
32730 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
32740 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f SQLITE_MUTEX_O
32750 53 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c S2.** <li> SQL
32760 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52 45 41 ITE_MUTEX_PTHREA
32770 44 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 D.** <li> SQLI
32780 54 45 5f 4d 55 54 45 58 5f 57 33 32 0a 2a 2a 20 TE_MUTEX_W32.**
32790 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 <li> SQLITE_MU
327a0 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20 3c 2f 75 6c TEX_NOOP.** </ul
327b0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 >.**.** The SQLI
327c0 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 20 69 6d TE_MUTEX_NOOP im
327d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 plementation is
327e0 61 20 73 65 74 20 6f 66 20 72 6f 75 74 69 6e 65 a set of routine
327f0 73 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e s.** that does n
32800 6f 20 72 65 61 6c 20 6c 6f 63 6b 69 6e 67 20 61 o real locking a
32810 6e 64 20 69 73 20 61 70 70 72 6f 70 72 69 61 74 nd is appropriat
32820 65 20 66 6f 72 20 75 73 65 20 69 6e 0a 2a 2a 20 e for use in.**
32830 61 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 a single-threade
32840 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 d application.
32850 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 The SQLITE_MUTEX
32860 5f 4f 53 32 2c 0a 2a 2a 20 53 51 4c 49 54 45 5f _OS2,.** SQLITE_
32870 4d 55 54 45 58 5f 50 54 48 52 45 41 44 2c 20 61 MUTEX_PTHREAD, a
32880 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f nd SQLITE_MUTEX_
32890 57 33 32 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 W32 implementati
328a0 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 70 70 72 6f ons.** are appro
328b0 70 72 69 61 74 65 20 66 6f 72 20 75 73 65 20 6f priate for use o
328c0 6e 20 4f 53 2f 32 2c 20 55 6e 69 78 2c 20 61 6e n OS/2, Unix, an
328d0 64 20 57 69 6e 64 6f 77 73 2e 0a 2a 2a 0a 2a 2a d Windows..**.**
328e0 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f If SQLite is co
328f0 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 mpiled with the
32900 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 SQLITE_MUTEX_APP
32910 44 45 46 20 70 72 65 70 72 6f 63 65 73 73 6f 72 DEF preprocessor
32920 0a 2a 2a 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 .** macro define
32930 64 20 28 77 69 74 68 20 22 2d 44 53 51 4c 49 54 d (with "-DSQLIT
32940 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 3d 31 E_MUTEX_APPDEF=1
32950 22 29 2c 20 74 68 65 6e 20 6e 6f 20 6d 75 74 65 "), then no mute
32960 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 x.** implementat
32970 69 6f 6e 20 69 73 20 69 6e 63 6c 75 64 65 64 20 ion is included
32980 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 with the library
32990 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 20 74 . In this case t
329a0 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f he.** applicatio
329b0 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 n must supply a
329c0 63 75 73 74 6f 6d 20 6d 75 74 65 78 20 69 6d 70 custom mutex imp
329d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 69 6e lementation usin
329e0 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 g the.** [SQLITE
329f0 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f _CONFIG_MUTEX] o
32a00 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 71 6c ption of the sql
32a10 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 66 75 ite3_config() fu
32a20 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 66 6f 72 65 nction.** before
32a30 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 calling sqlite3
32a40 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 6f 72 _initialize() or
32a50 20 61 6e 79 20 6f 74 68 65 72 20 70 75 62 6c 69 any other publi
32a60 63 20 73 71 6c 69 74 65 33 5f 0a 2a 2a 20 66 75 c sqlite3_.** fu
32a70 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 61 6c 6c nction that call
32a80 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 s sqlite3_initia
32a90 6c 69 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 lize()..**.** {H
32aa0 31 37 30 31 31 7d 20 54 68 65 20 73 71 6c 69 74 17011} The sqlit
32ab0 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 e3_mutex_alloc()
32ac0 20 72 6f 75 74 69 6e 65 20 61 6c 6c 6f 63 61 74 routine allocat
32ad0 65 73 20 61 20 6e 65 77 0a 2a 2a 20 6d 75 74 65 es a new.** mute
32ae0 78 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 x and returns a
32af0 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e 20 7b pointer to it. {
32b00 48 31 37 30 31 32 7d 20 49 66 20 69 74 20 72 65 H17012} If it re
32b10 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 turns NULL.** th
32b20 61 74 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 at means that a
32b30 6d 75 74 65 78 20 63 6f 75 6c 64 20 6e 6f 74 20 mutex could not
32b40 62 65 20 61 6c 6c 6f 63 61 74 65 64 2e 20 7b 48 be allocated. {H
32b50 31 37 30 31 33 7d 20 53 51 4c 69 74 65 0a 2a 2a 17013} SQLite.**
32b60 20 77 69 6c 6c 20 75 6e 77 69 6e 64 20 69 74 73 will unwind its
32b70 20 73 74 61 63 6b 20 61 6e 64 20 72 65 74 75 72 stack and retur
32b80 6e 20 61 6e 20 65 72 72 6f 72 2e 20 7b 48 31 37 n an error. {H17
32b90 30 31 34 7d 20 54 68 65 20 61 72 67 75 6d 65 6e 014} The argumen
32ba0 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f t.** to sqlite3_
32bb0 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 69 73 mutex_alloc() is
32bc0 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e one of these in
32bd0 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 3a teger constants:
32be0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
32bf0 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 li> SQLITE_MUTE
32c00 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20 X_FAST.** <li>
32c10 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 SQLITE_MUTEX_REC
32c20 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 URSIVE.** <li>
32c30 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 SQLITE_MUTEX_STA
32c40 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c TIC_MASTER.** <l
32c50 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 i> SQLITE_MUTEX
32c60 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c _STATIC_MEM.** <
32c70 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 li> SQLITE_MUTE
32c80 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 0a 2a 2a X_STATIC_MEM2.**
32c90 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 <li> SQLITE_MU
32ca0 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 0a TEX_STATIC_PRNG.
32cb0 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f ** <li> SQLITE_
32cc0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 MUTEX_STATIC_LRU
32cd0 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 .** <li> SQLITE
32ce0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 _MUTEX_STATIC_LR
32cf0 55 32 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a U2.** </ul>.**.*
32d00 2a 20 7b 48 31 37 30 31 35 7d 20 54 68 65 20 66 * {H17015} The f
32d10 69 72 73 74 20 74 77 6f 20 63 6f 6e 73 74 61 6e irst two constan
32d20 74 73 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 ts cause sqlite3
32d30 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 74 _mutex_alloc() t
32d40 6f 20 63 72 65 61 74 65 0a 2a 2a 20 61 20 6e 65 o create.** a ne
32d50 77 20 6d 75 74 65 78 2e 20 20 54 68 65 20 6e 65 w mutex. The ne
32d60 77 20 6d 75 74 65 78 20 69 73 20 72 65 63 75 72 w mutex is recur
32d70 73 69 76 65 20 77 68 65 6e 20 53 51 4c 49 54 45 sive when SQLITE
32d80 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 _MUTEX_RECURSIVE
32d90 0a 2a 2a 20 69 73 20 75 73 65 64 20 62 75 74 20 .** is used but
32da0 6e 6f 74 20 6e 65 63 65 73 73 61 72 69 6c 79 20 not necessarily
32db0 73 6f 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d so when SQLITE_M
32dc0 55 54 45 58 5f 46 41 53 54 20 69 73 20 75 73 65 UTEX_FAST is use
32dd0 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 54 68 65 20 d. {END}.** The
32de0 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 mutex implementa
32df0 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 tion does not ne
32e00 65 64 20 74 6f 20 6d 61 6b 65 20 61 20 64 69 73 ed to make a dis
32e10 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 tinction.** betw
32e20 65 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 een SQLITE_MUTEX
32e30 5f 52 45 43 55 52 53 49 56 45 20 61 6e 64 20 53 _RECURSIVE and S
32e40 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 QLITE_MUTEX_FAST
32e50 20 69 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e if it does.** n
32e60 6f 74 20 77 61 6e 74 20 74 6f 2e 20 20 7b 48 31 ot want to. {H1
32e70 37 30 31 36 7d 20 42 75 74 20 53 51 4c 69 74 65 7016} But SQLite
32e80 20 77 69 6c 6c 20 6f 6e 6c 79 20 72 65 71 75 65 will only reque
32e90 73 74 20 61 20 72 65 63 75 72 73 69 76 65 20 6d st a recursive m
32ea0 75 74 65 78 20 69 6e 0a 2a 2a 20 63 61 73 65 73 utex in.** cases
32eb0 20 77 68 65 72 65 20 69 74 20 72 65 61 6c 6c 79 where it really
32ec0 20 6e 65 65 64 73 20 6f 6e 65 2e 20 20 7b 45 4e needs one. {EN
32ed0 44 7d 20 49 66 20 61 20 66 61 73 74 65 72 20 6e D} If a faster n
32ee0 6f 6e 2d 72 65 63 75 72 73 69 76 65 20 6d 75 74 on-recursive mut
32ef0 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 ex.** implementa
32f00 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c tion is availabl
32f10 65 20 6f 6e 20 74 68 65 20 68 6f 73 74 20 70 6c e on the host pl
32f20 61 74 66 6f 72 6d 2c 20 74 68 65 20 6d 75 74 65 atform, the mute
32f30 78 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20 6d x subsystem.** m
32f40 69 67 68 74 20 72 65 74 75 72 6e 20 73 75 63 68 ight return such
32f50 20 61 20 6d 75 74 65 78 20 69 6e 20 72 65 73 70 a mutex in resp
32f60 6f 6e 73 65 20 74 6f 20 53 51 4c 49 54 45 5f 4d onse to SQLITE_M
32f70 55 54 45 58 5f 46 41 53 54 2e 0a 2a 2a 0a 2a 2a UTEX_FAST..**.**
32f80 20 7b 48 31 37 30 31 37 7d 20 54 68 65 20 6f 74 {H17017} The ot
32f90 68 65 72 20 61 6c 6c 6f 77 65 64 20 70 61 72 61 her allowed para
32fa0 6d 65 74 65 72 73 20 74 6f 20 73 71 6c 69 74 65 meters to sqlite
32fb0 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 3_mutex_alloc()
32fc0 65 61 63 68 20 72 65 74 75 72 6e 0a 2a 2a 20 61 each return.** a
32fd0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 pointer to a st
32fe0 61 74 69 63 20 70 72 65 65 78 69 73 74 69 6e 67 atic preexisting
32ff0 20 6d 75 74 65 78 2e 20 7b 45 4e 44 7d 20 20 46 mutex. {END} F
33000 6f 75 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 our static mutex
33010 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 62 es are.** used b
33020 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 65 y the current ve
33030 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 2e rsion of SQLite.
33040 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e Future version
33050 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d s of SQLite.** m
33060 61 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 ay add additiona
33070 6c 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 l static mutexes
33080 2e 20 20 53 74 61 74 69 63 20 6d 75 74 65 78 65 . Static mutexe
33090 73 20 61 72 65 20 66 6f 72 20 69 6e 74 65 72 6e s are for intern
330a0 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c al.** use by SQL
330b0 69 74 65 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 ite only. Appli
330c0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 cations that use
330d0 20 53 51 4c 69 74 65 20 6d 75 74 65 78 65 73 20 SQLite mutexes
330e0 73 68 6f 75 6c 64 0a 2a 2a 20 75 73 65 20 6f 6e should.** use on
330f0 6c 79 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d ly the dynamic m
33100 75 74 65 78 65 73 20 72 65 74 75 72 6e 65 64 20 utexes returned
33110 62 79 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f by SQLITE_MUTEX_
33120 46 41 53 54 20 6f 72 0a 2a 2a 20 53 51 4c 49 54 FAST or.** SQLIT
33130 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 E_MUTEX_RECURSIV
33140 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 38 E..**.** {H17018
33150 7d 20 4e 6f 74 65 20 74 68 61 74 20 69 66 20 6f } Note that if o
33160 6e 65 20 6f 66 20 74 68 65 20 64 79 6e 61 6d 69 ne of the dynami
33170 63 20 6d 75 74 65 78 20 70 61 72 61 6d 65 74 65 c mutex paramete
33180 72 73 20 28 53 51 4c 49 54 45 5f 4d 55 54 45 58 rs (SQLITE_MUTEX
33190 5f 46 41 53 54 0a 2a 2a 20 6f 72 20 53 51 4c 49 _FAST.** or SQLI
331a0 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 TE_MUTEX_RECURSI
331b0 56 45 29 20 69 73 20 75 73 65 64 20 74 68 65 6e VE) is used then
331c0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 sqlite3_mutex_a
331d0 6c 6c 6f 63 28 29 0a 2a 2a 20 72 65 74 75 72 6e lloc().** return
331e0 73 20 61 20 64 69 66 66 65 72 65 6e 74 20 6d 75 s a different mu
331f0 74 65 78 20 6f 6e 20 65 76 65 72 79 20 63 61 6c tex on every cal
33200 6c 2e 20 20 7b 48 31 37 30 33 34 7d 20 42 75 74 l. {H17034} But
33210 20 66 6f 72 20 74 68 65 20 73 74 61 74 69 63 0a for the static.
33220 2a 2a 20 6d 75 74 65 78 20 74 79 70 65 73 2c 20 ** mutex types,
33230 74 68 65 20 73 61 6d 65 20 6d 75 74 65 78 20 69 the same mutex i
33240 73 20 72 65 74 75 72 6e 65 64 20 6f 6e 20 65 76 s returned on ev
33250 65 72 79 20 63 61 6c 6c 20 74 68 61 74 20 68 61 ery call that ha
33260 73 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 79 s.** the same ty
33270 70 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a pe number..**.**
33280 20 7b 48 31 37 30 31 39 7d 20 54 68 65 20 73 71 {H17019} The sq
33290 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 lite3_mutex_free
332a0 28 29 20 72 6f 75 74 69 6e 65 20 64 65 61 6c 6c () routine deall
332b0 6f 63 61 74 65 73 20 61 20 70 72 65 76 69 6f 75 ocates a previou
332c0 73 6c 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 sly.** allocated
332d0 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 2e 20 dynamic mutex.
332e0 7b 48 31 37 30 32 30 7d 20 53 51 4c 69 74 65 20 {H17020} SQLite
332f0 69 73 20 63 61 72 65 66 75 6c 20 74 6f 20 64 65 is careful to de
33300 61 6c 6c 6f 63 61 74 65 20 65 76 65 72 79 0a 2a allocate every.*
33310 2a 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 * dynamic mutex
33320 74 68 61 74 20 69 74 20 61 6c 6c 6f 63 61 74 65 that it allocate
33330 73 2e 20 7b 41 31 37 30 32 31 7d 20 54 68 65 20 s. {A17021} The
33340 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65 73 20 dynamic mutexes
33350 6d 75 73 74 20 6e 6f 74 20 62 65 20 69 6e 0a 2a must not be in.*
33360 2a 20 75 73 65 20 77 68 65 6e 20 74 68 65 79 20 * use when they
33370 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e are deallocated.
33380 20 7b 41 31 37 30 32 32 7d 20 41 74 74 65 6d 70 {A17022} Attemp
33390 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c 6f 63 61 ting to dealloca
333a0 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a 20 6d te a static.** m
333b0 75 74 65 78 20 72 65 73 75 6c 74 73 20 69 6e 20 utex results in
333c0 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 undefined behavi
333d0 6f 72 2e 20 7b 48 31 37 30 32 33 7d 20 53 51 4c or. {H17023} SQL
333e0 69 74 65 20 6e 65 76 65 72 20 64 65 61 6c 6c 6f ite never deallo
333f0 63 61 74 65 73 0a 2a 2a 20 61 20 73 74 61 74 69 cates.** a stati
33400 63 20 6d 75 74 65 78 2e 20 7b 45 4e 44 7d 0a 2a c mutex. {END}.*
33410 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
33420 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 20 61 _mutex_enter() a
33430 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 nd sqlite3_mutex
33440 5f 74 72 79 28 29 20 72 6f 75 74 69 6e 65 73 20 _try() routines
33450 61 74 74 65 6d 70 74 0a 2a 2a 20 74 6f 20 65 6e attempt.** to en
33460 74 65 72 20 61 20 6d 75 74 65 78 2e 20 7b 48 31 ter a mutex. {H1
33470 37 30 32 34 7d 20 49 66 20 61 6e 6f 74 68 65 72 7024} If another
33480 20 74 68 72 65 61 64 20 69 73 20 61 6c 72 65 61 thread is alrea
33490 64 79 20 77 69 74 68 69 6e 20 74 68 65 20 6d 75 dy within the mu
334a0 74 65 78 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f tex,.** sqlite3_
334b0 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 20 77 69 mutex_enter() wi
334c0 6c 6c 20 62 6c 6f 63 6b 20 61 6e 64 20 73 71 6c ll block and sql
334d0 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 ite3_mutex_try()
334e0 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 will return.**
334f0 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 7b 48 31 SQLITE_BUSY. {H1
33500 37 30 32 35 7d 20 20 54 68 65 20 73 71 6c 69 74 7025} The sqlit
33510 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 69 e3_mutex_try() i
33520 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
33530 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 [SQLITE_OK].**
33540 75 70 6f 6e 20 73 75 63 63 65 73 73 66 75 6c 20 upon successful
33550 65 6e 74 72 79 2e 20 20 7b 48 31 37 30 32 36 7d entry. {H17026}
33560 20 4d 75 74 65 78 65 73 20 63 72 65 61 74 65 64 Mutexes created
33570 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 using.** SQLITE
33580 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 _MUTEX_RECURSIVE
33590 20 63 61 6e 20 62 65 20 65 6e 74 65 72 65 64 20 can be entered
335a0 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 62 multiple times b
335b0 79 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 y the same threa
335c0 64 2e 0a 2a 2a 20 7b 48 31 37 30 32 37 7d 20 49 d..** {H17027} I
335d0 6e 20 73 75 63 68 20 63 61 73 65 73 20 74 68 65 n such cases the
335e0 2c 0a 2a 2a 20 6d 75 74 65 78 20 6d 75 73 74 20 ,.** mutex must
335f0 62 65 20 65 78 69 74 65 64 20 61 6e 20 65 71 75 be exited an equ
33600 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d al number of tim
33610 65 73 20 62 65 66 6f 72 65 20 61 6e 6f 74 68 65 es before anothe
33620 72 20 74 68 72 65 61 64 0a 2a 2a 20 63 61 6e 20 r thread.** can
33630 65 6e 74 65 72 2e 20 20 7b 41 31 37 30 32 38 7d enter. {A17028}
33640 20 49 66 20 74 68 65 20 73 61 6d 65 20 74 68 72 If the same thr
33650 65 61 64 20 74 72 69 65 73 20 74 6f 20 65 6e 74 ead tries to ent
33660 65 72 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 er any other.**
33670 6b 69 6e 64 20 6f 66 20 6d 75 74 65 78 20 6d 6f kind of mutex mo
33680 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 74 68 re than once, th
33690 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e e behavior is un
336a0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 7b 48 31 37 defined..** {H17
336b0 30 32 39 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 029} SQLite will
336c0 20 6e 65 76 65 72 20 65 78 68 69 62 69 74 0a 2a never exhibit.*
336d0 2a 20 73 75 63 68 20 62 65 68 61 76 69 6f 72 20 * such behavior
336e0 69 6e 20 69 74 73 20 6f 77 6e 20 75 73 65 20 6f in its own use o
336f0 66 20 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a 2a 2a f mutexes..**.**
33700 20 53 6f 6d 65 20 73 79 73 74 65 6d 73 20 28 66 Some systems (f
33710 6f 72 20 65 78 61 6d 70 6c 65 2c 20 57 69 6e 64 or example, Wind
33720 6f 77 73 20 39 35 29 20 64 6f 20 6e 6f 74 20 73 ows 95) do not s
33730 75 70 70 6f 72 74 20 74 68 65 20 6f 70 65 72 61 upport the opera
33740 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e tion.** implemen
33750 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d ted by sqlite3_m
33760 75 74 65 78 5f 74 72 79 28 29 2e 20 20 4f 6e 20 utex_try(). On
33770 74 68 6f 73 65 20 73 79 73 74 65 6d 73 2c 20 73 those systems, s
33780 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 qlite3_mutex_try
33790 28 29 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 79 ().** will alway
337a0 73 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f s return SQLITE_
337b0 42 55 53 59 2e 20 20 7b 48 31 37 30 33 30 7d 20 BUSY. {H17030}
337c0 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 The SQLite core
337d0 6f 6e 6c 79 20 65 76 65 72 20 75 73 65 73 0a 2a only ever uses.*
337e0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f * sqlite3_mutex_
337f0 74 72 79 28 29 20 61 73 20 61 6e 20 6f 70 74 69 try() as an opti
33800 6d 69 7a 61 74 69 6f 6e 20 73 6f 20 74 68 69 73 mization so this
33810 20 69 73 20 61 63 63 65 70 74 61 62 6c 65 20 62 is acceptable b
33820 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b ehavior..**.** {
33830 48 31 37 30 33 31 7d 20 54 68 65 20 73 71 6c 69 H17031} The sqli
33840 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 te3_mutex_leave(
33850 29 20 72 6f 75 74 69 6e 65 20 65 78 69 74 73 20 ) routine exits
33860 61 20 6d 75 74 65 78 20 74 68 61 74 20 77 61 73 a mutex that was
33870 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 65 .** previously e
33880 6e 74 65 72 65 64 20 62 79 20 74 68 65 20 73 61 ntered by the sa
33890 6d 65 20 74 68 72 65 61 64 2e 20 20 7b 41 31 37 me thread. {A17
338a0 30 33 32 7d 20 54 68 65 20 62 65 68 61 76 69 6f 032} The behavio
338b0 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 r.** is undefine
338c0 64 20 69 66 20 74 68 65 20 6d 75 74 65 78 20 69 d if the mutex i
338d0 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 s not currently
338e0 65 6e 74 65 72 65 64 20 62 79 20 74 68 65 0a 2a entered by the.*
338f0 2a 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 * calling thread
33900 20 6f 72 20 69 73 20 6e 6f 74 20 63 75 72 72 65 or is not curre
33910 6e 74 6c 79 20 61 6c 6c 6f 63 61 74 65 64 2e 20 ntly allocated.
33920 20 7b 48 31 37 30 33 33 7d 20 53 51 4c 69 74 65 {H17033} SQLite
33930 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 64 will.** never d
33940 6f 20 65 69 74 68 65 72 2e 20 7b 45 4e 44 7d 0a o either. {END}.
33950 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 61 72 67 **.** If the arg
33960 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 ument to sqlite3
33970 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 2c 20 _mutex_enter(),
33980 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 sqlite3_mutex_tr
33990 79 28 29 2c 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 y(), or.** sqlit
339a0 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 e3_mutex_leave()
339b0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
339c0 65 72 2c 20 74 68 65 6e 20 61 6c 6c 20 74 68 72 er, then all thr
339d0 65 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 62 ee routines.** b
339e0 65 68 61 76 65 20 61 73 20 6e 6f 2d 6f 70 73 2e ehave as no-ops.
339f0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
33a00 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
33a10 68 65 6c 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c held()] and [sql
33a20 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 ite3_mutex_nothe
33a30 6c 64 28 29 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 ld()]..*/.sqlite
33a40 33 5f 6d 75 74 65 78 20 2a 73 71 6c 69 74 65 33 3_mutex *sqlite3
33a50 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 69 6e 74 _mutex_alloc(int
33a60 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
33a70 6d 75 74 65 78 5f 66 72 65 65 28 73 71 6c 69 74 mutex_free(sqlit
33a80 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 e3_mutex*);.void
33a90 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 sqlite3_mutex_e
33aa0 6e 74 65 72 28 73 71 6c 69 74 65 33 5f 6d 75 74 nter(sqlite3_mut
33ab0 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 ex*);.int sqlite
33ac0 33 5f 6d 75 74 65 78 5f 74 72 79 28 73 71 6c 69 3_mutex_try(sqli
33ad0 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 te3_mutex*);.voi
33ae0 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f d sqlite3_mutex_
33af0 6c 65 61 76 65 28 73 71 6c 69 74 65 33 5f 6d 75 leave(sqlite3_mu
33b00 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 tex*);../*.** CA
33b10 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 4d 65 PI3REF: Mutex Me
33b20 74 68 6f 64 73 20 4f 62 6a 65 63 74 20 7b 48 31 thods Object {H1
33b30 37 31 32 30 7d 20 3c 53 32 30 31 33 30 3e 0a 2a 7120} <S20130>.*
33b40 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
33b50 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 *.** An instance
33b60 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 of this structu
33b70 72 65 20 64 65 66 69 6e 65 73 20 74 68 65 20 6c re defines the l
33b80 6f 77 2d 6c 65 76 65 6c 20 72 6f 75 74 69 6e 65 ow-level routine
33b90 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 61 6c 6c s.** used to all
33ba0 6f 63 61 74 65 20 61 6e 64 20 75 73 65 20 6d 75 ocate and use mu
33bb0 74 65 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 55 73 75 texes..**.** Usu
33bc0 61 6c 6c 79 2c 20 74 68 65 20 64 65 66 61 75 6c ally, the defaul
33bd0 74 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e t mutex implemen
33be0 74 61 74 69 6f 6e 73 20 70 72 6f 76 69 64 65 64 tations provided
33bf0 20 62 79 20 53 51 4c 69 74 65 20 61 72 65 0a 2a by SQLite are.*
33c00 2a 20 73 75 66 66 69 63 69 65 6e 74 2c 20 68 6f * sufficient, ho
33c10 77 65 76 65 72 20 74 68 65 20 75 73 65 72 20 68 wever the user h
33c20 61 73 20 74 68 65 20 6f 70 74 69 6f 6e 20 6f 66 as the option of
33c30 20 73 75 62 73 74 69 74 75 74 69 6e 67 20 61 20 substituting a
33c40 63 75 73 74 6f 6d 0a 2a 2a 20 69 6d 70 6c 65 6d custom.** implem
33c50 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 73 70 65 entation for spe
33c60 63 69 61 6c 69 7a 65 64 20 64 65 70 6c 6f 79 6d cialized deploym
33c70 65 6e 74 73 20 6f 72 20 73 79 73 74 65 6d 73 20 ents or systems
33c80 66 6f 72 20 77 68 69 63 68 20 53 51 4c 69 74 65 for which SQLite
33c90 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f .** does not pro
33ca0 76 69 64 65 20 61 20 73 75 69 74 61 62 6c 65 20 vide a suitable
33cb0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 implementation.
33cc0 49 6e 20 74 68 69 73 20 63 61 73 65 2c 20 74 68 In this case, th
33cd0 65 20 75 73 65 72 0a 2a 2a 20 63 72 65 61 74 65 e user.** create
33ce0 73 20 61 6e 64 20 70 6f 70 75 6c 61 74 65 73 20 s and populates
33cf0 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 an instance of t
33d00 68 69 73 20 73 74 72 75 63 74 75 72 65 20 74 6f his structure to
33d10 20 70 61 73 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 pass.** to sqli
33d20 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 61 6c 6f te3_config() alo
33d30 6e 67 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c ng with the [SQL
33d40 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 ITE_CONFIG_MUTEX
33d50 5d 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 64 64 ] option..** Add
33d60 69 74 69 6f 6e 61 6c 6c 79 2c 20 61 6e 20 69 6e itionally, an in
33d70 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 stance of this s
33d80 74 72 75 63 74 75 72 65 20 63 61 6e 20 62 65 20 tructure can be
33d90 75 73 65 64 20 61 73 20 61 6e 0a 2a 2a 20 6f 75 used as an.** ou
33da0 74 70 75 74 20 76 61 72 69 61 62 6c 65 20 77 68 tput variable wh
33db0 65 6e 20 71 75 65 72 79 69 6e 67 20 74 68 65 20 en querying the
33dc0 73 79 73 74 65 6d 20 66 6f 72 20 74 68 65 20 63 system for the c
33dd0 75 72 72 65 6e 74 20 6d 75 74 65 78 0a 2a 2a 20 urrent mutex.**
33de0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 implementation,
33df0 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 using the [SQLIT
33e00 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 E_CONFIG_GETMUTE
33e10 58 5d 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a X] option..**.**
33e20 20 54 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20 The xMutexInit
33e30 6d 65 74 68 6f 64 20 64 65 66 69 6e 65 64 20 62 method defined b
33e40 79 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 y this structure
33e50 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 0a 2a is invoked as.*
33e60 2a 20 70 61 72 74 20 6f 66 20 73 79 73 74 65 6d * part of system
33e70 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 initialization
33e80 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 by the sqlite3_i
33e90 6e 69 74 69 61 6c 69 7a 65 28 29 20 66 75 6e 63 nitialize() func
33ea0 74 69 6f 6e 2e 0a 2a 2a 20 7b 48 31 37 30 30 31 tion..** {H17001
33eb0 7d 20 54 68 65 20 78 4d 75 74 65 78 49 6e 69 74 } The xMutexInit
33ec0 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 62 routine shall b
33ed0 65 20 63 61 6c 6c 65 64 20 62 79 20 53 51 4c 69 e called by SQLi
33ee0 74 65 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 te once for each
33ef0 0a 2a 2a 20 65 66 66 65 63 74 69 76 65 20 63 61 .** effective ca
33f00 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 69 ll to [sqlite3_i
33f10 6e 69 74 69 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a nitialize()]..**
33f20 0a 2a 2a 20 54 68 65 20 78 4d 75 74 65 78 45 6e .** The xMutexEn
33f30 64 20 6d 65 74 68 6f 64 20 64 65 66 69 6e 65 64 d method defined
33f40 20 62 79 20 74 68 69 73 20 73 74 72 75 63 74 75 by this structu
33f50 72 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 re is invoked as
33f60 0a 2a 2a 20 70 61 72 74 20 6f 66 20 73 79 73 74 .** part of syst
33f70 65 6d 20 73 68 75 74 64 6f 77 6e 20 62 79 20 74 em shutdown by t
33f80 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 he sqlite3_shutd
33f90 6f 77 6e 28 29 20 66 75 6e 63 74 69 6f 6e 2e 20 own() function.
33fa0 54 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 The.** implement
33fb0 61 74 69 6f 6e 20 6f 66 20 74 68 69 73 20 6d 65 ation of this me
33fc0 74 68 6f 64 20 69 73 20 65 78 70 65 63 74 65 64 thod is expected
33fd0 20 74 6f 20 72 65 6c 65 61 73 65 20 61 6c 6c 20 to release all
33fe0 6f 75 74 73 74 61 6e 64 69 6e 67 0a 2a 2a 20 72 outstanding.** r
33ff0 65 73 6f 75 72 63 65 73 20 6f 62 74 61 69 6e 65 esources obtaine
34000 64 20 62 79 20 74 68 65 20 6d 75 74 65 78 20 6d d by the mutex m
34010 65 74 68 6f 64 73 20 69 6d 70 6c 65 6d 65 6e 74 ethods implement
34020 61 74 69 6f 6e 2c 20 65 73 70 65 63 69 61 6c 6c ation, especiall
34030 79 0a 2a 2a 20 74 68 6f 73 65 20 6f 62 74 61 69 y.** those obtai
34040 6e 65 64 20 62 79 20 74 68 65 20 78 4d 75 74 65 ned by the xMute
34050 78 49 6e 69 74 20 6d 65 74 68 6f 64 2e 20 7b 48 xInit method. {H
34060 31 37 30 30 33 7d 20 54 68 65 20 78 4d 75 74 65 17003} The xMute
34070 78 45 6e 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 xEnd().** interf
34080 61 63 65 20 73 68 61 6c 6c 20 62 65 20 69 6e 76 ace shall be inv
34090 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 oked once for ea
340a0 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 ch call to [sqli
340b0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e te3_shutdown()].
340c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 .**.** The remai
340d0 6e 69 6e 67 20 73 65 76 65 6e 20 6d 65 74 68 6f ning seven metho
340e0 64 73 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 ds defined by th
340f0 69 73 20 73 74 72 75 63 74 75 72 65 20 28 78 4d is structure (xM
34100 75 74 65 78 41 6c 6c 6f 63 2c 0a 2a 2a 20 78 4d utexAlloc,.** xM
34110 75 74 65 78 46 72 65 65 2c 20 78 4d 75 74 65 78 utexFree, xMutex
34120 45 6e 74 65 72 2c 20 78 4d 75 74 65 78 54 72 79 Enter, xMutexTry
34130 2c 20 78 4d 75 74 65 78 4c 65 61 76 65 2c 20 78 , xMutexLeave, x
34140 4d 75 74 65 78 48 65 6c 64 20 61 6e 64 0a 2a 2a MutexHeld and.**
34150 20 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 20 xMutexNotheld)
34160 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 66 6f implement the fo
34170 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 llowing interfac
34180 65 73 20 28 72 65 73 70 65 63 74 69 76 65 6c 79 es (respectively
34190 29 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a ):.**.** <ul>.**
341a0 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 <li> [sqlite
341b0 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 3_mutex_alloc()]
341c0 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e </li>.** <li>
341d0 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 [sqlite3_mutex
341e0 5f 66 72 65 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a _free()] </li>.*
341f0 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 * <li> [sqlit
34200 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 e3_mutex_enter()
34210 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 ] </li>.** <li
34220 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 > [sqlite3_mute
34230 78 5f 74 72 79 28 29 5d 20 3c 2f 6c 69 3e 0a 2a x_try()] </li>.*
34240 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 * <li> [sqlit
34250 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 e3_mutex_leave()
34260 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 ] </li>.** <li
34270 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 > [sqlite3_mute
34280 78 5f 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a x_held()] </li>.
34290 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 ** <li> [sqli
342a0 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c te3_mutex_nothel
342b0 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f d()] </li>.** </
342c0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 6e ul>.**.** The on
342d0 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 ly difference is
342e0 20 74 68 61 74 20 74 68 65 20 70 75 62 6c 69 63 that the public
342f0 20 73 71 6c 69 74 65 33 5f 58 58 58 20 66 75 6e sqlite3_XXX fun
34300 63 74 69 6f 6e 73 20 65 6e 75 6d 65 72 61 74 65 ctions enumerate
34310 64 0a 2a 2a 20 61 62 6f 76 65 20 73 69 6c 65 6e d.** above silen
34320 74 6c 79 20 69 67 6e 6f 72 65 20 61 6e 79 20 69 tly ignore any i
34330 6e 76 6f 63 61 74 69 6f 6e 73 20 74 68 61 74 20 nvocations that
34340 70 61 73 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e pass a NULL poin
34350 74 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f ter instead.** o
34360 66 20 61 20 76 61 6c 69 64 20 6d 75 74 65 78 20 f a valid mutex
34370 68 61 6e 64 6c 65 2e 20 54 68 65 20 69 6d 70 6c handle. The impl
34380 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 ementations of t
34390 68 65 20 6d 65 74 68 6f 64 73 20 64 65 66 69 6e he methods defin
343a0 65 64 0a 2a 2a 20 62 79 20 74 68 69 73 20 73 74 ed.** by this st
343b0 72 75 63 74 75 72 65 20 61 72 65 20 6e 6f 74 20 ructure are not
343c0 72 65 71 75 69 72 65 64 20 74 6f 20 68 61 6e 64 required to hand
343d0 6c 65 20 74 68 69 73 20 63 61 73 65 2c 20 74 68 le this case, th
343e0 65 20 72 65 73 75 6c 74 73 0a 2a 2a 20 6f 66 20 e results.** of
343f0 70 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 passing a NULL p
34400 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f ointer instead o
34410 66 20 61 20 76 61 6c 69 64 20 6d 75 74 65 78 20 f a valid mutex
34420 68 61 6e 64 6c 65 20 61 72 65 20 75 6e 64 65 66 handle are undef
34430 69 6e 65 64 0a 2a 2a 20 28 69 2e 65 2e 20 69 74 ined.** (i.e. it
34440 20 69 73 20 61 63 63 65 70 74 61 62 6c 65 20 74 is acceptable t
34450 6f 20 70 72 6f 76 69 64 65 20 61 6e 20 69 6d 70 o provide an imp
34460 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 lementation that
34470 20 73 65 67 66 61 75 6c 74 73 20 69 66 0a 2a 2a segfaults if.**
34480 20 69 74 20 69 73 20 70 61 73 73 65 64 20 61 20 it is passed a
34490 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 29 2e 0a 2a NULL pointer)..*
344a0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
344b0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d sqlite3_mutex_m
344c0 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d ethods sqlite3_m
344d0 75 74 65 78 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 utex_methods;.st
344e0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 ruct sqlite3_mut
344f0 65 78 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 ex_methods {. i
34500 6e 74 20 28 2a 78 4d 75 74 65 78 49 6e 69 74 29 nt (*xMutexInit)
34510 28 76 6f 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a (void);. int (*
34520 78 4d 75 74 65 78 45 6e 64 29 28 76 6f 69 64 29 xMutexEnd)(void)
34530 3b 0a 20 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 ;. sqlite3_mute
34540 78 20 2a 28 2a 78 4d 75 74 65 78 41 6c 6c 6f 63 x *(*xMutexAlloc
34550 29 28 69 6e 74 29 3b 0a 20 20 76 6f 69 64 20 28 )(int);. void (
34560 2a 78 4d 75 74 65 78 46 72 65 65 29 28 73 71 6c *xMutexFree)(sql
34570 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 ite3_mutex *);.
34580 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 45 6e void (*xMutexEn
34590 74 65 72 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 ter)(sqlite3_mut
345a0 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 ex *);. int (*x
345b0 4d 75 74 65 78 54 72 79 29 28 73 71 6c 69 74 65 MutexTry)(sqlite
345c0 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 3_mutex *);. vo
345d0 69 64 20 28 2a 78 4d 75 74 65 78 4c 65 61 76 65 id (*xMutexLeave
345e0 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 )(sqlite3_mutex
345f0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 *);. int (*xMut
34600 65 78 48 65 6c 64 29 28 73 71 6c 69 74 65 33 5f exHeld)(sqlite3_
34610 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20 mutex *);. int
34620 28 2a 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 (*xMutexNotheld)
34630 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a (sqlite3_mutex *
34640 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 );.};../*.** CAP
34650 49 33 52 45 46 3a 20 4d 75 74 65 78 20 56 65 72 I3REF: Mutex Ver
34660 69 66 69 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e ification Routin
34670 65 73 20 7b 48 31 37 30 38 30 7d 20 3c 53 32 30 es {H17080} <S20
34680 31 33 30 3e 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 130> <S30800>.**
34690 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
346a0 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 61 6e 64 mutex_held() and
346b0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e sqlite3_mutex_n
346c0 6f 74 68 65 6c 64 28 29 20 72 6f 75 74 69 6e 65 otheld() routine
346d0 73 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e 64 65 s.** are intende
346e0 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 d for use inside
346f0 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d assert() statem
34700 65 6e 74 73 2e 20 7b 48 31 37 30 38 31 7d 20 54 ents. {H17081} T
34710 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 0a 2a he SQLite core.*
34720 2a 20 6e 65 76 65 72 20 75 73 65 73 20 74 68 65 * never uses the
34730 73 65 20 72 6f 75 74 69 6e 65 73 20 65 78 63 65 se routines exce
34740 70 74 20 69 6e 73 69 64 65 20 61 6e 20 61 73 73 pt inside an ass
34750 65 72 74 28 29 20 61 6e 64 20 61 70 70 6c 69 63 ert() and applic
34760 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 64 ations.** are ad
34770 76 69 73 65 64 20 74 6f 20 66 6f 6c 6c 6f 77 20 vised to follow
34780 74 68 65 20 6c 65 61 64 20 6f 66 20 74 68 65 20 the lead of the
34790 63 6f 72 65 2e 20 20 7b 48 31 37 30 38 32 7d 20 core. {H17082}
347a0 54 68 65 20 63 6f 72 65 20 6f 6e 6c 79 0a 2a 2a The core only.**
347b0 20 70 72 6f 76 69 64 65 73 20 69 6d 70 6c 65 6d provides implem
347c0 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 entations for th
347d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 68 65 ese routines whe
347e0 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 n it is compiled
347f0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 53 51 4c .** with the SQL
34800 49 54 45 5f 44 45 42 55 47 20 66 6c 61 67 2e 20 ITE_DEBUG flag.
34810 20 7b 41 31 37 30 38 37 7d 20 45 78 74 65 72 6e {A17087} Extern
34820 61 6c 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 al mutex impleme
34830 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 ntations.** are
34840 6f 6e 6c 79 20 72 65 71 75 69 72 65 64 20 74 6f only required to
34850 20 70 72 6f 76 69 64 65 20 74 68 65 73 65 20 72 provide these r
34860 6f 75 74 69 6e 65 73 20 69 66 20 53 51 4c 49 54 outines if SQLIT
34870 45 5f 44 45 42 55 47 20 69 73 0a 2a 2a 20 64 65 E_DEBUG is.** de
34880 66 69 6e 65 64 20 61 6e 64 20 69 66 20 4e 44 45 fined and if NDE
34890 42 55 47 20 69 73 20 6e 6f 74 20 64 65 66 69 6e BUG is not defin
348a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 38 ed..**.** {H1708
348b0 33 7d 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 3} These routine
348c0 73 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 s should return
348d0 74 72 75 65 20 69 66 20 74 68 65 20 6d 75 74 65 true if the mute
348e0 78 20 69 6e 20 74 68 65 69 72 20 61 72 67 75 6d x in their argum
348f0 65 6e 74 0a 2a 2a 20 69 73 20 68 65 6c 64 20 6f ent.** is held o
34900 72 20 6e 6f 74 20 68 65 6c 64 2c 20 72 65 73 70 r not held, resp
34910 65 63 74 69 76 65 6c 79 2c 20 62 79 20 74 68 65 ectively, by the
34920 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 2e calling thread.
34930 0a 2a 2a 0a 2a 2a 20 7b 58 31 37 30 38 34 7d 20 .**.** {X17084}
34940 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 The implementati
34950 6f 6e 20 69 73 20 6e 6f 74 20 72 65 71 75 69 72 on is not requir
34960 65 64 20 74 6f 20 70 72 6f 76 69 64 65 64 20 76 ed to provided v
34970 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 ersions of these
34980 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 .** routines tha
34990 74 20 61 63 74 75 61 6c 6c 79 20 77 6f 72 6b 2e t actually work.
349a0 20 49 66 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e If the implemen
349b0 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 tation does not
349c0 70 72 6f 76 69 64 65 20 77 6f 72 6b 69 6e 67 0a provide working.
349d0 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 ** versions of t
349e0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 69 hese routines, i
349f0 74 20 73 68 6f 75 6c 64 20 61 74 20 6c 65 61 73 t should at leas
34a00 74 20 70 72 6f 76 69 64 65 20 73 74 75 62 73 20 t provide stubs
34a10 74 68 61 74 20 61 6c 77 61 79 73 0a 2a 2a 20 72 that always.** r
34a20 65 74 75 72 6e 20 74 72 75 65 20 73 6f 20 74 68 eturn true so th
34a30 61 74 20 6f 6e 65 20 64 6f 65 73 20 6e 6f 74 20 at one does not
34a40 67 65 74 20 73 70 75 72 69 6f 75 73 20 61 73 73 get spurious ass
34a50 65 72 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 2e ertion failures.
34a60 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 38 35 7d 20 .**.** {H17085}
34a70 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 If the argument
34a80 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 to sqlite3_mutex
34a90 5f 68 65 6c 64 28 29 20 69 73 20 61 20 4e 55 4c _held() is a NUL
34aa0 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a L pointer then.*
34ab0 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 73 68 * the routine sh
34ac0 6f 75 6c 64 20 72 65 74 75 72 6e 20 31 2e 20 20 ould return 1.
34ad0 7b 45 4e 44 7d 20 54 68 69 73 20 73 65 65 6d 73 {END} This seems
34ae0 20 63 6f 75 6e 74 65 72 2d 69 6e 74 75 69 74 69 counter-intuiti
34af0 76 65 20 73 69 6e 63 65 0a 2a 2a 20 63 6c 65 61 ve since.** clea
34b00 72 6c 79 20 74 68 65 20 6d 75 74 65 78 20 63 61 rly the mutex ca
34b10 6e 6e 6f 74 20 62 65 20 68 65 6c 64 20 69 66 20 nnot be held if
34b20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 it does not exis
34b30 74 2e 20 20 42 75 74 20 74 68 65 0a 2a 2a 20 74 t. But the.** t
34b40 68 65 20 72 65 61 73 6f 6e 20 74 68 65 20 6d 75 he reason the mu
34b50 74 65 78 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 tex does not exi
34b60 73 74 20 69 73 20 62 65 63 61 75 73 65 20 74 68 st is because th
34b70 65 20 62 75 69 6c 64 20 69 73 20 6e 6f 74 0a 2a e build is not.*
34b80 2a 20 75 73 69 6e 67 20 6d 75 74 65 78 65 73 2e * using mutexes.
34b90 20 20 41 6e 64 20 77 65 20 64 6f 20 6e 6f 74 20 And we do not
34ba0 77 61 6e 74 20 74 68 65 20 61 73 73 65 72 74 28 want the assert(
34bb0 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 ) containing the
34bc0 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 .** call to sqli
34bd0 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 te3_mutex_held()
34be0 20 74 6f 20 66 61 69 6c 2c 20 73 6f 20 61 20 6e to fail, so a n
34bf0 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20 69 on-zero return i
34c00 73 0a 2a 2a 20 74 68 65 20 61 70 70 72 6f 70 72 s.** the appropr
34c10 69 61 74 65 20 74 68 69 6e 67 20 74 6f 20 64 6f iate thing to do
34c20 2e 20 20 7b 48 31 37 30 38 36 7d 20 54 68 65 20 . {H17086} The
34c30 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f sqlite3_mutex_no
34c40 74 68 65 6c 64 28 29 0a 2a 2a 20 69 6e 74 65 72 theld().** inter
34c50 66 61 63 65 20 73 68 6f 75 6c 64 20 61 6c 73 6f face should also
34c60 20 72 65 74 75 72 6e 20 31 20 77 68 65 6e 20 67 return 1 when g
34c70 69 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e iven a NULL poin
34c80 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ter..*/.int sqli
34c90 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 73 te3_mutex_held(s
34ca0 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a qlite3_mutex*);.
34cb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 int sqlite3_mute
34cc0 78 5f 6e 6f 74 68 65 6c 64 28 73 71 6c 69 74 65 x_notheld(sqlite
34cd0 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 3_mutex*);../*.*
34ce0 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 * CAPI3REF: Mute
34cf0 78 20 54 79 70 65 73 20 7b 48 31 37 30 30 31 7d x Types {H17001}
34d00 20 3c 48 31 37 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 <H17000>.**.**
34d10 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 The [sqlite3_mut
34d20 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 69 6e 74 65 ex_alloc()] inte
34d30 72 66 61 63 65 20 74 61 6b 65 73 20 61 20 73 69 rface takes a si
34d40 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a ngle argument.**
34d50 20 77 68 69 63 68 20 69 73 20 6f 6e 65 20 6f 66 which is one of
34d60 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 these integer c
34d70 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 onstants..**.**
34d80 54 68 65 20 73 65 74 20 6f 66 20 73 74 61 74 69 The set of stati
34d90 63 20 6d 75 74 65 78 65 73 20 6d 61 79 20 63 68 c mutexes may ch
34da0 61 6e 67 65 20 66 72 6f 6d 20 6f 6e 65 20 53 51 ange from one SQ
34db0 4c 69 74 65 20 72 65 6c 65 61 73 65 20 74 6f 20 Lite release to
34dc0 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 the.** next. Ap
34dd0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 plications that
34de0 6f 76 65 72 72 69 64 65 20 74 68 65 20 62 75 69 override the bui
34df0 6c 74 2d 69 6e 20 6d 75 74 65 78 20 6c 6f 67 69 lt-in mutex logi
34e00 63 20 6d 75 73 74 20 62 65 0a 2a 2a 20 70 72 65 c must be.** pre
34e10 70 61 72 65 64 20 74 6f 20 61 63 63 6f 6d 6d 6f pared to accommo
34e20 64 61 74 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 date additional
34e30 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e 0a static mutexes..
34e40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
34e50 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 20 20 20 E_MUTEX_FAST
34e60 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 0.#defi
34e70 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f ne SQLITE_MUTEX_
34e80 52 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20 RECURSIVE
34e90 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 1.#define SQLIT
34ea0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d E_MUTEX_STATIC_M
34eb0 41 53 54 45 52 20 20 20 20 32 0a 23 64 65 66 69 ASTER 2.#defi
34ec0 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f ne SQLITE_MUTEX_
34ed0 53 54 41 54 49 43 5f 4d 45 4d 20 20 20 20 20 20 STATIC_MEM
34ee0 20 33 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 3 /* sqlite3_m
34ef0 61 6c 6c 6f 63 28 29 20 2a 2f 0a 23 64 65 66 69 alloc() */.#defi
34f00 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f ne SQLITE_MUTEX_
34f10 53 54 41 54 49 43 5f 4d 45 4d 32 20 20 20 20 20 STATIC_MEM2
34f20 20 34 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 20 4 /* NOT USED
34f30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
34f40 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4f E_MUTEX_STATIC_O
34f50 50 45 4e 20 20 20 20 20 20 34 20 20 2f 2a 20 73 PEN 4 /* s
34f60 71 6c 69 74 65 33 42 74 72 65 65 4f 70 65 6e 28 qlite3BtreeOpen(
34f70 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
34f80 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 ITE_MUTEX_STATIC
34f90 5f 50 52 4e 47 20 20 20 20 20 20 35 20 20 2f 2a _PRNG 5 /*
34fa0 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 28 sqlite3_random(
34fb0 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
34fc0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 ITE_MUTEX_STATIC
34fd0 5f 4c 52 55 20 20 20 20 20 20 20 36 20 20 2f 2a _LRU 6 /*
34fe0 20 6c 72 75 20 70 61 67 65 20 6c 69 73 74 20 2a lru page list *
34ff0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
35000 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 _MUTEX_STATIC_LR
35010 55 32 20 20 20 20 20 20 37 20 20 2f 2a 20 6c 72 U2 7 /* lr
35020 75 20 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a 0a u page list */..
35030 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
35040 52 65 74 72 69 65 76 65 20 74 68 65 20 6d 75 74 Retrieve the mut
35050 65 78 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 ex for a databas
35060 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 e connection {H1
35070 37 30 30 32 7d 20 3c 48 31 37 30 30 30 3e 0a 2a 7002} <H17000>.*
35080 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 *.** This interf
35090 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f ace returns a po
350a0 69 6e 74 65 72 20 74 68 65 20 5b 73 71 6c 69 74 inter the [sqlit
350b0 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 e3_mutex] object
350c0 20 74 68 61 74 20 0a 2a 2a 20 73 65 72 69 61 6c that .** serial
350d0 69 7a 65 73 20 61 63 63 65 73 73 20 74 6f 20 74 izes access to t
350e0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
350f0 6e 65 63 74 69 6f 6e 5d 20 67 69 76 65 6e 20 69 nection] given i
35100 6e 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a n the argument.*
35110 2a 20 77 68 65 6e 20 74 68 65 20 5b 74 68 72 65 * when the [thre
35120 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 53 ading mode] is S
35130 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 49 66 erialized..** If
35140 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 the [threading
35150 6d 6f 64 65 5d 20 69 73 20 53 69 6e 67 6c 65 2d mode] is Single-
35160 74 68 72 65 61 64 20 6f 72 20 4d 75 6c 74 69 2d thread or Multi-
35170 74 68 72 65 61 64 20 74 68 65 6e 20 74 68 69 73 thread then this
35180 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 .** routine retu
35190 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 rns a NULL point
351a0 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d er..*/.sqlite3_m
351b0 75 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 64 62 utex *sqlite3_db
351c0 5f 6d 75 74 65 78 28 73 71 6c 69 74 65 33 2a 29 _mutex(sqlite3*)
351d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
351e0 46 3a 20 4c 6f 77 2d 4c 65 76 65 6c 20 43 6f 6e F: Low-Level Con
351f0 74 72 6f 6c 20 4f 66 20 44 61 74 61 62 61 73 65 trol Of Database
35200 20 46 69 6c 65 73 20 7b 48 31 31 33 30 30 7d 20 Files {H11300}
35210 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 7b <S30800>.**.** {
35220 48 31 31 33 30 31 7d 20 54 68 65 20 5b 73 71 6c H11301} The [sql
35230 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
35240 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 6d l()] interface m
35250 61 6b 65 73 20 61 20 64 69 72 65 63 74 20 63 61 akes a direct ca
35260 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 78 46 69 ll to the.** xFi
35270 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 leControl method
35280 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 for the [sqlite
35290 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
352a0 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 0a ject associated.
352b0 2a 2a 20 77 69 74 68 20 61 20 70 61 72 74 69 63 ** with a partic
352c0 75 6c 61 72 20 64 61 74 61 62 61 73 65 20 69 64 ular database id
352d0 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 entified by the
352e0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e second argument.
352f0 20 7b 48 31 31 33 30 32 7d 20 54 68 65 0a 2a 2a {H11302} The.**
35300 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 name of the dat
35310 61 62 61 73 65 20 69 73 20 74 68 65 20 6e 61 6d abase is the nam
35320 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 74 68 e assigned to th
35330 65 20 64 61 74 61 62 61 73 65 20 62 79 20 74 68 e database by th
35340 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 6c 61 e.** <a href="la
35350 6e 67 5f 61 74 74 61 63 68 2e 68 74 6d 6c 22 3e ng_attach.html">
35360 41 54 54 41 43 48 3c 2f 61 3e 20 53 51 4c 20 63 ATTACH</a> SQL c
35370 6f 6d 6d 61 6e 64 20 74 68 61 74 20 6f 70 65 6e ommand that open
35380 65 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 ed the.** databa
35390 73 65 2e 20 7b 48 31 31 33 30 33 7d 20 54 6f 20 se. {H11303} To
353a0 63 6f 6e 74 72 6f 6c 20 74 68 65 20 6d 61 69 6e control the main
353b0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 database file,
353c0 75 73 65 20 74 68 65 20 6e 61 6d 65 20 22 6d 61 use the name "ma
353d0 69 6e 22 0a 2a 2a 20 6f 72 20 61 20 4e 55 4c 4c in".** or a NULL
353e0 20 70 6f 69 6e 74 65 72 2e 20 7b 48 31 31 33 30 pointer. {H1130
353f0 34 7d 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 4} The third and
35400 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
35410 72 73 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 rs to this routi
35420 6e 65 0a 2a 2a 20 61 72 65 20 70 61 73 73 65 64 ne.** are passed
35430 20 64 69 72 65 63 74 6c 79 20 74 68 72 6f 75 67 directly throug
35440 68 20 74 6f 20 74 68 65 20 73 65 63 6f 6e 64 20 h to the second
35450 61 6e 64 20 74 68 69 72 64 20 70 61 72 61 6d 65 and third parame
35460 74 65 72 73 20 6f 66 0a 2a 2a 20 74 68 65 20 78 ters of.** the x
35470 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 FileControl meth
35480 6f 64 2e 20 20 7b 48 31 31 33 30 35 7d 20 54 68 od. {H11305} Th
35490 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f e return value o
354a0 66 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 f the xFileContr
354b0 6f 6c 0a 2a 2a 20 6d 65 74 68 6f 64 20 62 65 63 ol.** method bec
354c0 6f 6d 65 73 20 74 68 65 20 72 65 74 75 72 6e 20 omes the return
354d0 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 72 6f value of this ro
354e0 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 utine..**.** {H1
354f0 31 33 30 36 7d 20 49 66 20 74 68 65 20 73 65 63 1306} If the sec
35500 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 7a ond parameter (z
35510 44 62 4e 61 6d 65 29 20 64 6f 65 73 20 6e 6f 74 DbName) does not
35520 20 6d 61 74 63 68 20 74 68 65 20 6e 61 6d 65 20 match the name
35530 6f 66 20 61 6e 79 0a 2a 2a 20 6f 70 65 6e 20 64 of any.** open d
35540 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 74 68 atabase file, th
35550 65 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 en SQLITE_ERROR
35560 69 73 20 72 65 74 75 72 6e 65 64 2e 20 7b 48 31 is returned. {H1
35570 31 33 30 37 7d 20 54 68 69 73 20 65 72 72 6f 72 1307} This error
35580 0a 2a 2a 20 63 6f 64 65 20 69 73 20 6e 6f 74 20 .** code is not
35590 72 65 6d 65 6d 62 65 72 65 64 20 61 6e 64 20 77 remembered and w
355a0 69 6c 6c 20 6e 6f 74 20 62 65 20 72 65 63 61 6c ill not be recal
355b0 6c 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f led by [sqlite3_
355c0 65 72 72 63 6f 64 65 28 29 5d 0a 2a 2a 20 6f 72 errcode()].** or
355d0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
355e0 28 29 5d 2e 20 7b 41 31 31 33 30 38 7d 20 54 68 ()]. {A11308} Th
355f0 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 78 46 69 e underlying xFi
35600 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 leControl method
35610 20 6d 69 67 68 74 0a 2a 2a 20 61 6c 73 6f 20 72 might.** also r
35620 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 45 52 52 eturn SQLITE_ERR
35630 4f 52 2e 20 20 7b 41 31 31 33 30 39 7d 20 54 68 OR. {A11309} Th
35640 65 72 65 20 69 73 20 6e 6f 20 77 61 79 20 74 6f ere is no way to
35650 20 64 69 73 74 69 6e 67 75 69 73 68 20 62 65 74 distinguish bet
35660 77 65 65 6e 0a 2a 2a 20 61 6e 20 69 6e 63 6f 72 ween.** an incor
35670 72 65 63 74 20 7a 44 62 4e 61 6d 65 20 61 6e 64 rect zDbName and
35680 20 61 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 an SQLITE_ERROR
35690 20 72 65 74 75 72 6e 20 66 72 6f 6d 20 74 68 65 return from the
356a0 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 78 underlying.** x
356b0 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 FileControl meth
356c0 6f 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 od. {END}.**.**
356d0 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 See also: [SQLIT
356e0 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 E_FCNTL_LOCKSTAT
356f0 45 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 E].*/.int sqlite
35700 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 73 3_file_control(s
35710 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 qlite3*, const c
35720 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 69 6e har *zDbName, in
35730 74 20 6f 70 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f t op, void*);../
35740 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
35750 65 73 74 69 6e 67 20 49 6e 74 65 72 66 61 63 65 esting Interface
35760 20 7b 48 31 31 34 30 30 7d 20 3c 53 33 30 38 30 {H11400} <S3080
35770 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 0>.**.** The sql
35780 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f ite3_test_contro
35790 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 l() interface is
357a0 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f 75 used to read ou
357b0 74 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 73 74 t internal.** st
357c0 61 74 65 20 6f 66 20 53 51 4c 69 74 65 20 61 6e ate of SQLite an
357d0 64 20 74 6f 20 69 6e 6a 65 63 74 20 66 61 75 6c d to inject faul
357e0 74 73 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 66 ts into SQLite f
357f0 6f 72 20 74 65 73 74 69 6e 67 0a 2a 2a 20 70 75 or testing.** pu
35800 72 70 6f 73 65 73 2e 20 20 54 68 65 20 66 69 72 rposes. The fir
35810 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 st parameter is
35820 61 6e 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 an operation cod
35830 65 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 e that determine
35840 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 2c s.** the number,
35850 20 6d 65 61 6e 69 6e 67 2c 20 61 6e 64 20 6f 70 meaning, and op
35860 65 72 61 74 69 6f 6e 20 6f 66 20 61 6c 6c 20 73 eration of all s
35870 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 ubsequent parame
35880 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 ters..**.** This
35890 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f interface is no
358a0 74 20 66 6f 72 20 75 73 65 20 62 79 20 61 70 70 t for use by app
358b0 6c 69 63 61 74 69 6f 6e 73 2e 20 20 49 74 20 65 lications. It e
358c0 78 69 73 74 73 20 73 6f 6c 65 6c 79 0a 2a 2a 20 xists solely.**
358d0 66 6f 72 20 76 65 72 69 66 79 69 6e 67 20 74 68 for verifying th
358e0 65 20 63 6f 72 72 65 63 74 20 6f 70 65 72 61 74 e correct operat
358f0 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 ion of the SQLit
35900 65 20 6c 69 62 72 61 72 79 2e 20 20 44 65 70 65 e library. Depe
35910 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 68 6f 77 20 nding.** on how
35920 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 the SQLite libra
35930 72 79 20 69 73 20 63 6f 6d 70 69 6c 65 64 2c 20 ry is compiled,
35940 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6d this interface m
35950 69 67 68 74 20 6e 6f 74 20 65 78 69 73 74 2e 0a ight not exist..
35960 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c **.** The detail
35970 73 20 6f 66 20 74 68 65 20 6f 70 65 72 61 74 69 s of the operati
35980 6f 6e 20 63 6f 64 65 73 2c 20 74 68 65 69 72 20 on codes, their
35990 6d 65 61 6e 69 6e 67 73 2c 20 74 68 65 20 70 61 meanings, the pa
359a0 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 68 65 79 rameters.** they
359b0 20 74 61 6b 65 2c 20 61 6e 64 20 77 68 61 74 20 take, and what
359c0 74 68 65 79 20 64 6f 20 61 72 65 20 61 6c 6c 20 they do are all
359d0 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 subject to chang
359e0 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 e without notice
359f0 2e 0a 2a 2a 20 55 6e 6c 69 6b 65 20 6d 6f 73 74 ..** Unlike most
35a00 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 41 of the SQLite A
35a10 50 49 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f PI, this functio
35a20 6e 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 n is not guarant
35a30 65 65 64 20 74 6f 0a 2a 2a 20 6f 70 65 72 61 74 eed to.** operat
35a40 65 20 63 6f 6e 73 69 73 74 65 6e 74 6c 79 20 66 e consistently f
35a50 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 rom one release
35a60 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a to the next..*/.
35a70 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 65 73 74 int sqlite3_test
35a80 5f 63 6f 6e 74 72 6f 6c 28 69 6e 74 20 6f 70 2c _control(int op,
35a90 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ...);../*.** CA
35aa0 50 49 33 52 45 46 3a 20 54 65 73 74 69 6e 67 20 PI3REF: Testing
35ab0 49 6e 74 65 72 66 61 63 65 20 4f 70 65 72 61 74 Interface Operat
35ac0 69 6f 6e 20 43 6f 64 65 73 20 7b 48 31 31 34 31 ion Codes {H1141
35ad0 30 7d 20 3c 48 31 31 34 30 30 3e 0a 2a 2a 0a 2a 0} <H11400>.**.*
35ae0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 * These constant
35af0 73 20 61 72 65 20 74 68 65 20 76 61 6c 69 64 20 s are the valid
35b00 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 65 20 70 operation code p
35b10 61 72 61 6d 65 74 65 72 73 20 75 73 65 64 0a 2a arameters used.*
35b20 2a 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 * as the first a
35b30 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 rgument to [sqli
35b40 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c te3_test_control
35b50 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ()]..**.** These
35b60 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 parameters and
35b70 74 68 65 69 72 20 6d 65 61 6e 69 6e 67 73 20 61 their meanings a
35b80 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 re subject to ch
35b90 61 6e 67 65 0a 2a 2a 20 77 69 74 68 6f 75 74 20 ange.** without
35ba0 6e 6f 74 69 63 65 2e 20 20 54 68 65 73 65 20 76 notice. These v
35bb0 61 6c 75 65 73 20 61 72 65 20 66 6f 72 20 74 65 alues are for te
35bc0 73 74 69 6e 67 20 70 75 72 70 6f 73 65 73 20 6f sting purposes o
35bd0 6e 6c 79 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 nly..** Applicat
35be0 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 ions should not
35bf0 75 73 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 use any of these
35c00 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 74 parameters or t
35c10 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 he.** [sqlite3_t
35c20 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 est_control()] i
35c30 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 nterface..*/.#de
35c40 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 fine SQLITE_TEST
35c50 43 54 52 4c 5f 50 52 4e 47 5f 53 41 56 45 20 20 CTRL_PRNG_SAVE
35c60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 5.
35c70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
35c80 45 53 54 43 54 52 4c 5f 50 52 4e 47 5f 52 45 53 ESTCTRL_PRNG_RES
35c90 54 4f 52 45 20 20 20 20 20 20 20 20 20 20 20 20 TORE
35ca0 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 6.#define SQLIT
35cb0 45 5f 54 45 53 54 43 54 52 4c 5f 50 52 4e 47 5f E_TESTCTRL_PRNG_
35cc0 52 45 53 45 54 20 20 20 20 20 20 20 20 20 20 20 RESET
35cd0 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 7.#define SQ
35ce0 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 42 49 LITE_TESTCTRL_BI
35cf0 54 56 45 43 5f 54 45 53 54 20 20 20 20 20 20 20 TVEC_TEST
35d00 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 8.#define
35d10 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c SQLITE_TESTCTRL
35d20 5f 46 41 55 4c 54 5f 49 4e 53 54 41 4c 4c 20 20 _FAULT_INSTALL
35d30 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 9.#def
35d40 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 ine SQLITE_TESTC
35d50 54 52 4c 5f 42 45 4e 49 47 4e 5f 4d 41 4c 4c 4f TRL_BENIGN_MALLO
35d60 43 5f 48 4f 4f 4b 53 20 20 20 20 20 31 30 0a 23 C_HOOKS 10.#
35d70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 define SQLITE_TE
35d80 53 54 43 54 52 4c 5f 50 45 4e 44 49 4e 47 5f 42 STCTRL_PENDING_B
35d90 59 54 45 20 20 20 20 20 20 20 20 20 20 20 20 31 YTE 1
35da0 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 1../*.** CAPI3RE
35db0 46 3a 20 53 51 4c 69 74 65 20 52 75 6e 74 69 6d F: SQLite Runtim
35dc0 65 20 53 74 61 74 75 73 20 7b 48 31 37 32 30 30 e Status {H17200
35dd0 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 45 58 } <S60200>.** EX
35de0 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a PERIMENTAL.**.**
35df0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 This interface
35e00 69 73 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 is used to retri
35e10 65 76 65 20 72 75 6e 74 69 6d 65 20 73 74 61 74 eve runtime stat
35e20 75 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a us information.*
35e30 2a 20 61 62 6f 75 74 20 74 68 65 20 70 72 65 66 * about the pref
35e40 6f 72 6d 61 6e 63 65 20 6f 66 20 53 51 4c 69 74 ormance of SQLit
35e50 65 2c 20 61 6e 64 20 6f 70 74 69 6f 6e 61 6c 6c e, and optionall
35e60 79 20 74 6f 20 72 65 73 65 74 20 76 61 72 69 6f y to reset vario
35e70 75 73 0a 2a 2a 20 68 69 67 68 77 61 74 65 72 20 us.** highwater
35e80 6d 61 72 6b 73 2e 20 20 54 68 65 20 66 69 72 73 marks. The firs
35e90 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e t argument is an
35ea0 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 66 6f integer code fo
35eb0 72 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 66 69 r.** the specifi
35ec0 63 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 6d c parameter to m
35ed0 65 61 73 75 72 65 2e 20 20 52 65 63 6f 67 6e 69 easure. Recogni
35ee0 7a 65 64 20 69 6e 74 65 67 65 72 20 63 6f 64 65 zed integer code
35ef0 73 0a 2a 2a 20 61 72 65 20 6f 66 20 74 68 65 20 s.** are of the
35f00 66 6f 72 6d 20 5b 53 51 4c 49 54 45 5f 53 54 41 form [SQLITE_STA
35f10 54 55 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 20 TUS_MEMORY_USED
35f20 7c 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f | SQLITE_STATUS_
35f30 2e 2e 2e 5d 2e 0a 2a 2a 20 54 68 65 20 63 75 72 ...]..** The cur
35f40 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 74 68 rent value of th
35f50 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 72 e parameter is r
35f60 65 74 75 72 6e 65 64 20 69 6e 74 6f 20 2a 70 43 eturned into *pC
35f70 75 72 72 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 68 urrent..** The h
35f80 69 67 68 65 73 74 20 72 65 63 6f 72 64 65 64 20 ighest recorded
35f90 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 value is returne
35fa0 64 20 69 6e 20 2a 70 48 69 67 68 77 61 74 65 72 d in *pHighwater
35fb0 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 72 65 73 . If the.** res
35fc0 65 74 46 6c 61 67 20 69 73 20 74 72 75 65 2c 20 etFlag is true,
35fd0 74 68 65 6e 20 74 68 65 20 68 69 67 68 65 73 74 then the highest
35fe0 20 72 65 63 6f 72 64 20 76 61 6c 75 65 20 69 73 record value is
35ff0 20 72 65 73 65 74 20 61 66 74 65 72 0a 2a 2a 20 reset after.**
36000 2a 70 48 69 67 68 77 61 74 65 72 20 69 73 20 77 *pHighwater is w
36010 72 69 74 74 65 6e 2e 20 53 6f 6d 65 20 70 61 72 ritten. Some par
36020 61 6d 65 74 65 72 73 20 64 6f 20 6e 6f 74 20 72 ameters do not r
36030 65 63 6f 72 64 20 74 68 65 20 68 69 67 68 65 73 ecord the highes
36040 74 0a 2a 2a 20 76 61 6c 75 65 2e 20 20 46 6f 72 t.** value. For
36050 20 74 68 6f 73 65 20 70 61 72 61 6d 65 74 65 72 those parameter
36060 73 0a 2a 2a 20 6e 6f 74 68 69 6e 67 20 69 73 20 s.** nothing is
36070 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 48 written into *pH
36080 69 67 68 77 61 74 65 72 20 61 6e 64 20 74 68 65 ighwater and the
36090 20 72 65 73 65 74 46 6c 61 67 20 69 73 20 69 67 resetFlag is ig
360a0 6e 6f 72 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 20 nored..** Other
360b0 70 61 72 61 6d 65 74 65 72 73 20 72 65 63 6f 72 parameters recor
360c0 64 20 6f 6e 6c 79 20 74 68 65 20 68 69 67 68 77 d only the highw
360d0 61 74 65 72 20 6d 61 72 6b 20 61 6e 64 20 6e 6f ater mark and no
360e0 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a t the current.**
360f0 20 76 61 6c 75 65 2e 20 20 46 6f 72 20 74 68 65 value. For the
36100 73 65 20 6c 61 74 74 65 72 20 70 61 72 61 6d 65 se latter parame
36110 74 65 72 73 20 6e 6f 74 68 69 6e 67 20 69 73 20 ters nothing is
36120 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 43 written into *pC
36130 75 72 72 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 urrent..**.** Th
36140 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 is routine retur
36150 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 20 6f 6e 20 ns SQLITE_OK on
36160 73 75 63 63 65 73 73 20 61 6e 64 20 61 20 6e 6f success and a no
36170 6e 2d 7a 65 72 6f 0a 2a 2a 20 5b 65 72 72 6f 72 n-zero.** [error
36180 20 63 6f 64 65 5d 20 6f 6e 20 66 61 69 6c 75 72 code] on failur
36190 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f e..**.** This ro
361a0 75 74 69 6e 65 20 69 73 20 74 68 72 65 61 64 73 utine is threads
361b0 61 66 65 20 62 75 74 20 69 73 20 6e 6f 74 20 61 afe but is not a
361c0 74 6f 6d 69 63 2e 20 20 54 68 69 73 20 72 6f 75 tomic. This rou
361d0 74 69 6e 65 20 63 61 6e 0a 2a 2a 20 63 61 6c 6c tine can.** call
361e0 65 64 20 77 68 69 6c 65 20 6f 74 68 65 72 20 74 ed while other t
361f0 68 72 65 61 64 73 20 61 72 65 20 72 75 6e 6e 69 hreads are runni
36200 6e 67 20 74 68 65 20 73 61 6d 65 20 6f 72 20 64 ng the same or d
36210 69 66 66 65 72 65 6e 74 20 53 51 4c 69 74 65 0a ifferent SQLite.
36220 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 ** interfaces.
36230 48 6f 77 65 76 65 72 20 74 68 65 20 76 61 6c 75 However the valu
36240 65 73 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a es returned in *
36250 70 43 75 72 72 65 6e 74 20 61 6e 64 0a 2a 2a 20 pCurrent and.**
36260 2a 70 48 69 67 68 77 61 74 65 72 20 72 65 66 6c *pHighwater refl
36270 65 63 74 20 74 68 65 20 73 74 61 74 75 73 20 6f ect the status o
36280 66 20 53 51 4c 69 74 65 20 61 74 20 64 69 66 66 f SQLite at diff
36290 65 72 65 6e 74 20 70 6f 69 6e 74 73 20 69 6e 20 erent points in
362a0 74 69 6d 65 0a 2a 2a 20 61 6e 64 20 69 74 20 69 time.** and it i
362b0 73 20 70 6f 73 73 69 62 6c 65 20 74 68 61 74 20 s possible that
362c0 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 6d another thread m
362d0 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 ight change the
362e0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 20 parameter.** in
362f0 62 65 74 77 65 65 6e 20 74 68 65 20 74 69 6d 65 between the time
36300 73 20 77 68 65 6e 20 2a 70 43 75 72 72 65 6e 74 s when *pCurrent
36310 20 61 6e 64 20 2a 70 48 69 67 68 77 61 74 65 72 and *pHighwater
36320 20 61 72 65 20 77 72 69 74 74 65 6e 2e 0a 2a 2a are written..**
36330 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
36340 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 qlite3_db_status
36350 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 ()].*/.SQLITE_EX
36360 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 PERIMENTAL int s
36370 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 69 6e qlite3_status(in
36380 74 20 6f 70 2c 20 69 6e 74 20 2a 70 43 75 72 72 t op, int *pCurr
36390 65 6e 74 2c 20 69 6e 74 20 2a 70 48 69 67 68 77 ent, int *pHighw
363a0 61 74 65 72 2c 20 69 6e 74 20 72 65 73 65 74 46 ater, int resetF
363b0 6c 61 67 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 lag);.../*.** CA
363c0 50 49 33 52 45 46 3a 20 53 74 61 74 75 73 20 50 PI3REF: Status P
363d0 61 72 61 6d 65 74 65 72 73 20 7b 48 31 37 32 35 arameters {H1725
363e0 30 7d 20 3c 48 31 37 32 30 30 3e 0a 2a 2a 20 45 0} <H17200>.** E
363f0 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a XPERIMENTAL.**.*
36400 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 * These integer
36410 63 6f 6e 73 74 61 6e 74 73 20 64 65 73 69 67 6e constants design
36420 61 74 65 20 76 61 72 69 6f 75 73 20 72 75 6e 2d ate various run-
36430 74 69 6d 65 20 73 74 61 74 75 73 20 70 61 72 61 time status para
36440 6d 65 74 65 72 73 0a 2a 2a 20 74 68 61 74 20 63 meters.** that c
36450 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 62 an be returned b
36460 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 y [sqlite3_statu
36470 73 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e s()]..**.** <dl>
36480 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 .** <dt>SQLITE_S
36490 54 41 54 55 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 TATUS_MEMORY_USE
364a0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 D</dt>.** <dd>Th
364b0 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 is parameter is
364c0 74 68 65 20 63 75 72 72 65 6e 74 20 61 6d 6f 75 the current amou
364d0 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 20 63 68 65 nt of memory che
364e0 63 6b 65 64 20 6f 75 74 0a 2a 2a 20 75 73 69 6e cked out.** usin
364f0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f g [sqlite3_mallo
36500 63 28 29 5d 2c 20 65 69 74 68 65 72 20 64 69 72 c()], either dir
36510 65 63 74 6c 79 20 6f 72 20 69 6e 64 69 72 65 63 ectly or indirec
36520 74 6c 79 2e 20 20 54 68 65 0a 2a 2a 20 66 69 67 tly. The.** fig
36530 75 72 65 20 69 6e 63 6c 75 64 65 73 20 63 61 6c ure includes cal
36540 6c 73 20 6d 61 64 65 20 74 6f 20 5b 73 71 6c 69 ls made to [sqli
36550 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 79 te3_malloc()] by
36560 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
36570 0a 2a 2a 20 61 6e 64 20 69 6e 74 65 72 6e 61 6c .** and internal
36580 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 20 62 79 memory usage by
36590 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 the SQLite libr
365a0 61 72 79 2e 20 20 53 63 72 61 74 63 68 20 6d 65 ary. Scratch me
365b0 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 6c mory.** controll
365c0 65 64 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f ed by [SQLITE_CO
365d0 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e NFIG_SCRATCH] an
365e0 64 20 61 75 78 69 6c 69 61 72 79 20 70 61 67 65 d auxiliary page
365f0 2d 63 61 63 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 -cache.** memory
36600 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 5b controlled by [
36610 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 SQLITE_CONFIG_PA
36620 47 45 43 41 43 48 45 5d 20 69 73 20 6e 6f 74 20 GECACHE] is not
36630 69 6e 63 6c 75 64 65 64 20 69 6e 0a 2a 2a 20 74 included in.** t
36640 68 69 73 20 70 61 72 61 6d 65 74 65 72 2e 20 20 his parameter.
36650 54 68 65 20 61 6d 6f 75 6e 74 20 72 65 74 75 72 The amount retur
36660 6e 65 64 20 69 73 20 74 68 65 20 73 75 6d 20 6f ned is the sum o
36670 66 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e f the allocation
36680 0a 2a 2a 20 73 69 7a 65 73 20 61 73 20 72 65 70 .** sizes as rep
36690 6f 72 74 65 64 20 62 79 20 74 68 65 20 78 53 69 orted by the xSi
366a0 7a 65 20 6d 65 74 68 6f 64 20 69 6e 20 5b 73 71 ze method in [sq
366b0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
366c0 73 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c s].</dd>.**.** <
366d0 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 dt>SQLITE_STATUS
366e0 5f 4d 41 4c 4c 4f 43 5f 53 49 5a 45 3c 2f 64 74 _MALLOC_SIZE</dt
366f0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 >.** <dd>This pa
36700 72 61 6d 65 74 65 72 20 72 65 63 6f 72 64 73 20 rameter records
36710 74 68 65 20 6c 61 72 67 65 73 74 20 6d 65 6d 6f the largest memo
36720 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 ry allocation re
36730 71 75 65 73 74 0a 2a 2a 20 68 61 6e 64 65 64 20 quest.** handed
36740 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c to [sqlite3_mall
36750 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 oc()] or [sqlite
36760 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 28 6f 72 3_realloc()] (or
36770 20 74 68 65 69 72 0a 2a 2a 20 69 6e 74 65 72 6e their.** intern
36780 61 6c 20 65 71 75 69 76 61 6c 65 6e 74 73 29 2e al equivalents).
36790 20 20 4f 6e 6c 79 20 74 68 65 20 76 61 6c 75 65 Only the value
367a0 20 72 65 74 75 72 6e 65 64 20 69 6e 20 74 68 65 returned in the
367b0 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74 65 72 20 .** *pHighwater
367c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 parameter to [sq
367d0 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 20 lite3_status()]
367e0 69 73 20 6f 66 20 69 6e 74 65 72 65 73 74 2e 20 is of interest.
367f0 20 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 77 .** The value w
36800 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 ritten into the
36810 2a 70 43 75 72 72 65 6e 74 20 70 61 72 61 6d 65 *pCurrent parame
36820 74 65 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ter is undefined
36830 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
36840 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 >SQLITE_STATUS_P
36850 41 47 45 43 41 43 48 45 5f 55 53 45 44 3c 2f 64 AGECACHE_USED</d
36860 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 t>.** <dd>This p
36870 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 arameter returns
36880 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 the number of p
36890 61 67 65 73 20 75 73 65 64 20 6f 75 74 20 6f 66 ages used out of
368a0 20 74 68 65 0a 2a 2a 20 5b 70 61 67 65 63 61 63 the.** [pagecac
368b0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
368c0 74 6f 72 5d 20 74 68 61 74 20 77 61 73 20 63 6f tor] that was co
368d0 6e 66 69 67 75 72 65 64 20 75 73 69 6e 67 20 0a nfigured using .
368e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ** [SQLITE_CONFI
368f0 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 20 20 54 G_PAGECACHE]. T
36900 68 65 0a 2a 2a 20 76 61 6c 75 65 20 72 65 74 75 he.** value retu
36910 72 6e 65 64 20 69 73 20 69 6e 20 70 61 67 65 73 rned is in pages
36920 2c 20 6e 6f 74 20 69 6e 20 62 79 74 65 73 2e 3c , not in bytes.<
36930 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
36940 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 QLITE_STATUS_PAG
36950 45 43 41 43 48 45 5f 4f 56 45 52 46 4c 4f 57 3c ECACHE_OVERFLOW<
36960 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 /dt>.** <dd>This
36970 20 70 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 parameter retur
36980 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
36990 20 62 79 74 65 73 20 6f 66 20 70 61 67 65 20 63 bytes of page c
369a0 61 63 68 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 ache.** allocati
369b0 6f 6e 20 77 68 69 63 68 20 63 6f 75 6c 64 20 6e on which could n
369c0 6f 74 20 62 65 20 73 74 61 74 69 73 66 69 65 64 ot be statisfied
369d0 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f by the [SQLITE_
369e0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 CONFIG_PAGECACHE
369f0 5d 0a 2a 2a 20 62 75 66 66 65 72 20 61 6e 64 20 ].** buffer and
36a00 77 68 65 72 65 20 66 6f 72 63 65 64 20 74 6f 20 where forced to
36a10 6f 76 65 72 66 6c 6f 77 20 74 6f 20 5b 73 71 6c overflow to [sql
36a20 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 ite3_malloc()].
36a30 20 54 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 The.** returned
36a40 20 76 61 6c 75 65 20 69 6e 63 6c 75 64 65 73 20 value includes
36a50 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 74 68 61 74 allocations that
36a60 20 6f 76 65 72 66 6c 6f 77 65 64 20 62 65 63 61 overflowed beca
36a70 75 73 65 20 74 68 65 79 0a 2a 2a 20 77 68 65 72 use they.** wher
36a80 65 20 74 6f 6f 20 6c 61 72 67 65 20 28 74 68 65 e too large (the
36a90 79 20 77 65 72 65 20 6c 61 72 67 65 72 20 74 68 y were larger th
36aa0 61 6e 20 74 68 65 20 22 73 7a 22 20 70 61 72 61 an the "sz" para
36ab0 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c meter to.** [SQL
36ac0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 ITE_CONFIG_PAGEC
36ad0 41 43 48 45 5d 29 20 61 6e 64 20 61 6c 6c 6f 63 ACHE]) and alloc
36ae0 61 74 69 6f 6e 73 20 74 68 61 74 20 6f 76 65 72 ations that over
36af0 66 6c 6f 77 65 64 20 62 65 63 61 75 73 65 0a 2a flowed because.*
36b00 2a 20 6e 6f 20 73 70 61 63 65 20 77 61 73 20 6c * no space was l
36b10 65 66 74 20 69 6e 20 74 68 65 20 70 61 67 65 20 eft in the page
36b20 63 61 63 68 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a cache.</dd>.**.*
36b30 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 * <dt>SQLITE_STA
36b40 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f 53 49 TUS_PAGECACHE_SI
36b50 5a 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 ZE</dt>.** <dd>T
36b60 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 his parameter re
36b70 63 6f 72 64 73 20 74 68 65 20 6c 61 72 67 65 73 cords the larges
36b80 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 t memory allocat
36b90 69 6f 6e 20 72 65 71 75 65 73 74 0a 2a 2a 20 68 ion request.** h
36ba0 61 6e 64 65 64 20 74 6f 20 5b 70 61 67 65 63 61 anded to [pageca
36bb0 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 che memory alloc
36bc0 61 74 6f 72 5d 2e 20 20 4f 6e 6c 79 20 74 68 65 ator]. Only the
36bd0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
36be0 69 6e 20 74 68 65 0a 2a 2a 20 2a 70 48 69 67 68 in the.** *pHigh
36bf0 77 61 74 65 72 20 70 61 72 61 6d 65 74 65 72 20 water parameter
36c00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 to [sqlite3_stat
36c10 75 73 28 29 5d 20 69 73 20 6f 66 20 69 6e 74 65 us()] is of inte
36c20 72 65 73 74 2e 20 20 0a 2a 2a 20 54 68 65 20 76 rest. .** The v
36c30 61 6c 75 65 20 77 72 69 74 74 65 6e 20 69 6e 74 alue written int
36c40 6f 20 74 68 65 20 2a 70 43 75 72 72 65 6e 74 20 o the *pCurrent
36c50 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 6e 64 parameter is und
36c60 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a efined.</dd>.**.
36c70 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 ** <dt>SQLITE_ST
36c80 41 54 55 53 5f 53 43 52 41 54 43 48 5f 55 53 45 ATUS_SCRATCH_USE
36c90 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 D</dt>.** <dd>Th
36ca0 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 74 is parameter ret
36cb0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
36cc0 6f 66 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 75 of allocations u
36cd0 73 65 64 20 6f 75 74 20 6f 66 20 74 68 65 0a 2a sed out of the.*
36ce0 2a 20 5b 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 * [scratch memor
36cf0 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e y allocator] con
36d00 66 69 67 75 72 65 64 20 75 73 69 6e 67 0a 2a 2a figured using.**
36d10 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
36d20 53 43 52 41 54 43 48 5d 2e 20 20 54 68 65 20 76 SCRATCH]. The v
36d30 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 alue returned is
36d40 20 69 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c in allocations,
36d50 20 6e 6f 74 0a 2a 2a 20 69 6e 20 62 79 74 65 73 not.** in bytes
36d60 2e 20 20 53 69 6e 63 65 20 61 20 73 69 6e 67 6c . Since a singl
36d70 65 20 74 68 72 65 61 64 20 6d 61 79 20 6f 6e 6c e thread may onl
36d80 79 20 68 61 76 65 20 6f 6e 65 20 73 63 72 61 74 y have one scrat
36d90 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a ch allocation.**
36da0 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 61 74 20 outstanding at
36db0 74 69 6d 65 2c 20 74 68 69 73 20 70 61 72 61 6d time, this param
36dc0 65 74 65 72 20 61 6c 73 6f 20 72 65 70 6f 72 74 eter also report
36dd0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
36de0 74 68 72 65 61 64 73 0a 2a 2a 20 75 73 69 6e 67 threads.** using
36df0 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 scratch memory
36e00 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 at the same time
36e10 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
36e20 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 >SQLITE_STATUS_S
36e30 43 52 41 54 43 48 5f 4f 56 45 52 46 4c 4f 57 3c CRATCH_OVERFLOW<
36e40 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 /dt>.** <dd>This
36e50 20 70 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 parameter retur
36e60 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
36e70 20 62 79 74 65 73 20 6f 66 20 73 63 72 61 74 63 bytes of scratc
36e80 68 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f h memory.** allo
36e90 63 61 74 69 6f 6e 20 77 68 69 63 68 20 63 6f 75 cation which cou
36ea0 6c 64 20 6e 6f 74 20 62 65 20 73 74 61 74 69 73 ld not be statis
36eb0 66 69 65 64 20 62 79 20 74 68 65 20 5b 53 51 4c fied by the [SQL
36ec0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 ITE_CONFIG_SCRAT
36ed0 43 48 5d 0a 2a 2a 20 62 75 66 66 65 72 20 61 6e CH].** buffer an
36ee0 64 20 77 68 65 72 65 20 66 6f 72 63 65 64 20 74 d where forced t
36ef0 6f 20 6f 76 65 72 66 6c 6f 77 20 74 6f 20 5b 73 o overflow to [s
36f00 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
36f10 2e 20 20 54 68 65 20 76 61 6c 75 65 73 0a 2a 2a . The values.**
36f20 20 72 65 74 75 72 6e 65 64 20 69 6e 63 6c 75 64 returned includ
36f30 65 20 6f 76 65 72 66 6c 6f 77 73 20 62 65 63 61 e overflows beca
36f40 75 73 65 20 74 68 65 20 72 65 71 75 65 73 74 65 use the requeste
36f50 64 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 77 61 73 d allocation was
36f60 20 74 6f 6f 0a 2a 2a 20 6c 61 72 67 65 72 20 28 too.** larger (
36f70 74 68 61 74 20 69 73 2c 20 62 65 63 61 75 73 65 that is, because
36f80 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 61 the requested a
36f90 6c 6c 6f 63 61 74 69 6f 6e 20 77 61 73 20 6c 61 llocation was la
36fa0 72 67 65 72 20 74 68 61 6e 20 74 68 65 0a 2a 2a rger than the.**
36fb0 20 22 73 7a 22 20 70 61 72 61 6d 65 74 65 72 20 "sz" parameter
36fc0 74 6f 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 to [SQLITE_CONFI
36fd0 47 5f 53 43 52 41 54 43 48 5d 29 20 61 6e 64 20 G_SCRATCH]) and
36fe0 62 65 63 61 75 73 65 20 6e 6f 20 73 63 72 61 74 because no scrat
36ff0 63 68 20 62 75 66 66 65 72 0a 2a 2a 20 73 6c 6f ch buffer.** slo
37000 74 73 20 77 65 72 65 20 61 76 61 69 6c 61 62 6c ts were availabl
37010 65 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a e..** </dd>.**.*
37020 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 * <dt>SQLITE_STA
37030 54 55 53 5f 53 43 52 41 54 43 48 5f 53 49 5a 45 TUS_SCRATCH_SIZE
37040 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 </dt>.** <dd>Thi
37050 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 63 6f s parameter reco
37060 72 64 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 rds the largest
37070 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
37080 6e 20 72 65 71 75 65 73 74 0a 2a 2a 20 68 61 6e n request.** han
37090 64 65 64 20 74 6f 20 5b 73 63 72 61 74 63 68 20 ded to [scratch
370a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
370b0 5d 2e 20 20 4f 6e 6c 79 20 74 68 65 20 76 61 6c ]. Only the val
370c0 75 65 20 72 65 74 75 72 6e 65 64 20 69 6e 20 74 ue returned in t
370d0 68 65 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74 65 he.** *pHighwate
370e0 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b r parameter to [
370f0 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 sqlite3_status()
37100 5d 20 69 73 20 6f 66 20 69 6e 74 65 72 65 73 74 ] is of interest
37110 2e 20 20 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 . .** The value
37120 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 written into th
37130 65 20 2a 70 43 75 72 72 65 6e 74 20 70 61 72 61 e *pCurrent para
37140 6d 65 74 65 72 20 69 73 20 75 6e 64 65 66 69 6e meter is undefin
37150 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c ed.</dd>.**.** <
37160 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 dt>SQLITE_STATUS
37170 5f 50 41 52 53 45 52 5f 53 54 41 43 4b 3c 2f 64 _PARSER_STACK</d
37180 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 t>.** <dd>This p
37190 61 72 61 6d 65 74 65 72 20 72 65 63 6f 72 64 73 arameter records
371a0 20 74 68 65 20 64 65 65 70 65 73 74 20 70 61 72 the deepest par
371b0 73 65 72 20 73 74 61 63 6b 2e 20 20 49 74 20 69 ser stack. It i
371c0 73 20 6f 6e 6c 79 0a 2a 2a 20 6d 65 61 6e 69 6e s only.** meanin
371d0 67 66 75 6c 20 69 66 20 53 51 4c 69 74 65 20 69 gful if SQLite i
371e0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 s compiled with
371f0 5b 59 59 54 52 41 43 4b 4d 41 58 53 54 41 43 4b [YYTRACKMAXSTACK
37200 44 45 50 54 48 5d 2e 3c 2f 64 64 3e 0a 2a 2a 20 DEPTH].</dd>.**
37210 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 </dl>.**.** New
37220 73 74 61 74 75 73 20 70 61 72 61 6d 65 74 65 72 status parameter
37230 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 66 s may be added f
37240 72 6f 6d 20 74 69 6d 65 20 74 6f 20 74 69 6d 65 rom time to time
37250 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
37260 49 54 45 5f 53 54 41 54 55 53 5f 4d 45 4d 4f 52 ITE_STATUS_MEMOR
37270 59 5f 55 53 45 44 20 20 20 20 20 20 20 20 20 20 Y_USED
37280 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
37290 5f 53 54 41 54 55 53 5f 50 41 47 45 43 41 43 48 _STATUS_PAGECACH
372a0 45 5f 55 53 45 44 20 20 20 20 20 20 20 31 0a 23 E_USED 1.#
372b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 define SQLITE_ST
372c0 41 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f 4f ATUS_PAGECACHE_O
372d0 56 45 52 46 4c 4f 57 20 20 20 32 0a 23 64 65 66 VERFLOW 2.#def
372e0 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 ine SQLITE_STATU
372f0 53 5f 53 43 52 41 54 43 48 5f 55 53 45 44 20 20 S_SCRATCH_USED
37300 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 3.#define
37310 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 SQLITE_STATUS_S
37320 43 52 41 54 43 48 5f 4f 56 45 52 46 4c 4f 57 20 CRATCH_OVERFLOW
37330 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4.#define SQ
37340 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 41 4c 4c LITE_STATUS_MALL
37350 4f 43 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 OC_SIZE
37360 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 5.#define SQLIT
37370 45 5f 53 54 41 54 55 53 5f 50 41 52 53 45 52 5f E_STATUS_PARSER_
37380 53 54 41 43 4b 20 20 20 20 20 20 20 20 20 36 0a STACK 6.
37390 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
373a0 54 41 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f TATUS_PAGECACHE_
373b0 53 49 5a 45 20 20 20 20 20 20 20 37 0a 23 64 65 SIZE 7.#de
373c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 fine SQLITE_STAT
373d0 55 53 5f 53 43 52 41 54 43 48 5f 53 49 5a 45 20 US_SCRATCH_SIZE
373e0 20 20 20 20 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 8../*.**
373f0 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 CAPI3REF: Datab
37400 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 53 ase Connection S
37410 74 61 74 75 73 20 7b 48 31 37 35 30 30 7d 20 3c tatus {H17500} <
37420 53 36 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 S60200>.** EXPER
37430 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 IMENTAL.**.** Th
37440 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 is interface is
37450 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 used to retrieve
37460 20 72 75 6e 74 69 6d 65 20 73 74 61 74 75 73 20 runtime status
37470 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 0a 2a 2a 20 information .**
37480 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 5b about a single [
37490 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
374a0 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 ion]. The first
374b0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
374c0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
374d0 6e 65 63 74 69 6f 6e 20 6f 62 6a 65 63 74 20 74 nection object t
374e0 6f 20 62 65 20 69 6e 74 65 72 72 6f 67 61 74 65 o be interrogate
374f0 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 d. The second a
37500 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 74 68 rgument.** is th
37510 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 69 e parameter to i
37520 6e 74 65 72 72 6f 67 61 74 65 2e 20 20 43 75 72 nterrogate. Cur
37530 72 65 6e 74 6c 79 2c 20 74 68 65 20 6f 6e 6c 79 rently, the only
37540 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 0a 2a allowed value.*
37550 2a 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 * for the second
37560 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 5b 53 parameter is [S
37570 51 4c 49 54 45 5f 44 42 53 54 41 54 55 53 5f 4c QLITE_DBSTATUS_L
37580 4f 4f 4b 41 53 49 44 45 5f 55 53 45 44 5d 2e 0a OOKASIDE_USED]..
37590 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6f 70 ** Additional op
375a0 74 69 6f 6e 73 20 77 69 6c 6c 20 6c 69 6b 65 6c tions will likel
375b0 79 20 61 70 70 65 61 72 20 69 6e 20 66 75 74 75 y appear in futu
375c0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 re releases of S
375d0 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 QLite..**.** The
375e0 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f current value o
375f0 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 f the requested
37600 70 61 72 61 6d 65 74 65 72 20 69 73 20 77 72 69 parameter is wri
37610 74 74 65 6e 20 69 6e 74 6f 20 2a 70 43 75 72 0a tten into *pCur.
37620 2a 2a 20 61 6e 64 20 74 68 65 20 68 69 67 68 65 ** and the highe
37630 73 74 20 69 6e 73 74 61 6e 74 61 6e 65 6f 75 73 st instantaneous
37640 20 76 61 6c 75 65 20 69 73 20 77 72 69 74 74 65 value is writte
37650 6e 20 69 6e 74 6f 20 2a 70 48 69 77 74 72 2e 20 n into *pHiwtr.
37660 20 49 66 0a 2a 2a 20 74 68 65 20 72 65 73 65 74 If.** the reset
37670 46 6c 67 20 69 73 20 74 72 75 65 2c 20 74 68 65 Flg is true, the
37680 6e 20 74 68 65 20 68 69 67 68 65 73 74 20 69 6e n the highest in
37690 73 74 61 6e 74 61 6e 65 6f 75 73 20 76 61 6c 75 stantaneous valu
376a0 65 20 69 73 0a 2a 2a 20 72 65 73 65 74 20 62 61 e is.** reset ba
376b0 63 6b 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 63 ck down to the c
376c0 75 72 72 65 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a urrent value..**
376d0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
376e0 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d qlite3_status()]
376f0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 and [sqlite3_st
37700 6d 74 5f 73 74 61 74 75 73 28 29 5d 2e 0a 2a 2f mt_status()]..*/
37710 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 .SQLITE_EXPERIME
37720 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 NTAL int sqlite3
37730 5f 64 62 5f 73 74 61 74 75 73 28 73 71 6c 69 74 _db_status(sqlit
37740 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 69 6e 74 e3*, int op, int
37750 20 2a 70 43 75 72 2c 20 69 6e 74 20 2a 70 48 69 *pCur, int *pHi
37760 77 74 72 2c 20 69 6e 74 20 72 65 73 65 74 46 6c wtr, int resetFl
37770 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 g);../*.** CAPI3
37780 52 45 46 3a 20 53 74 61 74 75 73 20 50 61 72 61 REF: Status Para
37790 6d 65 74 65 72 73 20 66 6f 72 20 64 61 74 61 62 meters for datab
377a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 ase connections
377b0 7b 48 31 37 35 32 30 7d 20 3c 48 31 37 35 30 30 {H17520} <H17500
377c0 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 >.** EXPERIMENTA
377d0 4c 0a 2a 2a 0a 2a 2a 20 53 74 61 74 75 73 20 76 L.**.** Status v
377e0 65 72 62 73 20 66 6f 72 20 5b 73 71 6c 69 74 65 erbs for [sqlite
377f0 33 5f 64 62 5f 73 74 61 74 75 73 28 29 5d 2e 0a 3_db_status()]..
37800 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 **.** <dl>.** <d
37810 74 3e 53 51 4c 49 54 45 5f 44 42 53 54 41 54 55 t>SQLITE_DBSTATU
37820 53 5f 4c 4f 4f 4b 41 53 49 44 45 5f 55 53 45 44 S_LOOKASIDE_USED
37830 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 </dt>.** <dd>Thi
37840 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 74 75 s parameter retu
37850 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
37860 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f f lookaside memo
37870 72 79 20 73 6c 6f 74 73 20 63 75 72 72 65 6e 74 ry slots current
37880 6c 79 0a 2a 2a 20 63 68 65 63 6b 65 64 20 6f 75 ly.** checked ou
37890 74 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e t.</dd>.** </dl>
378a0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
378b0 54 45 5f 44 42 53 54 41 54 55 53 5f 4c 4f 4f 4b TE_DBSTATUS_LOOK
378c0 41 53 49 44 45 5f 55 53 45 44 20 20 20 20 20 30 ASIDE_USED 0
378d0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 .../*.** CAPI3RE
378e0 46 3a 20 50 72 65 70 61 72 65 64 20 53 74 61 74 F: Prepared Stat
378f0 65 6d 65 6e 74 20 53 74 61 74 75 73 20 7b 48 31 ement Status {H1
37900 37 35 35 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 7550} <S60200>.*
37910 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
37920 2a 0a 2a 2a 20 45 61 63 68 20 70 72 65 70 61 72 *.** Each prepar
37930 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6d 61 69 ed statement mai
37940 6e 74 61 69 6e 73 20 76 61 72 69 6f 75 73 0a 2a ntains various.*
37950 2a 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 53 54 * [SQLITE_STMTST
37960 41 54 55 53 5f 53 4f 52 54 20 7c 20 63 6f 75 6e ATUS_SORT | coun
37970 74 65 72 73 5d 20 74 68 61 74 20 6d 65 61 73 75 ters] that measu
37980 72 65 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a re the number.**
37990 20 6f 66 20 74 69 6d 65 73 20 69 74 20 68 61 73 of times it has
379a0 20 70 65 72 66 6f 72 6d 65 64 20 73 70 65 63 69 performed speci
379b0 66 69 63 20 6f 70 65 72 61 74 69 6f 6e 73 2e 20 fic operations.
379c0 20 54 68 65 73 65 20 63 6f 75 6e 74 65 72 73 20 These counters
379d0 63 61 6e 0a 2a 2a 20 62 65 20 75 73 65 64 20 74 can.** be used t
379e0 6f 20 6d 6f 6e 69 74 6f 72 20 74 68 65 20 70 65 o monitor the pe
379f0 72 66 6f 72 6d 61 6e 63 65 20 63 68 61 72 61 63 rformance charac
37a00 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 teristics of the
37a10 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 prepared.** sta
37a20 74 65 6d 65 6e 74 73 2e 20 20 46 6f 72 20 65 78 tements. For ex
37a30 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 6e 75 ample, if the nu
37a40 6d 62 65 72 20 6f 66 20 74 61 62 6c 65 20 73 74 mber of table st
37a50 65 70 73 20 67 72 65 61 74 6c 79 20 65 78 63 65 eps greatly exce
37a60 65 64 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 eds.** the numbe
37a70 72 20 6f 66 20 74 61 62 6c 65 20 73 65 61 72 63 r of table searc
37a80 68 65 73 20 6f 72 20 72 65 73 75 6c 74 20 72 6f hes or result ro
37a90 77 73 2c 20 74 68 61 74 20 77 6f 75 6c 64 20 74 ws, that would t
37aa0 65 6e 64 20 74 6f 20 69 6e 64 69 63 61 74 65 0a end to indicate.
37ab0 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 65 70 ** that the prep
37ac0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 ared statement i
37ad0 73 20 75 73 69 6e 67 20 61 20 66 75 6c 6c 20 74 s using a full t
37ae0 61 62 6c 65 20 73 63 61 6e 20 72 61 74 68 65 72 able scan rather
37af0 20 74 68 61 6e 0a 2a 2a 20 61 6e 20 69 6e 64 65 than.** an inde
37b00 78 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 x. .**.** This
37b10 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 interface is use
37b20 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 6e d to retrieve an
37b30 64 20 72 65 73 65 74 20 63 6f 75 6e 74 65 72 20 d reset counter
37b40 76 61 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 61 values from.** a
37b50 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
37b60 6d 65 6e 74 5d 2e 20 20 54 68 65 20 66 69 72 73 ment]. The firs
37b70 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 t argument is th
37b80 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 e prepared state
37b90 6d 65 6e 74 0a 2a 2a 20 6f 62 6a 65 63 74 20 74 ment.** object t
37ba0 6f 20 62 65 20 69 6e 74 65 72 72 6f 67 61 74 65 o be interrogate
37bb0 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 d. The second a
37bc0 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 61 6e rgument.** is an
37bd0 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 66 6f integer code fo
37be0 72 20 61 20 73 70 65 63 69 66 69 63 20 5b 53 51 r a specific [SQ
37bf0 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f LITE_STMTSTATUS_
37c00 53 4f 52 54 20 7c 20 63 6f 75 6e 74 65 72 5d 0a SORT | counter].
37c10 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 6f ** to be interro
37c20 67 61 74 65 64 2e 20 0a 2a 2a 20 54 68 65 20 63 gated. .** The c
37c30 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 urrent value of
37c40 74 68 65 20 72 65 71 75 65 73 74 65 64 20 63 6f the requested co
37c50 75 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 unter is returne
37c60 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 d..** If the res
37c70 65 74 46 6c 67 20 69 73 20 74 72 75 65 2c 20 74 etFlg is true, t
37c80 68 65 6e 20 74 68 65 20 63 6f 75 6e 74 65 72 20 hen the counter
37c90 69 73 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f is reset to zero
37ca0 20 61 66 74 65 72 20 74 68 69 73 0a 2a 2a 20 69 after this.** i
37cb0 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 72 65 nterface call re
37cc0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 turns..**.** See
37cd0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
37ce0 73 74 61 74 75 73 28 29 5d 20 61 6e 64 20 5b 73 status()] and [s
37cf0 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 qlite3_db_status
37d00 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 ()]..*/.SQLITE_E
37d10 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 XPERIMENTAL int
37d20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 73 74 61 sqlite3_stmt_sta
37d30 74 75 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 tus(sqlite3_stmt
37d40 2a 2c 20 69 6e 74 20 6f 70 2c 69 6e 74 20 72 65 *, int op,int re
37d50 73 65 74 46 6c 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 setFlg);../*.**
37d60 43 41 50 49 33 52 45 46 3a 20 53 74 61 74 75 73 CAPI3REF: Status
37d70 20 50 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 Parameters for
37d80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
37d90 6e 74 73 20 7b 48 31 37 35 37 30 7d 20 3c 48 31 nts {H17570} <H1
37da0 37 35 35 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 7550>.** EXPERIM
37db0 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ENTAL.**.** Thes
37dc0 65 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d e preprocessor m
37dd0 61 63 72 6f 73 20 64 65 66 69 6e 65 20 69 6e 74 acros define int
37de0 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 eger codes that
37df0 6e 61 6d 65 20 63 6f 75 6e 74 65 72 0a 2a 2a 20 name counter.**
37e00 76 61 6c 75 65 73 20 61 73 73 6f 63 69 61 74 65 values associate
37e10 64 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 d with the [sqli
37e20 74 65 33 5f 73 74 6d 74 5f 73 74 61 74 75 73 28 te3_stmt_status(
37e30 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a )] interface..**
37e40 20 54 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 The meanings of
37e50 20 74 68 65 20 76 61 72 69 6f 75 73 20 63 6f 75 the various cou
37e60 6e 74 65 72 73 20 61 72 65 20 61 73 20 66 6f 6c nters are as fol
37e70 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e lows:.**.** <dl>
37e80 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 .** <dt>SQLITE_S
37e90 54 4d 54 53 54 41 54 55 53 5f 46 55 4c 4c 53 43 TMTSTATUS_FULLSC
37ea0 41 4e 5f 53 54 45 50 3c 2f 64 74 3e 0a 2a 2a 20 AN_STEP</dt>.**
37eb0 3c 64 64 3e 54 68 69 73 20 69 73 20 74 68 65 20 <dd>This is the
37ec0 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 number of times
37ed0 74 68 61 74 20 53 51 4c 69 74 65 20 68 61 73 20 that SQLite has
37ee0 73 74 65 70 70 65 64 20 66 6f 72 77 61 72 64 20 stepped forward
37ef0 69 6e 0a 2a 2a 20 61 20 74 61 62 6c 65 20 61 73 in.** a table as
37f00 20 70 61 72 74 20 6f 66 20 61 20 66 75 6c 6c 20 part of a full
37f10 74 61 62 6c 65 20 73 63 61 6e 2e 20 20 4c 61 72 table scan. Lar
37f20 67 65 20 6e 75 6d 62 65 72 73 20 66 6f 72 20 74 ge numbers for t
37f30 68 69 73 20 63 6f 75 6e 74 65 72 0a 2a 2a 20 6d his counter.** m
37f40 61 79 20 69 6e 64 69 63 61 74 65 20 6f 70 70 6f ay indicate oppo
37f50 72 74 75 6e 69 74 69 65 73 20 66 6f 72 20 70 65 rtunities for pe
37f60 72 66 6f 72 6d 61 6e 63 65 20 69 6d 70 72 6f 76 rformance improv
37f70 65 6d 65 6e 74 20 74 68 72 6f 75 67 68 20 0a 2a ement through .*
37f80 2a 20 63 61 72 65 66 75 6c 20 75 73 65 20 6f 66 * careful use of
37f90 20 69 6e 64 69 63 65 73 2e 3c 2f 64 64 3e 0a 2a indices.</dd>.*
37fa0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
37fb0 53 54 4d 54 53 54 41 54 55 53 5f 53 4f 52 54 3c STMTSTATUS_SORT<
37fc0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 /dt>.** <dd>This
37fd0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
37fe0 66 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e f sort operation
37ff0 73 20 74 68 61 74 20 68 61 76 65 20 6f 63 63 75 s that have occu
38000 72 72 65 64 2e 0a 2a 2a 20 41 20 6e 6f 6e 2d 7a rred..** A non-z
38010 65 72 6f 20 76 61 6c 75 65 20 69 6e 20 74 68 69 ero value in thi
38020 73 20 63 6f 75 6e 74 65 72 20 6d 61 79 20 69 6e s counter may in
38030 64 69 63 61 74 65 20 61 6e 20 6f 70 70 6f 72 74 dicate an opport
38040 75 6e 69 74 79 20 74 6f 0a 2a 2a 20 69 6d 70 72 unity to.** impr
38050 6f 76 65 6d 65 6e 74 20 70 65 72 66 6f 72 6d 61 ovement performa
38060 6e 63 65 20 74 68 72 6f 75 67 68 20 63 61 72 65 nce through care
38070 66 75 6c 20 75 73 65 20 6f 66 20 69 6e 64 69 63 ful use of indic
38080 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c es.</dd>.**.** <
38090 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 /dl>.*/.#define
380a0 53 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 55 SQLITE_STMTSTATU
380b0 53 5f 46 55 4c 4c 53 43 41 4e 5f 53 54 45 50 20 S_FULLSCAN_STEP
380c0 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 1.#define SQ
380d0 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f LITE_STMTSTATUS_
380e0 53 4f 52 54 20 20 20 20 20 20 20 20 20 20 20 20 SORT
380f0 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 2../*.** CAPI3
38100 52 45 46 3a 20 43 75 73 74 6f 6d 20 50 61 67 65 REF: Custom Page
38110 20 43 61 63 68 65 20 4f 62 6a 65 63 74 0a 2a 2a Cache Object.**
38120 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a EXPERIMENTAL.**
38130 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
38140 70 63 61 63 68 65 20 74 79 70 65 20 69 73 20 6f pcache type is o
38150 70 61 71 75 65 2e 20 20 49 74 20 69 73 20 69 6d paque. It is im
38160 70 6c 65 6d 65 6e 74 65 64 20 62 79 0a 2a 2a 20 plemented by.**
38170 74 68 65 20 70 6c 75 67 67 61 62 6c 65 20 6d 6f the pluggable mo
38180 64 75 6c 65 2e 20 20 54 68 65 20 53 51 4c 69 74 dule. The SQLit
38190 65 20 63 6f 72 65 20 68 61 73 20 6e 6f 20 6b 6e e core has no kn
381a0 6f 77 6c 65 64 67 65 20 6f 66 0a 2a 2a 20 69 74 owledge of.** it
381b0 73 20 73 69 7a 65 20 6f 72 20 69 6e 74 65 72 6e s size or intern
381c0 61 6c 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 al structure and
381d0 20 6e 65 76 65 72 20 64 65 61 6c 73 20 77 69 74 never deals wit
381e0 68 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 h the.** sqlite3
381f0 5f 70 63 61 63 68 65 20 6f 62 6a 65 63 74 20 65 _pcache object e
38200 78 63 65 70 74 20 62 79 20 68 6f 6c 64 69 6e 67 xcept by holding
38210 20 61 6e 64 20 70 61 73 73 69 6e 67 20 70 6f 69 and passing poi
38220 6e 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 nters.** to the
38230 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 object..**.** Se
38240 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 e [sqlite3_pcach
38250 65 5f 6d 65 74 68 6f 64 73 5d 20 66 6f 72 20 61 e_methods] for a
38260 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d dditional inform
38270 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 ation..*/.typede
38280 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
38290 5f 70 63 61 63 68 65 20 73 71 6c 69 74 65 33 5f _pcache sqlite3_
382a0 70 63 61 63 68 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 pcache;../*.** C
382b0 41 50 49 33 52 45 46 3a 20 41 70 70 6c 69 63 61 API3REF: Applica
382c0 74 69 6f 6e 20 44 65 66 69 6e 65 64 20 50 61 67 tion Defined Pag
382d0 65 20 43 61 63 68 65 2e 0a 2a 2a 20 45 58 50 45 e Cache..** EXPE
382e0 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 RIMENTAL.**.** T
382f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 he [sqlite3_conf
38300 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ig]([SQLITE_CONF
38310 49 47 5f 50 43 41 43 48 45 5d 2c 20 2e 2e 2e 29 IG_PCACHE], ...)
38320 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 0a 2a interface can.*
38330 2a 20 72 65 67 69 73 74 65 72 20 61 6e 20 61 6c * register an al
38340 74 65 72 6e 61 74 69 76 65 20 70 61 67 65 20 63 ternative page c
38350 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ache implementat
38360 69 6f 6e 20 62 79 20 70 61 73 73 69 6e 67 20 69 ion by passing i
38370 6e 20 61 6e 20 0a 2a 2a 20 69 6e 73 74 61 6e 63 n an .** instanc
38380 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 e of the sqlite3
38390 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 20 _pcache_methods
383a0 73 74 72 75 63 74 75 72 65 2e 20 54 68 65 20 6d structure. The m
383b0 61 6a 6f 72 69 74 79 20 6f 66 20 74 68 65 20 0a ajority of the .
383c0 2a 2a 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 ** heap memory u
383d0 73 65 64 20 62 79 20 73 71 6c 69 74 65 20 69 73 sed by sqlite is
383e0 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 67 used by the pag
383f0 65 20 63 61 63 68 65 20 74 6f 20 63 61 63 68 65 e cache to cache
38400 20 64 61 74 61 20 72 65 61 64 20 0a 2a 2a 20 66 data read .** f
38410 72 6f 6d 2c 20 6f 72 20 72 65 61 64 79 20 74 6f rom, or ready to
38420 20 62 65 20 77 72 69 74 74 65 6e 20 74 6f 2c 20 be written to,
38430 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
38440 65 2e 20 42 79 20 69 6d 70 6c 65 6d 65 6e 74 69 e. By implementi
38450 6e 67 20 61 20 0a 2a 2a 20 63 75 73 74 6f 6d 20 ng a .** custom
38460 70 61 67 65 20 63 61 63 68 65 20 75 73 69 6e 67 page cache using
38470 20 74 68 69 73 20 41 50 49 2c 20 61 6e 20 61 70 this API, an ap
38480 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 63 6f plication can co
38490 6e 74 72 6f 6c 20 6d 6f 72 65 20 0a 2a 2a 20 70 ntrol more .** p
384a0 72 65 63 69 73 65 6c 79 20 74 68 65 20 61 6d 6f recisely the amo
384b0 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 20 63 6f unt of memory co
384c0 6e 73 75 6d 65 64 20 62 79 20 73 71 6c 69 74 65 nsumed by sqlite
384d0 2c 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 , the way in whi
384e0 63 68 20 0a 2a 2a 20 73 61 69 64 20 6d 65 6d 6f ch .** said memo
384f0 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 ry is allocated
38500 61 6e 64 20 72 65 6c 65 61 73 65 64 2c 20 61 6e and released, an
38510 64 20 74 68 65 20 70 6f 6c 69 63 69 65 73 20 75 d the policies u
38520 73 65 64 20 74 6f 20 0a 2a 2a 20 64 65 74 65 72 sed to .** deter
38530 6d 69 6e 65 20 65 78 61 63 74 6c 79 20 77 68 69 mine exactly whi
38540 63 68 20 70 61 72 74 73 20 6f 66 20 61 20 64 61 ch parts of a da
38550 74 61 62 61 73 65 20 66 69 6c 65 20 61 72 65 20 tabase file are
38560 63 61 63 68 65 64 20 61 6e 64 20 66 6f 72 20 0a cached and for .
38570 2a 2a 20 68 6f 77 20 6c 6f 6e 67 2e 0a 2a 2a 0a ** how long..**.
38580 2a 2a 20 54 68 65 20 63 6f 6e 74 65 6e 74 73 20 ** The contents
38590 6f 66 20 74 68 65 20 73 74 72 75 63 74 75 72 65 of the structure
385a0 20 61 72 65 20 63 6f 70 69 65 64 20 74 6f 20 61 are copied to a
385b0 6e 20 69 6e 74 65 72 6e 61 6c 20 62 75 66 66 65 n internal buffe
385c0 72 20 62 79 20 73 71 6c 69 74 65 0a 2a 2a 20 77 r by sqlite.** w
385d0 69 74 68 69 6e 20 74 68 65 20 63 61 6c 6c 20 74 ithin the call t
385e0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 o [sqlite3_confi
385f0 67 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 g]..**.** The xI
38600 6e 69 74 28 29 20 6d 65 74 68 6f 64 20 69 73 20 nit() method is
38610 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 called once for
38620 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 each call to [sq
38630 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
38640 28 29 5d 0a 2a 2a 20 28 75 73 75 61 6c 6c 79 20 ()].** (usually
38650 6f 6e 6c 79 20 6f 6e 63 65 20 64 75 72 69 6e 67 only once during
38660 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 the lifetime of
38670 20 74 68 65 20 70 72 6f 63 65 73 73 29 2e 20 49 the process). I
38680 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 61 t is passed.** a
38690 20 63 6f 70 79 20 6f 66 20 74 68 65 20 73 71 6c copy of the sql
386a0 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 ite3_pcache_meth
386b0 6f 64 73 2e 70 41 72 67 20 76 61 6c 75 65 2e 20 ods.pArg value.
386c0 49 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 It can be used t
386d0 6f 20 73 65 74 0a 2a 2a 20 75 70 20 67 6c 6f 62 o set.** up glob
386e0 61 6c 20 73 74 72 75 63 74 75 72 65 73 20 61 6e al structures an
386f0 64 20 6d 75 74 65 78 65 73 20 72 65 71 75 69 72 d mutexes requir
38700 65 64 20 62 79 20 74 68 65 20 63 75 73 74 6f 6d ed by the custom
38710 20 70 61 67 65 20 63 61 63 68 65 20 0a 2a 2a 20 page cache .**
38720 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 implementation.
38730 54 68 65 20 78 53 68 75 74 64 6f 77 6e 28 29 20 The xShutdown()
38740 6d 65 74 68 6f 64 20 69 73 20 63 61 6c 6c 65 64 method is called
38750 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 0a 2a 2a from within .**
38760 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f [sqlite3_shutdo
38770 77 6e 28 29 5d 2c 20 69 66 20 74 68 65 20 61 70 wn()], if the ap
38780 70 6c 69 63 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 plication invoke
38790 73 20 74 68 69 73 20 41 50 49 2e 20 49 74 20 63 s this API. It c
387a0 61 6e 20 62 65 20 75 73 65 64 0a 2a 2a 20 74 6f an be used.** to
387b0 20 63 6c 65 61 6e 20 75 70 20 61 6e 79 20 6f 75 clean up any ou
387c0 74 73 74 61 6e 64 69 6e 67 20 72 65 73 6f 75 72 tstanding resour
387d0 63 65 73 20 62 65 66 6f 72 65 20 70 72 6f 63 65 ces before proce
387e0 73 73 20 73 68 75 74 64 6f 77 6e 2c 20 69 66 20 ss shutdown, if
387f0 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 required..**.**
38800 54 68 65 20 78 43 72 65 61 74 65 28 29 20 6d 65 The xCreate() me
38810 74 68 6f 64 20 69 73 20 75 73 65 64 20 74 6f 20 thod is used to
38820 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 construct a new
38830 63 61 63 68 65 20 69 6e 73 74 61 6e 63 65 2e 20 cache instance.
38840 54 68 65 0a 2a 2a 20 66 69 72 73 74 20 70 61 72 The.** first par
38850 61 6d 65 74 65 72 2c 20 73 7a 50 61 67 65 2c 20 ameter, szPage,
38860 69 73 20 74 68 65 20 73 69 7a 65 20 69 6e 20 62 is the size in b
38870 79 74 65 73 20 6f 66 20 74 68 65 20 70 61 67 65 ytes of the page
38880 73 20 74 68 61 74 20 6d 75 73 74 0a 2a 2a 20 62 s that must.** b
38890 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 74 e allocated by t
388a0 68 65 20 63 61 63 68 65 2e 20 73 7a 50 61 67 65 he cache. szPage
388b0 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 61 20 70 will not be a p
388c0 6f 77 65 72 20 6f 66 20 74 77 6f 2e 20 54 68 65 ower of two. The
388d0 0a 2a 2a 20 73 65 63 6f 6e 64 20 61 72 67 75 6d .** second argum
388e0 65 6e 74 2c 20 62 50 75 72 67 65 61 62 6c 65 2c ent, bPurgeable,
388f0 20 69 73 20 74 72 75 65 20 69 66 20 74 68 65 20 is true if the
38900 63 61 63 68 65 20 62 65 69 6e 67 20 63 72 65 61 cache being crea
38910 74 65 64 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 75 ted will.** be u
38920 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74 sed to cache dat
38930 61 62 61 73 65 20 70 61 67 65 73 20 72 65 61 64 abase pages read
38940 20 66 72 6f 6d 20 61 20 66 69 6c 65 20 73 74 6f from a file sto
38950 72 65 64 20 6f 6e 20 64 69 73 6b 2c 20 6f 72 0a red on disk, or.
38960 2a 2a 20 66 61 6c 73 65 20 69 66 20 69 74 20 69 ** false if it i
38970 73 20 75 73 65 64 20 66 6f 72 20 61 6e 20 69 6e s used for an in
38980 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 -memory database
38990 2e 20 54 68 65 20 63 61 63 68 65 20 69 6d 70 6c . The cache impl
389a0 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 64 6f ementation.** do
389b0 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 20 64 es not have to d
389c0 6f 20 61 6e 79 74 68 69 6e 67 20 73 70 65 63 69 o anything speci
389d0 61 6c 20 62 61 73 65 64 20 6f 6e 20 74 68 65 20 al based on the
389e0 76 61 6c 75 65 20 6f 66 20 62 50 75 72 67 65 61 value of bPurgea
389f0 62 6c 65 2c 0a 2a 2a 20 69 74 20 69 73 20 70 75 ble,.** it is pu
38a00 72 65 6c 79 20 61 64 76 69 73 6f 72 79 2e 20 0a rely advisory. .
38a10 2a 2a 0a 2a 2a 20 54 68 65 20 78 43 61 63 68 65 **.** The xCache
38a20 73 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 6d 61 size() method ma
38a30 79 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 y be called at a
38a40 6e 79 20 74 69 6d 65 20 62 79 20 53 51 4c 69 74 ny time by SQLit
38a50 65 20 74 6f 20 73 65 74 20 74 68 65 0a 2a 2a 20 e to set the.**
38a60 73 75 67 67 65 73 74 65 64 20 6d 61 78 69 6d 75 suggested maximu
38a70 6d 20 63 61 63 68 65 2d 73 69 7a 65 20 28 6e 75 m cache-size (nu
38a80 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 73 74 mber of pages st
38a90 6f 72 65 64 20 62 79 29 20 74 68 65 20 63 61 63 ored by) the cac
38aa0 68 65 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 70 he.** instance p
38ab0 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 assed as the fir
38ac0 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 69 st argument. Thi
38ad0 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 63 s is the value c
38ae0 6f 6e 66 69 67 75 72 65 64 20 75 73 69 6e 67 0a onfigured using.
38af0 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 22 5b ** the SQLite "[
38b00 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a PRAGMA cache_siz
38b10 65 5d 22 20 63 6f 6d 6d 61 6e 64 2e 20 41 73 20 e]" command. As
38b20 77 69 74 68 20 74 68 65 20 62 50 75 72 67 65 61 with the bPurgea
38b30 62 6c 65 20 70 61 72 61 6d 65 74 65 72 2c 0a 2a ble parameter,.*
38b40 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 * the implementa
38b50 74 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65 71 75 tion is not requ
38b60 69 72 65 64 20 74 6f 20 64 6f 20 61 6e 79 74 68 ired to do anyth
38b70 69 6e 67 20 73 70 65 63 69 61 6c 20 77 69 74 68 ing special with
38b80 20 74 68 69 73 0a 2a 2a 20 76 61 6c 75 65 2c 20 this.** value,
38b90 69 74 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f it is advisory o
38ba0 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 nly..**.** The x
38bb0 50 61 67 65 63 6f 75 6e 74 28 29 20 6d 65 74 68 Pagecount() meth
38bc0 6f 64 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e od should return
38bd0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 the number of p
38be0 61 67 65 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a ages currently.*
38bf0 2a 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 * stored in the
38c00 63 61 63 68 65 20 73 75 70 70 6c 69 65 64 20 61 cache supplied a
38c10 73 20 61 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a s an argument..*
38c20 2a 20 0a 2a 2a 20 54 68 65 20 78 46 65 74 63 68 * .** The xFetch
38c30 28 29 20 6d 65 74 68 6f 64 20 69 73 20 75 73 65 () method is use
38c40 64 20 74 6f 20 66 65 74 63 68 20 61 20 70 61 67 d to fetch a pag
38c50 65 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 e and return a p
38c60 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e 20 0a 2a ointer to it. .*
38c70 2a 20 41 20 27 70 61 67 65 27 2c 20 69 6e 20 74 * A 'page', in t
38c80 68 69 73 20 63 6f 6e 74 65 78 74 2c 20 69 73 20 his context, is
38c90 61 20 62 75 66 66 65 72 20 6f 66 20 73 7a 50 61 a buffer of szPa
38ca0 67 65 20 62 79 74 65 73 20 61 6c 69 67 6e 65 64 ge bytes aligned
38cb0 20 61 74 20 61 6e 0a 2a 2a 20 38 2d 62 79 74 65 at an.** 8-byte
38cc0 20 62 6f 75 6e 64 61 72 79 2e 20 54 68 65 20 70 boundary. The p
38cd0 61 67 65 20 74 6f 20 62 65 20 66 65 74 63 68 65 age to be fetche
38ce0 64 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 20 d is determined
38cf0 62 79 20 74 68 65 20 6b 65 79 2e 20 54 68 65 0a by the key. The.
38d00 2a 2a 20 6d 69 6d 69 6d 75 6d 20 6b 65 79 20 76 ** mimimum key v
38d10 61 6c 75 65 20 69 73 20 31 2e 20 41 66 74 65 72 alue is 1. After
38d20 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 74 it has been ret
38d30 72 69 65 76 65 64 20 75 73 69 6e 67 20 78 46 65 rieved using xFe
38d40 74 63 68 2c 20 74 68 65 20 70 61 67 65 20 0a 2a tch, the page .*
38d50 2a 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 * is considered
38d60 74 6f 20 62 65 20 70 69 6e 6e 65 64 2e 0a 2a 2a to be pinned..**
38d70 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 71 75 65 .** If the reque
38d80 73 74 65 64 20 70 61 67 65 20 69 73 20 61 6c 72 sted page is alr
38d90 65 61 64 79 20 69 6e 20 74 68 65 20 70 61 67 65 eady in the page
38da0 20 63 61 63 68 65 2c 20 74 68 65 6e 20 61 20 70 cache, then a p
38db0 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 ointer to.** the
38dc0 20 63 61 63 68 65 64 20 62 75 66 66 65 72 20 73 cached buffer s
38dd0 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 hould be returne
38de0 64 20 77 69 74 68 20 69 74 73 20 63 6f 6e 74 65 d with its conte
38df0 6e 74 73 20 69 6e 74 61 63 74 2e 20 49 66 20 74 nts intact. If t
38e00 68 65 0a 2a 2a 20 70 61 67 65 20 69 73 20 6e 6f he.** page is no
38e10 74 20 61 6c 72 65 61 64 79 20 69 6e 20 74 68 65 t already in the
38e20 20 63 61 63 68 65 2c 20 74 68 65 6e 20 74 68 65 cache, then the
38e30 20 65 78 70 65 63 74 65 64 20 62 65 68 61 76 69 expected behavi
38e40 6f 75 72 20 6f 66 20 74 68 65 0a 2a 2a 20 63 61 our of the.** ca
38e50 63 68 65 20 69 73 20 64 65 74 65 72 6d 69 6e 65 che is determine
38e60 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 6f d by the value o
38e70 66 20 74 68 65 20 63 72 65 61 74 65 46 6c 61 67 f the createFlag
38e80 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 parameter passe
38e90 64 0a 2a 2a 20 74 6f 20 78 46 65 74 63 68 2c 20 d.** to xFetch,
38ea0 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 according to the
38eb0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 following table
38ec0 3a 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 :.**.** <table b
38ed0 6f 72 64 65 72 3d 31 20 77 69 64 74 68 3d 38 35 order=1 width=85
38ee0 25 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 3e 0a % align=center>.
38ef0 2a 2a 20 20 20 3c 74 72 3e 3c 74 68 3e 63 72 65 ** <tr><th>cre
38f00 61 74 65 46 6c 61 67 3c 74 68 3e 45 78 70 65 63 ateFlag<th>Expec
38f10 74 65 64 20 42 65 68 61 76 69 6f 75 72 0a 2a 2a ted Behaviour.**
38f20 20 20 20 3c 74 72 3e 3c 74 64 3e 30 3c 74 64 3e <tr><td>0<td>
38f30 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 72 NULL should be r
38f40 65 74 75 72 6e 65 64 2e 20 4e 6f 20 6e 65 77 20 eturned. No new
38f50 63 61 63 68 65 20 65 6e 74 72 79 20 69 73 20 63 cache entry is c
38f60 72 65 61 74 65 64 2e 0a 2a 2a 20 20 20 3c 74 72 reated..** <tr
38f70 3e 3c 74 64 3e 31 3c 74 64 3e 49 66 20 63 72 65 ><td>1<td>If cre
38f80 61 74 65 46 6c 61 67 20 69 73 20 73 65 74 20 74 ateFlag is set t
38f90 6f 20 31 2c 20 74 68 69 73 20 69 6e 64 69 63 61 o 1, this indica
38fa0 74 65 73 20 74 68 61 74 20 0a 2a 2a 20 20 20 20 tes that .**
38fb0 20 20 20 20 20 20 20 20 20 20 20 20 53 51 4c 69 SQLi
38fc0 74 65 20 69 73 20 68 6f 6c 64 69 6e 67 20 70 69 te is holding pi
38fd0 6e 6e 65 64 20 70 61 67 65 73 20 74 68 61 74 20 nned pages that
38fe0 63 61 6e 20 62 65 20 75 6e 70 69 6e 6e 65 64 0a can be unpinned.
38ff0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 **
39000 20 20 62 79 20 77 72 69 74 69 6e 67 20 74 68 65 by writing the
39010 69 72 20 63 6f 6e 74 65 6e 74 73 20 74 6f 20 74 ir contents to t
39020 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
39030 20 28 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 (a.**
39040 20 20 20 20 20 20 72 65 6c 61 74 69 76 65 6c 79 relatively
39050 20 65 78 70 65 6e 73 69 76 65 20 6f 70 65 72 61 expensive opera
39060 74 69 6f 6e 29 2e 20 49 6e 20 74 68 69 73 20 73 tion). In this s
39070 69 74 75 61 74 69 6f 6e 20 74 68 65 0a 2a 2a 20 ituation the.**
39080 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 63 c
39090 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ache implementat
390a0 69 6f 6e 20 68 61 73 20 74 77 6f 20 63 68 6f 69 ion has two choi
390b0 63 65 73 3a 20 69 74 20 63 61 6e 20 72 65 74 75 ces: it can retu
390c0 72 6e 20 4e 55 4c 4c 2c 0a 2a 2a 20 20 20 20 20 rn NULL,.**
390d0 20 20 20 20 20 20 20 20 20 20 20 69 6e 20 77 68 in wh
390e0 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 ich case SQLite
390f0 77 69 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f 20 will attempt to
39100 75 6e 70 69 6e 20 6f 6e 65 20 6f 72 20 6d 6f 72 unpin one or mor
39110 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 e .**
39120 20 20 20 20 20 70 61 67 65 73 20 62 65 66 6f 72 pages befor
39130 65 20 72 65 2d 72 65 71 75 65 73 74 69 6e 67 20 e re-requesting
39140 74 68 65 20 73 61 6d 65 20 70 61 67 65 2c 20 6f the same page, o
39150 72 20 69 74 20 63 61 6e 0a 2a 2a 20 20 20 20 20 r it can.**
39160 20 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 alloc
39170 61 74 65 20 61 20 6e 65 77 20 70 61 67 65 20 61 ate a new page a
39180 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e nd return a poin
39190 74 65 72 20 74 6f 20 69 74 2e 20 49 66 20 61 20 ter to it. If a
391a0 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 new.**
391b0 20 20 20 20 20 20 70 61 67 65 20 69 73 20 61 6c page is al
391c0 6c 6f 63 61 74 65 64 2c 20 74 68 65 6e 20 74 68 located, then th
391d0 65 20 66 69 72 73 74 20 73 69 7a 65 6f 66 28 76 e first sizeof(v
391e0 6f 69 64 2a 29 20 62 79 74 65 73 20 6f 66 0a 2a oid*) bytes of.*
391f0 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 *
39200 20 69 74 20 28 61 74 20 6c 65 61 73 74 29 20 6d it (at least) m
39210 75 73 74 20 62 65 20 7a 65 72 6f 65 64 20 62 65 ust be zeroed be
39220 66 6f 72 65 20 69 74 20 69 73 20 72 65 74 75 72 fore it is retur
39230 6e 65 64 2e 0a 2a 2a 20 20 20 3c 74 72 3e 3c 74 ned..** <tr><t
39240 64 3e 32 3c 74 64 3e 49 66 20 63 72 65 61 74 65 d>2<td>If create
39250 46 6c 61 67 20 69 73 20 73 65 74 20 74 6f 20 32 Flag is set to 2
39260 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 69 73 , then SQLite is
39270 20 6e 6f 74 20 68 6f 6c 64 69 6e 67 20 61 6e 79 not holding any
39280 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 .**
39290 20 20 20 70 69 6e 6e 65 64 20 70 61 67 65 73 20 pinned pages
392a0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
392b0 74 68 65 20 73 70 65 63 69 66 69 63 20 63 61 63 the specific cac
392c0 68 65 20 70 61 73 73 65 64 0a 2a 2a 20 20 20 20 he passed.**
392d0 20 20 20 20 20 20 20 20 20 20 20 20 61 73 20 74 as t
392e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
392f0 74 20 74 6f 20 78 46 65 74 63 68 28 29 20 74 68 t to xFetch() th
39300 61 74 20 63 61 6e 20 62 65 20 75 6e 70 69 6e 6e at can be unpinn
39310 65 64 2e 20 54 68 65 0a 2a 2a 20 20 20 20 20 20 ed. The.**
39320 20 20 20 20 20 20 20 20 20 20 63 61 63 68 65 20 cache
39330 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 implementation s
39340 68 6f 75 6c 64 20 61 74 74 65 6d 70 74 20 74 6f hould attempt to
39350 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 77 0a allocate a new.
39360 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 **
39370 20 20 63 61 63 68 65 20 65 6e 74 72 79 20 61 6e cache entry an
39380 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 d return a point
39390 65 72 20 74 6f 20 69 74 2e 20 41 67 61 69 6e 2c er to it. Again,
393a0 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 20 20 the first.**
393b0 20 20 20 20 20 20 20 20 20 20 20 20 20 73 69 7a siz
393c0 65 6f 66 28 76 6f 69 64 2a 29 20 62 79 74 65 73 eof(void*) bytes
393d0 20 6f 66 20 74 68 65 20 70 61 67 65 20 73 68 6f of the page sho
393e0 75 6c 64 20 62 65 20 7a 65 72 6f 65 64 20 62 65 uld be zeroed be
393f0 66 6f 72 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 fore .**
39400 20 20 20 20 20 20 20 20 69 74 20 69 73 20 72 65 it is re
39410 74 75 72 6e 65 64 2e 20 49 66 20 74 68 65 20 78 turned. If the x
39420 46 65 74 63 68 28 29 20 6d 65 74 68 6f 64 20 72 Fetch() method r
39430 65 74 75 72 6e 73 20 4e 55 4c 4c 20 77 68 65 6e eturns NULL when
39440 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 .**
39450 20 20 20 20 63 72 65 61 74 65 46 6c 61 67 3d 3d createFlag==
39460 32 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 2, SQLite assume
39470 73 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 s that a memory
39480 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 20 allocation .**
39490 20 20 20 20 20 20 20 20 20 20 20 20 20 20 66 61 fa
394a0 69 6c 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 iled and returns
394b0 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 74 6f SQLITE_NOMEM to
394c0 20 74 68 65 20 75 73 65 72 2e 0a 2a 2a 20 3c 2f the user..** </
394d0 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 78 55 6e table>.**.** xUn
394e0 70 69 6e 28 29 20 69 73 20 63 61 6c 6c 65 64 20 pin() is called
394f0 62 79 20 53 51 4c 69 74 65 20 77 69 74 68 20 61 by SQLite with a
39500 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 75 pointer to a cu
39510 72 72 65 6e 74 6c 79 20 70 69 6e 6e 65 64 20 70 rrently pinned p
39520 61 67 65 0a 2a 2a 20 61 73 20 69 74 73 20 73 65 age.** as its se
39530 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 20 49 cond argument. I
39540 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 f the third para
39550 6d 65 74 65 72 2c 20 64 69 73 63 61 72 64 2c 20 meter, discard,
39560 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 is non-zero,.**
39570 74 68 65 6e 20 74 68 65 20 70 61 67 65 20 73 68 then the page sh
39580 6f 75 6c 64 20 62 65 20 65 76 69 63 74 65 64 20 ould be evicted
39590 66 72 6f 6d 20 74 68 65 20 63 61 63 68 65 2e 20 from the cache.
395a0 49 6e 20 74 68 69 73 20 63 61 73 65 20 53 51 4c In this case SQL
395b0 69 74 65 20 0a 2a 2a 20 61 73 73 75 6d 65 73 20 ite .** assumes
395c0 74 68 61 74 20 74 68 65 20 6e 65 78 74 20 74 69 that the next ti
395d0 6d 65 20 74 68 65 20 70 61 67 65 20 69 73 20 72 me the page is r
395e0 65 74 72 69 65 76 65 64 20 66 72 6f 6d 20 74 68 etrieved from th
395f0 65 20 63 61 63 68 65 20 75 73 69 6e 67 0a 2a 2a e cache using.**
39600 20 74 68 65 20 78 46 65 74 63 68 28 29 20 6d 65 the xFetch() me
39610 74 68 6f 64 2c 20 69 74 20 77 69 6c 6c 20 62 65 thod, it will be
39620 20 7a 65 72 6f 65 64 2e 20 49 66 20 74 68 65 20 zeroed. If the
39630 64 69 73 63 61 72 64 20 70 61 72 61 6d 65 74 65 discard paramete
39640 72 20 69 73 0a 2a 2a 20 7a 65 72 6f 2c 20 74 68 r is.** zero, th
39650 65 6e 20 74 68 65 20 70 61 67 65 20 69 73 20 63 en the page is c
39660 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20 onsidered to be
39670 75 6e 70 69 6e 6e 65 64 2e 20 54 68 65 20 63 61 unpinned. The ca
39680 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 che implementati
39690 6f 6e 0a 2a 2a 20 6d 61 79 20 63 68 6f 6f 73 65 on.** may choose
396a0 20 74 6f 20 72 65 63 6c 61 69 6d 20 28 66 72 65 to reclaim (fre
396b0 65 20 6f 72 20 72 65 63 79 63 6c 65 29 20 75 6e e or recycle) un
396c0 70 69 6e 6e 65 64 20 70 61 67 65 73 20 61 74 20 pinned pages at
396d0 61 6e 79 20 74 69 6d 65 2e 0a 2a 2a 20 53 51 4c any time..** SQL
396e0 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 ite assumes that
396f0 20 6e 65 78 74 20 74 69 6d 65 20 74 68 65 20 70 next time the p
39700 61 67 65 20 69 73 20 72 65 74 72 69 65 76 65 64 age is retrieved
39710 20 66 72 6f 6d 20 74 68 65 20 63 61 63 68 65 0a from the cache.
39720 2a 2a 20 69 74 20 77 69 6c 6c 20 65 69 74 68 65 ** it will eithe
39730 72 20 62 65 20 7a 65 72 6f 65 64 2c 20 6f 72 20 r be zeroed, or
39740 63 6f 6e 74 61 69 6e 20 74 68 65 20 73 61 6d 65 contain the same
39750 20 64 61 74 61 20 74 68 61 74 20 69 74 20 64 69 data that it di
39760 64 20 77 68 65 6e 20 69 74 0a 2a 2a 20 77 61 73 d when it.** was
39770 20 75 6e 70 69 6e 6e 65 64 2e 0a 2a 2a 0a 2a 2a unpinned..**.**
39780 20 54 68 65 20 63 61 63 68 65 20 69 73 20 6e 6f The cache is no
39790 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 70 65 t required to pe
397a0 72 66 6f 72 6d 20 61 6e 79 20 72 65 66 65 72 65 rform any refere
397b0 6e 63 65 20 63 6f 75 6e 74 69 6e 67 2e 20 41 20 nce counting. A
397c0 73 69 6e 67 6c 65 20 0a 2a 2a 20 63 61 6c 6c 20 single .** call
397d0 74 6f 20 78 55 6e 70 69 6e 28 29 20 75 6e 70 69 to xUnpin() unpi
397e0 6e 73 20 74 68 65 20 70 61 67 65 20 72 65 67 61 ns the page rega
397f0 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75 rdless of the nu
39800 6d 62 65 72 20 6f 66 20 70 72 69 6f 72 20 63 61 mber of prior ca
39810 6c 6c 73 20 0a 2a 2a 20 74 6f 20 78 46 65 74 63 lls .** to xFetc
39820 68 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 h()..**.** The x
39830 52 65 6b 65 79 28 29 20 6d 65 74 68 6f 64 20 69 Rekey() method i
39840 73 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 s used to change
39850 20 74 68 65 20 6b 65 79 20 76 61 6c 75 65 20 61 the key value a
39860 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
39870 68 65 0a 2a 2a 20 70 61 67 65 20 70 61 73 73 65 he.** page passe
39880 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 d as the second
39890 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 6f 6c argument from ol
398a0 64 4b 65 79 20 74 6f 20 6e 65 77 4b 65 79 2e 20 dKey to newKey.
398b0 49 66 20 74 68 65 20 63 61 63 68 65 0a 2a 2a 20 If the cache.**
398c0 70 72 65 76 69 6f 75 73 6c 79 20 63 6f 6e 74 61 previously conta
398d0 69 6e 73 20 61 6e 20 65 6e 74 72 79 20 61 73 73 ins an entry ass
398e0 6f 63 69 61 74 65 64 20 77 69 74 68 20 6e 65 77 ociated with new
398f0 4b 65 79 2c 20 69 74 20 73 68 6f 75 6c 64 20 62 Key, it should b
39900 65 0a 2a 2a 20 64 69 73 63 61 72 64 65 64 2e 20 e.** discarded.
39910 41 6e 79 20 70 72 69 6f 72 20 63 61 63 68 65 20 Any prior cache
39920 65 6e 74 72 79 20 61 73 73 6f 63 69 61 74 65 64 entry associated
39930 20 77 69 74 68 20 6e 65 77 4b 65 79 20 69 73 20 with newKey is
39940 67 75 61 72 61 6e 74 65 65 64 20 6e 6f 74 0a 2a guaranteed not.*
39950 2a 20 74 6f 20 62 65 20 70 69 6e 6e 65 64 2e 0a * to be pinned..
39960 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 **.** When SQLit
39970 65 20 63 61 6c 6c 73 20 74 68 65 20 78 54 72 75 e calls the xTru
39980 6e 63 61 74 65 28 29 20 6d 65 74 68 6f 64 2c 20 ncate() method,
39990 74 68 65 20 63 61 63 68 65 20 6d 75 73 74 20 64 the cache must d
399a0 69 73 63 61 72 64 20 61 6c 6c 0a 2a 2a 20 65 78 iscard all.** ex
399b0 69 73 74 69 6e 67 20 63 61 63 68 65 20 65 6e 74 isting cache ent
399c0 72 69 65 73 20 77 69 74 68 20 70 61 67 65 20 6e ries with page n
399d0 75 6d 62 65 72 73 20 28 6b 65 79 73 29 20 67 72 umbers (keys) gr
399e0 65 61 74 65 72 20 74 68 61 6e 20 6f 72 20 65 71 eater than or eq
399f0 75 61 6c 0a 2a 2a 20 74 6f 20 74 68 65 20 76 61 ual.** to the va
39a00 6c 75 65 20 6f 66 20 74 68 65 20 69 4c 69 6d 69 lue of the iLimi
39a10 74 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 t parameter pass
39a20 65 64 20 74 6f 20 78 54 72 75 6e 63 61 74 65 28 ed to xTruncate(
39a30 29 2e 20 49 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 ). If any.** of
39a40 74 68 65 73 65 20 70 61 67 65 73 20 61 72 65 20 these pages are
39a50 70 69 6e 6e 65 64 2c 20 74 68 65 79 20 61 72 65 pinned, they are
39a60 20 69 6d 70 6c 69 63 69 74 6c 79 20 75 6e 70 69 implicitly unpi
39a70 6e 6e 65 64 2c 20 6d 65 61 6e 69 6e 67 20 74 68 nned, meaning th
39a80 61 74 0a 2a 2a 20 74 68 65 79 20 63 61 6e 20 62 at.** they can b
39a90 65 20 73 61 66 65 6c 79 20 64 69 73 63 61 72 64 e safely discard
39aa0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 ed..**.** The xD
39ab0 65 73 74 72 6f 79 28 29 20 6d 65 74 68 6f 64 20 estroy() method
39ac0 69 73 20 75 73 65 64 20 74 6f 20 64 65 6c 65 74 is used to delet
39ad0 65 20 61 20 63 61 63 68 65 20 61 6c 6c 6f 63 61 e a cache alloca
39ae0 74 65 64 20 62 79 20 78 43 72 65 61 74 65 28 29 ted by xCreate()
39af0 2e 0a 2a 2a 20 41 6c 6c 20 72 65 73 6f 75 72 63 ..** All resourc
39b00 65 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 es associated wi
39b10 74 68 20 74 68 65 20 73 70 65 63 69 66 69 65 64 th the specified
39b20 20 63 61 63 68 65 20 73 68 6f 75 6c 64 20 62 65 cache should be
39b30 20 66 72 65 65 64 2e 20 41 66 74 65 72 0a 2a 2a freed. After.**
39b40 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 44 65 calling the xDe
39b50 73 74 72 6f 79 28 29 20 6d 65 74 68 6f 64 2c 20 stroy() method,
39b60 53 51 4c 69 74 65 20 63 6f 6e 73 69 64 65 72 73 SQLite considers
39b70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 the [sqlite3_pc
39b80 61 63 68 65 2a 5d 0a 2a 2a 20 68 61 6e 64 6c 65 ache*].** handle
39b90 20 69 6e 76 61 6c 69 64 2c 20 61 6e 64 20 77 69 invalid, and wi
39ba0 6c 6c 20 6e 6f 74 20 75 73 65 20 69 74 20 77 69 ll not use it wi
39bb0 74 68 20 61 6e 79 20 6f 74 68 65 72 20 73 71 6c th any other sql
39bc0 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 ite3_pcache_meth
39bd0 6f 64 73 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 ods.** functions
39be0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
39bf0 75 63 74 20 73 71 6c 69 74 65 33 5f 70 63 61 63 uct sqlite3_pcac
39c00 68 65 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 he_methods sqlit
39c10 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 e3_pcache_method
39c20 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 s;.struct sqlite
39c30 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3_pcache_methods
39c40 20 7b 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 3b {. void *pArg;
39c50 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 . int (*xInit)(
39c60 76 6f 69 64 2a 29 3b 0a 20 20 76 6f 69 64 20 28 void*);. void (
39c70 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 *xShutdown)(void
39c80 2a 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 70 63 *);. sqlite3_pc
39c90 61 63 68 65 20 2a 28 2a 78 43 72 65 61 74 65 29 ache *(*xCreate)
39ca0 28 69 6e 74 20 73 7a 50 61 67 65 2c 20 69 6e 74 (int szPage, int
39cb0 20 62 50 75 72 67 65 61 62 6c 65 29 3b 0a 20 20 bPurgeable);.
39cc0 76 6f 69 64 20 28 2a 78 43 61 63 68 65 73 69 7a void (*xCachesiz
39cd0 65 29 28 73 71 6c 69 74 65 33 5f 70 63 61 63 68 e)(sqlite3_pcach
39ce0 65 2a 2c 20 69 6e 74 20 6e 43 61 63 68 65 73 69 e*, int nCachesi
39cf0 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 50 61 ze);. int (*xPa
39d00 67 65 63 6f 75 6e 74 29 28 73 71 6c 69 74 65 33 gecount)(sqlite3
39d10 5f 70 63 61 63 68 65 2a 29 3b 0a 20 20 76 6f 69 _pcache*);. voi
39d20 64 20 2a 28 2a 78 46 65 74 63 68 29 28 73 71 6c d *(*xFetch)(sql
39d30 69 74 65 33 5f 70 63 61 63 68 65 2a 2c 20 75 6e ite3_pcache*, un
39d40 73 69 67 6e 65 64 20 6b 65 79 2c 20 69 6e 74 20 signed key, int
39d50 63 72 65 61 74 65 46 6c 61 67 29 3b 0a 20 20 76 createFlag);. v
39d60 6f 69 64 20 28 2a 78 55 6e 70 69 6e 29 28 73 71 oid (*xUnpin)(sq
39d70 6c 69 74 65 33 5f 70 63 61 63 68 65 2a 2c 20 76 lite3_pcache*, v
39d80 6f 69 64 2a 2c 20 69 6e 74 20 64 69 73 63 61 72 oid*, int discar
39d90 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 52 65 d);. void (*xRe
39da0 6b 65 79 29 28 73 71 6c 69 74 65 33 5f 70 63 61 key)(sqlite3_pca
39db0 63 68 65 2a 2c 20 76 6f 69 64 2a 2c 20 75 6e 73 che*, void*, uns
39dc0 69 67 6e 65 64 20 6f 6c 64 4b 65 79 2c 20 75 6e igned oldKey, un
39dd0 73 69 67 6e 65 64 20 6e 65 77 4b 65 79 29 3b 0a signed newKey);.
39de0 20 20 76 6f 69 64 20 28 2a 78 54 72 75 6e 63 61 void (*xTrunca
39df0 74 65 29 28 73 71 6c 69 74 65 33 5f 70 63 61 63 te)(sqlite3_pcac
39e00 68 65 2a 2c 20 75 6e 73 69 67 6e 65 64 20 69 4c he*, unsigned iL
39e10 69 6d 69 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a imit);. void (*
39e20 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65 xDestroy)(sqlite
39e30 33 5f 70 63 61 63 68 65 2a 29 3b 0a 7d 3b 0a 0a 3_pcache*);.};..
39e40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
39e50 4f 6e 6c 69 6e 65 20 42 61 63 6b 75 70 20 4f 62 Online Backup Ob
39e60 6a 65 63 74 0a 2a 2a 20 45 58 50 45 52 49 4d 45 ject.** EXPERIME
39e70 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 NTAL.**.** The s
39e80 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 qlite3_backup ob
39e90 6a 65 63 74 20 72 65 63 6f 72 64 73 20 73 74 61 ject records sta
39ea0 74 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 te information a
39eb0 62 6f 75 74 20 61 6e 20 6f 6e 67 6f 69 6e 67 0a bout an ongoing.
39ec0 2a 2a 20 6f 6e 6c 69 6e 65 20 62 61 63 6b 75 70 ** online backup
39ed0 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 54 68 65 operation. The
39ee0 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 sqlite3_backup
39ef0 6f 62 6a 65 63 74 20 69 73 20 63 72 65 61 74 65 object is create
39f00 64 20 62 79 0a 2a 2a 20 61 20 63 61 6c 6c 20 74 d by.** a call t
39f10 6f 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 o [sqlite3_backu
39f20 70 5f 69 6e 69 74 28 29 5d 20 61 6e 64 20 69 73 p_init()] and is
39f30 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 61 20 destroyed by a
39f40 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 call to.** [sqli
39f50 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 te3_backup_finis
39f60 68 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 h()]..**.** See
39f70 41 6c 73 6f 3a 20 5b 55 73 69 6e 67 20 74 68 65 Also: [Using the
39f80 20 53 51 4c 69 74 65 20 4f 6e 6c 69 6e 65 20 42 SQLite Online B
39f90 61 63 6b 75 70 20 41 50 49 5d 0a 2a 2f 0a 74 79 ackup API].*/.ty
39fa0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
39fb0 69 74 65 33 5f 62 61 63 6b 75 70 20 73 71 6c 69 ite3_backup sqli
39fc0 74 65 33 5f 62 61 63 6b 75 70 3b 0a 0a 2f 2a 0a te3_backup;../*.
39fd0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 6c ** CAPI3REF: Onl
39fe0 69 6e 65 20 42 61 63 6b 75 70 20 41 50 49 2e 0a ine Backup API..
39ff0 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a ** EXPERIMENTAL.
3a000 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 69 **.** This API i
3a010 73 20 75 73 65 64 20 74 6f 20 6f 76 65 72 77 72 s used to overwr
3a020 69 74 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 ite the contents
3a030 20 6f 66 20 6f 6e 65 20 64 61 74 61 62 61 73 65 of one database
3a040 20 77 69 74 68 20 74 68 61 74 0a 2a 2a 20 6f 66 with that.** of
3a050 20 61 6e 6f 74 68 65 72 2e 20 49 74 20 69 73 20 another. It is
3a060 75 73 65 66 75 6c 20 65 69 74 68 65 72 20 66 6f useful either fo
3a070 72 20 63 72 65 61 74 69 6e 67 20 62 61 63 6b 75 r creating backu
3a080 70 73 20 6f 66 20 64 61 74 61 62 61 73 65 73 20 ps of databases
3a090 6f 72 0a 2a 2a 20 66 6f 72 20 63 6f 70 79 69 6e or.** for copyin
3a0a0 67 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 g in-memory data
3a0b0 62 61 73 65 73 20 74 6f 20 6f 72 20 66 72 6f 6d bases to or from
3a0c0 20 70 65 72 73 69 73 74 65 6e 74 20 66 69 6c 65 persistent file
3a0d0 73 2e 20 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c s. .**.** See Al
3a0e0 73 6f 3a 20 5b 55 73 69 6e 67 20 74 68 65 20 53 so: [Using the S
3a0f0 51 4c 69 74 65 20 4f 6e 6c 69 6e 65 20 42 61 63 QLite Online Bac
3a100 6b 75 70 20 41 50 49 5d 0a 2a 2a 0a 2a 2a 20 45 kup API].**.** E
3a110 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 20 xclusive access
3a120 69 73 20 72 65 71 75 69 72 65 64 20 74 6f 20 74 is required to t
3a130 68 65 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 he destination d
3a140 61 74 61 62 61 73 65 20 66 6f 72 20 74 68 65 20 atabase for the
3a150 0a 2a 2a 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 .** duration of
3a160 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 48 the operation. H
3a170 6f 77 65 76 65 72 20 74 68 65 20 73 6f 75 72 63 owever the sourc
3a180 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 6e e database is on
3a190 6c 79 0a 2a 2a 20 72 65 61 64 2d 6c 6f 63 6b 65 ly.** read-locke
3a1a0 64 20 77 68 69 6c 65 20 69 74 20 69 73 20 61 63 d while it is ac
3a1b0 74 75 61 6c 6c 79 20 62 65 69 6e 67 20 72 65 61 tually being rea
3a1c0 64 2c 20 69 74 20 69 73 20 6e 6f 74 20 6c 6f 63 d, it is not loc
3a1d0 6b 65 64 0a 2a 2a 20 63 6f 6e 74 69 6e 75 6f 75 ked.** continuou
3a1e0 73 6c 79 20 66 6f 72 20 74 68 65 20 65 6e 74 69 sly for the enti
3a1f0 72 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 54 68 re operation. Th
3a200 75 73 2c 20 74 68 65 20 62 61 63 6b 75 70 20 6d us, the backup m
3a210 61 79 20 62 65 0a 2a 2a 20 70 65 72 66 6f 72 6d ay be.** perform
3a220 65 64 20 6f 6e 20 61 20 6c 69 76 65 20 64 61 74 ed on a live dat
3a230 61 62 61 73 65 20 77 69 74 68 6f 75 74 20 70 72 abase without pr
3a240 65 76 65 6e 74 69 6e 67 20 6f 74 68 65 72 20 75 eventing other u
3a250 73 65 72 73 20 66 72 6f 6d 0a 2a 2a 20 77 72 69 sers from.** wri
3a260 74 69 6e 67 20 74 6f 20 74 68 65 20 64 61 74 61 ting to the data
3a270 62 61 73 65 20 66 6f 72 20 61 6e 20 65 78 74 65 base for an exte
3a280 6e 64 65 64 20 70 65 72 69 6f 64 20 6f 66 20 74 nded period of t
3a290 69 6d 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 6f 20 70 ime..** .** To p
3a2a0 65 72 66 6f 72 6d 20 61 20 62 61 63 6b 75 70 20 erform a backup
3a2b0 6f 70 65 72 61 74 69 6f 6e 3a 20 0a 2a 2a 20 20 operation: .**
3a2c0 20 3c 6f 6c 3e 0a 2a 2a 20 20 20 20 20 3c 6c 69 <ol>.** <li
3a2d0 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 62 61 63 6b ><b>sqlite3_back
3a2e0 75 70 5f 69 6e 69 74 28 29 3c 2f 62 3e 20 69 73 up_init()</b> is
3a2f0 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 74 6f 20 called once to
3a300 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 0a 2a initialize the.*
3a310 2a 20 20 20 20 20 20 20 20 20 62 61 63 6b 75 70 * backup
3a320 2c 20 0a 2a 2a 20 20 20 20 20 3c 6c 69 3e 3c 62 , .** <li><b
3a330 3e 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f >sqlite3_backup_
3a340 73 74 65 70 28 29 3c 2f 62 3e 20 69 73 20 63 61 step()</b> is ca
3a350 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 lled one or more
3a360 20 74 69 6d 65 73 20 74 6f 20 74 72 61 6e 73 66 times to transf
3a370 65 72 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 74 er .** t
3a380 68 65 20 64 61 74 61 20 62 65 74 77 65 65 6e 20 he data between
3a390 74 68 65 20 74 77 6f 20 64 61 74 61 62 61 73 65 the two database
3a3a0 73 2c 20 61 6e 64 20 66 69 6e 61 6c 6c 79 0a 2a s, and finally.*
3a3b0 2a 20 20 20 20 20 3c 6c 69 3e 3c 62 3e 73 71 6c * <li><b>sql
3a3c0 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 ite3_backup_fini
3a3d0 73 68 28 29 3c 2f 62 3e 20 69 73 20 63 61 6c 6c sh()</b> is call
3a3e0 65 64 20 74 6f 20 72 65 6c 65 61 73 65 20 61 6c ed to release al
3a3f0 6c 20 72 65 73 6f 75 72 63 65 73 20 0a 2a 2a 20 l resources .**
3a400 20 20 20 20 20 20 20 20 61 73 73 6f 63 69 61 74 associat
3a410 65 64 20 77 69 74 68 20 74 68 65 20 62 61 63 6b ed with the back
3a420 75 70 20 6f 70 65 72 61 74 69 6f 6e 2e 20 0a 2a up operation. .*
3a430 2a 20 20 20 3c 2f 6f 6c 3e 0a 2a 2a 20 54 68 65 * </ol>.** The
3a440 72 65 20 73 68 6f 75 6c 64 20 62 65 20 65 78 61 re should be exa
3a450 63 74 6c 79 20 6f 6e 65 20 63 61 6c 6c 20 74 6f ctly one call to
3a460 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f sqlite3_backup_
3a470 66 69 6e 69 73 68 28 29 20 66 6f 72 20 65 61 63 finish() for eac
3a480 68 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 h.** successful
3a490 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
3a4a0 62 61 63 6b 75 70 5f 69 6e 69 74 28 29 2e 0a 2a backup_init()..*
3a4b0 2a 0a 2a 2a 20 3c 62 3e 73 71 6c 69 74 65 33 5f *.** <b>sqlite3_
3a4c0 62 61 63 6b 75 70 5f 69 6e 69 74 28 29 3c 2f 62 backup_init()</b
3a4d0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 >.**.** The firs
3a4e0 74 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 t two arguments
3a4f0 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 passed to [sqlit
3a500 65 33 5f 62 61 63 6b 75 70 5f 69 6e 69 74 28 29 e3_backup_init()
3a510 5d 20 61 72 65 20 74 68 65 20 64 61 74 61 62 61 ] are the databa
3a520 73 65 0a 2a 2a 20 68 61 6e 64 6c 65 20 61 73 73 se.** handle ass
3a530 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 ociated with the
3a540 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 destination dat
3a550 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 64 61 abase and the da
3a560 74 61 62 61 73 65 20 6e 61 6d 65 20 0a 2a 2a 20 tabase name .**
3a570 75 73 65 64 20 74 6f 20 61 74 74 61 63 68 20 74 used to attach t
3a580 68 65 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 he destination d
3a590 61 74 61 62 61 73 65 20 74 6f 20 74 68 65 20 68 atabase to the h
3a5a0 61 6e 64 6c 65 2e 20 54 68 65 20 64 61 74 61 62 andle. The datab
3a5b0 61 73 65 20 6e 61 6d 65 0a 2a 2a 20 69 73 20 22 ase name.** is "
3a5c0 6d 61 69 6e 22 20 66 6f 72 20 74 68 65 20 6d 61 main" for the ma
3a5d0 69 6e 20 64 61 74 61 62 61 73 65 2c 20 22 74 65 in database, "te
3a5e0 6d 70 22 20 66 6f 72 20 74 68 65 20 74 65 6d 70 mp" for the temp
3a5f0 6f 72 61 72 79 20 64 61 74 61 62 61 73 65 2c 20 orary database,
3a600 6f 72 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 73 or.** the name s
3a610 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74 pecified as part
3a620 20 6f 66 20 74 68 65 20 5b 41 54 54 41 43 48 5d of the [ATTACH]
3a630 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20 74 68 statement if th
3a640 65 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 69 73 e destination is
3a650 0a 2a 2a 20 61 6e 20 61 74 74 61 63 68 65 64 20 .** an attached
3a660 64 61 74 61 62 61 73 65 2e 20 54 68 65 20 74 68 database. The th
3a670 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61 ird and fourth a
3a680 72 67 75 6d 65 6e 74 73 20 70 61 73 73 65 64 20 rguments passed
3a690 74 6f 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 to .** sqlite3_b
3a6a0 61 63 6b 75 70 5f 69 6e 69 74 28 29 20 69 64 65 ackup_init() ide
3a6b0 6e 74 69 66 79 20 74 68 65 20 5b 64 61 74 61 62 ntify the [datab
3a6c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a ase connection].
3a6d0 2a 2a 20 61 6e 64 20 64 61 74 61 62 61 73 65 20 ** and database
3a6e0 6e 61 6d 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 name used.** to
3a6f0 61 63 63 65 73 73 20 74 68 65 20 73 6f 75 72 63 access the sourc
3a700 65 20 64 61 74 61 62 61 73 65 2e 20 54 68 65 20 e database. The
3a710 76 61 6c 75 65 73 20 70 61 73 73 65 64 20 66 6f values passed fo
3a720 72 20 74 68 65 20 73 6f 75 72 63 65 20 61 6e 64 r the source and
3a730 20 0a 2a 2a 20 64 65 73 74 69 6e 61 74 69 6f 6e .** destination
3a740 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
3a750 63 74 69 6f 6e 5d 20 70 61 72 61 6d 65 74 65 72 ction] parameter
3a760 73 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 74 68 s must not be th
3a770 65 20 73 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 e same..**.** If
3a780 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 an error occurs
3a790 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f within sqlite3_
3a7a0 62 61 63 6b 75 70 5f 69 6e 69 74 28 29 2c 20 74 backup_init(), t
3a7b0 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 hen NULL is retu
3a7c0 72 6e 65 64 0a 2a 2a 20 61 6e 64 20 61 6e 20 65 rned.** and an e
3a7d0 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 65 72 rror code and er
3a7e0 72 6f 72 20 6d 65 73 73 61 67 65 20 77 72 69 74 ror message writ
3a7f0 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 5b 64 61 ten into the [da
3a800 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
3a810 6e 5d 20 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 n] .** passed as
3a820 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
3a830 65 6e 74 2e 20 54 68 65 79 20 6d 61 79 20 62 65 ent. They may be
3a840 20 72 65 74 72 69 65 76 65 64 20 75 73 69 6e 67 retrieved using
3a850 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
3a860 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71 _errcode()], [sq
3a870 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c lite3_errmsg()],
3a880 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 and [sqlite3_er
3a890 72 6d 73 67 31 36 28 29 5d 20 66 75 6e 63 74 69 rmsg16()] functi
3a8a0 6f 6e 73 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 ons..** Otherwis
3a8b0 65 2c 20 69 66 20 73 75 63 63 65 73 73 66 75 6c e, if successful
3a8c0 2c 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 , a pointer to a
3a8d0 6e 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 n [sqlite3_backu
3a8e0 70 5d 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 p] object is.**
3a8f0 72 65 74 75 72 6e 65 64 2e 20 54 68 69 73 20 70 returned. This p
3a900 6f 69 6e 74 65 72 20 6d 61 79 20 62 65 20 75 73 ointer may be us
3a910 65 64 20 77 69 74 68 20 74 68 65 20 73 71 6c 69 ed with the sqli
3a920 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 te3_backup_step(
3a930 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ) and.** sqlite3
3a940 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 29 _backup_finish()
3a950 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 70 65 functions to pe
3a960 72 66 6f 72 6d 20 74 68 65 20 73 70 65 63 69 66 rform the specif
3a970 69 65 64 20 62 61 63 6b 75 70 20 0a 2a 2a 20 6f ied backup .** o
3a980 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 peration..**.**
3a990 3c 62 3e 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 <b>sqlite3_backu
3a9a0 70 5f 73 74 65 70 28 29 3c 2f 62 3e 0a 2a 2a 0a p_step()</b>.**.
3a9b0 2a 2a 20 46 75 6e 63 74 69 6f 6e 20 5b 73 71 6c ** Function [sql
3a9c0 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 ite3_backup_step
3a9d0 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 63 ()] is used to c
3a9e0 6f 70 79 20 75 70 20 74 6f 20 6e 50 61 67 65 20 opy up to nPage
3a9f0 70 61 67 65 73 20 62 65 74 77 65 65 6e 20 0a 2a pages between .*
3aa00 2a 20 74 68 65 20 73 6f 75 72 63 65 20 61 6e 64 * the source and
3aa10 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 destination dat
3aa20 61 62 61 73 65 73 2c 20 77 68 65 72 65 20 6e 50 abases, where nP
3aa30 61 67 65 20 69 73 20 74 68 65 20 76 61 6c 75 65 age is the value
3aa40 20 6f 66 20 74 68 65 20 0a 2a 2a 20 73 65 63 6f of the .** seco
3aa50 6e 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 nd parameter pas
3aa60 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 sed to sqlite3_b
3aa70 61 63 6b 75 70 5f 73 74 65 70 28 29 2e 20 49 66 ackup_step(). If
3aa80 20 6e 50 61 67 65 20 69 73 20 61 20 6e 65 67 61 nPage is a nega
3aa90 74 69 76 65 0a 2a 2a 20 76 61 6c 75 65 2c 20 61 tive.** value, a
3aaa0 6c 6c 20 72 65 6d 61 69 6e 69 6e 67 20 73 6f 75 ll remaining sou
3aab0 72 63 65 20 70 61 67 65 73 20 61 72 65 20 63 6f rce pages are co
3aac0 70 69 65 64 2e 20 49 66 20 74 68 65 20 72 65 71 pied. If the req
3aad0 75 69 72 65 64 20 70 61 67 65 73 20 61 72 65 20 uired pages are
3aae0 0a 2a 2a 20 73 75 63 63 65 73 66 75 6c 6c 79 20 .** succesfully
3aaf0 63 6f 70 69 65 64 2c 20 62 75 74 20 74 68 65 72 copied, but ther
3ab00 65 20 61 72 65 20 73 74 69 6c 6c 20 6d 6f 72 65 e are still more
3ab10 20 70 61 67 65 73 20 74 6f 20 63 6f 70 79 20 62 pages to copy b
3ab20 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 62 61 efore the .** ba
3ab30 63 6b 75 70 20 69 73 20 63 6f 6d 70 6c 65 74 65 ckup is complete
3ab40 2c 20 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 , it returns [SQ
3ab50 4c 49 54 45 5f 4f 4b 5d 2e 20 49 66 20 6e 6f 20 LITE_OK]. If no
3ab60 65 72 72 6f 72 20 6f 63 63 75 72 65 64 20 61 6e error occured an
3ab70 64 20 74 68 65 72 65 20 0a 2a 2a 20 61 72 65 20 d there .** are
3ab80 6e 6f 20 6d 6f 72 65 20 70 61 67 65 73 20 74 6f no more pages to
3ab90 20 63 6f 70 79 2c 20 74 68 65 6e 20 5b 53 51 4c copy, then [SQL
3aba0 49 54 45 5f 44 4f 4e 45 5d 20 69 73 20 72 65 74 ITE_DONE] is ret
3abb0 75 72 6e 65 64 2e 20 49 66 20 61 6e 20 65 72 72 urned. If an err
3abc0 6f 72 20 0a 2a 2a 20 6f 63 63 75 72 73 2c 20 74 or .** occurs, t
3abd0 68 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 65 72 hen an SQLite er
3abe0 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 ror code is retu
3abf0 72 6e 65 64 2e 20 41 73 20 77 65 6c 6c 20 61 73 rned. As well as
3ac00 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e 64 [SQLITE_OK] and
3ac10 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 .** [SQLITE_DONE
3ac20 5d 2c 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c ], a call to sql
3ac30 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 ite3_backup_step
3ac40 28 29 20 6d 61 79 20 72 65 74 75 72 6e 20 5b 53 () may return [S
3ac50 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2c QLITE_READONLY],
3ac60 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 .** [SQLITE_NOME
3ac70 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 M], [SQLITE_BUSY
3ac80 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 ], [SQLITE_LOCKE
3ac90 44 5d 2c 20 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 D], or an.** [SQ
3aca0 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 LITE_IOERR_ACCES
3acb0 53 20 7c 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 S | SQLITE_IOERR
3acc0 5f 58 58 58 5d 20 65 78 74 65 6e 64 65 64 20 65 _XXX] extended e
3acd0 72 72 6f 72 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a rror code..**.**
3ace0 20 41 73 20 77 65 6c 6c 20 61 73 20 74 68 65 20 As well as the
3acf0 63 61 73 65 20 77 68 65 72 65 20 74 68 65 20 64 case where the d
3ad00 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 estination datab
3ad10 61 73 65 20 66 69 6c 65 20 77 61 73 20 6f 70 65 ase file was ope
3ad20 6e 65 64 20 66 6f 72 0a 2a 2a 20 72 65 61 64 2d ned for.** read-
3ad30 6f 6e 6c 79 20 61 63 63 65 73 73 2c 20 73 71 6c only access, sql
3ad40 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 ite3_backup_step
3ad50 28 29 20 6d 61 79 20 72 65 74 75 72 6e 20 5b 53 () may return [S
3ad60 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 20 QLITE_READONLY]
3ad70 69 66 0a 2a 2a 20 74 68 65 20 64 65 73 74 69 6e if.** the destin
3ad80 61 74 69 6f 6e 20 69 73 20 61 6e 20 69 6e 2d 6d ation is an in-m
3ad90 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 emory database w
3ada0 69 74 68 20 61 20 64 69 66 66 65 72 65 6e 74 20 ith a different
3adb0 70 61 67 65 20 73 69 7a 65 0a 2a 2a 20 66 72 6f page size.** fro
3adc0 6d 20 74 68 65 20 73 6f 75 72 63 65 20 64 61 74 m the source dat
3add0 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 abase..**.** If
3ade0 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 sqlite3_backup_s
3adf0 74 65 70 28 29 20 63 61 6e 6e 6f 74 20 6f 62 74 tep() cannot obt
3ae00 61 69 6e 20 61 20 72 65 71 75 69 72 65 64 20 66 ain a required f
3ae10 69 6c 65 2d 73 79 73 74 65 6d 20 6c 6f 63 6b 2c ile-system lock,
3ae20 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 73 71 then.** the [sq
3ae30 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c lite3_busy_handl
3ae40 65 72 20 7c 20 62 75 73 79 2d 68 61 6e 64 6c 65 er | busy-handle
3ae50 72 20 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 69 r function].** i
3ae60 73 20 69 6e 76 6f 6b 65 64 20 28 69 66 20 6f 6e s invoked (if on
3ae70 65 20 69 73 20 73 70 65 63 69 66 69 65 64 29 2e e is specified).
3ae80 20 49 66 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 If the .** busy
3ae90 2d 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 -handler returns
3aea0 20 6e 6f 6e 2d 7a 65 72 6f 20 62 65 66 6f 72 65 non-zero before
3aeb0 20 74 68 65 20 6c 6f 63 6b 20 69 73 20 61 76 61 the lock is ava
3aec0 69 6c 61 62 6c 65 2c 20 74 68 65 6e 20 0a 2a 2a ilable, then .**
3aed0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 [SQLITE_BUSY] i
3aee0 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 s returned to th
3aef0 65 20 63 61 6c 6c 65 72 2e 20 49 6e 20 74 68 69 e caller. In thi
3af00 73 20 63 61 73 65 20 74 68 65 20 63 61 6c 6c 20 s case the call
3af10 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 to.** sqlite3_ba
3af20 63 6b 75 70 5f 73 74 65 70 28 29 20 63 61 6e 20 ckup_step() can
3af30 62 65 20 72 65 74 72 69 65 64 20 6c 61 74 65 72 be retried later
3af40 2e 20 49 66 20 74 68 65 20 73 6f 75 72 63 65 0a . If the source.
3af50 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
3af60 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 73 20 62 nection].** is b
3af70 65 69 6e 67 20 75 73 65 64 20 74 6f 20 77 72 69 eing used to wri
3af80 74 65 20 74 6f 20 74 68 65 20 73 6f 75 72 63 65 te to the source
3af90 20 64 61 74 61 62 61 73 65 20 77 68 65 6e 20 73 database when s
3afa0 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 qlite3_backup_st
3afb0 65 70 28 29 0a 2a 2a 20 69 73 20 63 61 6c 6c 65 ep().** is calle
3afc0 64 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f d, then [SQLITE_
3afd0 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 LOCKED] is retur
3afe0 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e ned immediately.
3aff0 20 41 67 61 69 6e 2c 20 69 6e 20 74 68 69 73 0a Again, in this.
3b000 2a 2a 20 63 61 73 65 20 74 68 65 20 63 61 6c 6c ** case the call
3b010 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b to sqlite3_back
3b020 75 70 5f 73 74 65 70 28 29 20 63 61 6e 20 62 65 up_step() can be
3b030 20 72 65 74 72 69 65 64 20 6c 61 74 65 72 20 6f retried later o
3b040 6e 2e 20 49 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 n. If.** [SQLITE
3b050 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 7c 20 _IOERR_ACCESS |
3b060 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 58 58 58 SQLITE_IOERR_XXX
3b070 5d 2c 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d ], [SQLITE_NOMEM
3b080 5d 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 ], or.** [SQLITE
3b090 5f 52 45 41 44 4f 4e 4c 59 5d 20 69 73 20 72 65 _READONLY] is re
3b0a0 74 75 72 6e 65 64 2c 20 74 68 65 6e 20 0a 2a 2a turned, then .**
3b0b0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 70 6f 69 there is no poi
3b0c0 6e 74 20 69 6e 20 72 65 74 72 79 69 6e 67 20 74 nt in retrying t
3b0d0 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 he call to sqlit
3b0e0 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 e3_backup_step()
3b0f0 2e 20 54 68 65 73 65 20 0a 2a 2a 20 65 72 72 6f . These .** erro
3b100 72 73 20 61 72 65 20 63 6f 6e 73 69 64 65 72 65 rs are considere
3b110 64 20 66 61 74 61 6c 2e 20 41 74 20 74 68 69 73 d fatal. At this
3b120 20 70 6f 69 6e 74 20 74 68 65 20 61 70 70 6c 69 point the appli
3b130 63 61 74 69 6f 6e 20 6d 75 73 74 20 61 63 63 65 cation must acce
3b140 70 74 20 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 pt .** that the
3b150 62 61 63 6b 75 70 20 6f 70 65 72 61 74 69 6f 6e backup operation
3b160 20 68 61 73 20 66 61 69 6c 65 64 20 61 6e 64 20 has failed and
3b170 70 61 73 73 20 74 68 65 20 62 61 63 6b 75 70 20 pass the backup
3b180 6f 70 65 72 61 74 69 6f 6e 20 68 61 6e 64 6c 65 operation handle
3b190 20 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 .** to the sqli
3b1a0 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 te3_backup_finis
3b1b0 68 28 29 20 74 6f 20 72 65 6c 65 61 73 65 20 61 h() to release a
3b1c0 73 73 6f 63 69 61 74 65 64 20 72 65 73 6f 75 72 ssociated resour
3b1d0 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 46 6f 6c 6c 6f ces..**.** Follo
3b1e0 77 69 6e 67 20 74 68 65 20 66 69 72 73 74 20 63 wing the first c
3b1f0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 all to sqlite3_b
3b200 61 63 6b 75 70 5f 73 74 65 70 28 29 2c 20 61 6e ackup_step(), an
3b210 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 20 exclusive lock
3b220 69 73 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 6f is.** obtained o
3b230 6e 20 74 68 65 20 64 65 73 74 69 6e 61 74 69 6f n the destinatio
3b240 6e 20 66 69 6c 65 2e 20 49 74 20 69 73 20 6e 6f n file. It is no
3b250 74 20 72 65 6c 65 61 73 65 64 20 75 6e 74 69 6c t released until
3b260 20 65 69 74 68 65 72 20 0a 2a 2a 20 73 71 6c 69 either .** sqli
3b270 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 te3_backup_finis
3b280 68 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 72 h() is called or
3b290 20 74 68 65 20 62 61 63 6b 75 70 20 6f 70 65 72 the backup oper
3b2a0 61 74 69 6f 6e 20 69 73 20 63 6f 6d 70 6c 65 74 ation is complet
3b2b0 65 20 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 e .** and sqlite
3b2c0 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 3_backup_step()
3b2d0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
3b2e0 44 4f 4e 45 5d 2e 20 41 64 64 69 74 69 6f 6e 61 DONE]. Additiona
3b2f0 6c 6c 79 2c 20 65 61 63 68 20 74 69 6d 65 20 0a lly, each time .
3b300 2a 2a 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c ** a call to sql
3b310 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 ite3_backup_step
3b320 28 29 20 69 73 20 6d 61 64 65 20 61 20 5b 73 68 () is made a [sh
3b330 61 72 65 64 20 6c 6f 63 6b 5d 20 69 73 20 6f 62 ared lock] is ob
3b340 74 61 69 6e 65 64 20 6f 6e 0a 2a 2a 20 74 68 65 tained on.** the
3b350 20 73 6f 75 72 63 65 20 64 61 74 61 62 61 73 65 source database
3b360 20 66 69 6c 65 2e 20 54 68 69 73 20 6c 6f 63 6b file. This lock
3b370 20 69 73 20 72 65 6c 65 61 73 65 64 20 62 65 66 is released bef
3b380 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 ore the.** sqlit
3b390 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 e3_backup_step()
3b3a0 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 20 42 call returns. B
3b3b0 65 63 61 75 73 65 20 74 68 65 20 73 6f 75 72 63 ecause the sourc
3b3c0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f e database is no
3b3d0 74 0a 2a 2a 20 6c 6f 63 6b 65 64 20 62 65 74 77 t.** locked betw
3b3e0 65 65 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c een calls to sql
3b3f0 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 ite3_backup_step
3b400 28 29 2c 20 69 74 20 6d 61 79 20 62 65 20 6d 6f (), it may be mo
3b410 64 69 66 69 65 64 20 6d 69 64 2d 77 61 79 0a 2a dified mid-way.*
3b420 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 62 61 * through the ba
3b430 63 6b 75 70 20 70 72 6f 63 65 64 75 72 65 2e 20 ckup procedure.
3b440 49 66 20 74 68 65 20 73 6f 75 72 63 65 20 64 61 If the source da
3b450 74 61 62 61 73 65 20 69 73 20 6d 6f 64 69 66 69 tabase is modifi
3b460 65 64 20 62 79 20 61 6e 0a 2a 2a 20 65 78 74 65 ed by an.** exte
3b470 72 6e 61 6c 20 70 72 6f 63 65 73 73 20 6f 72 20 rnal process or
3b480 76 69 61 20 61 20 64 61 74 61 62 61 73 65 20 63 via a database c
3b490 6f 6e 6e 65 63 74 69 6f 6e 20 6f 74 68 65 72 20 onnection other
3b4a0 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 62 65 69 than the one bei
3b4b0 6e 67 0a 2a 2a 20 75 73 65 64 20 62 79 20 74 68 ng.** used by th
3b4c0 65 20 62 61 63 6b 75 70 20 6f 70 65 72 61 74 69 e backup operati
3b4d0 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 62 61 63 on, then the bac
3b4e0 6b 75 70 20 77 69 6c 6c 20 62 65 20 74 72 61 6e kup will be tran
3b4f0 73 70 61 72 65 6e 74 6c 79 0a 2a 2a 20 72 65 73 sparently.** res
3b500 74 61 72 74 65 64 20 62 79 20 74 68 65 20 6e 65 tarted by the ne
3b510 78 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 xt call to sqlit
3b520 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 e3_backup_step()
3b530 2e 20 49 66 20 74 68 65 20 73 6f 75 72 63 65 20 . If the source
3b540 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 .** database is
3b550 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 20 modified by the
3b560 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 64 using the same d
3b570 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
3b580 6f 6e 20 61 73 20 69 73 20 75 73 65 64 0a 2a 2a on as is used.**
3b590 20 62 79 20 74 68 65 20 62 61 63 6b 75 70 20 6f by the backup o
3b5a0 70 65 72 61 74 69 6f 6e 2c 20 74 68 65 6e 20 74 peration, then t
3b5b0 68 65 20 62 61 63 6b 75 70 20 64 61 74 61 62 61 he backup databa
3b5c0 73 65 20 69 73 20 74 72 61 6e 73 70 61 72 65 6e se is transparen
3b5d0 74 6c 79 20 0a 2a 2a 20 75 70 64 61 74 65 64 20 tly .** updated
3b5e0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 at the same time
3b5f0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 73 71 6c 69 74 ..**.** <b>sqlit
3b600 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 e3_backup_finish
3b610 28 29 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 63 ()</b>.**.** Onc
3b620 65 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 e sqlite3_backup
3b630 5f 73 74 65 70 28 29 20 68 61 73 20 72 65 74 75 _step() has retu
3b640 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e rned [SQLITE_DON
3b650 45 5d 2c 20 6f 72 20 77 68 65 6e 20 74 68 65 20 E], or when the
3b660 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 .** application
3b670 77 69 73 68 65 73 20 74 6f 20 61 62 61 6e 64 6f wishes to abando
3b680 6e 20 74 68 65 20 62 61 63 6b 75 70 20 6f 70 65 n the backup ope
3b690 72 61 74 69 6f 6e 2c 20 74 68 65 20 5b 73 71 6c ration, the [sql
3b6a0 69 74 65 33 5f 62 61 63 6b 75 70 5d 0a 2a 2a 20 ite3_backup].**
3b6b0 6f 62 6a 65 63 74 20 73 68 6f 75 6c 64 20 62 65 object should be
3b6c0 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 passed to sqlit
3b6d0 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 e3_backup_finish
3b6e0 28 29 2e 20 54 68 69 73 20 72 65 6c 65 61 73 65 (). This release
3b6f0 73 20 61 6c 6c 0a 2a 2a 20 72 65 73 6f 75 72 63 s all.** resourc
3b700 65 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 es associated wi
3b710 74 68 20 74 68 65 20 62 61 63 6b 75 70 20 6f 70 th the backup op
3b720 65 72 61 74 69 6f 6e 2e 20 49 66 20 73 71 6c 69 eration. If sqli
3b730 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 te3_backup_step(
3b740 29 0a 2a 2a 20 68 61 73 20 6e 6f 74 20 79 65 74 ).** has not yet
3b750 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 returned [SQLIT
3b760 45 5f 44 4f 4e 45 5d 2c 20 74 68 65 6e 20 61 6e E_DONE], then an
3b770 79 20 61 63 74 69 76 65 20 77 72 69 74 65 2d 74 y active write-t
3b780 72 61 6e 73 61 63 74 69 6f 6e 20 6f 6e 20 74 68 ransaction on th
3b790 65 0a 2a 2a 20 64 65 73 74 69 6e 61 74 69 6f 6e e.** destination
3b7a0 20 64 61 74 61 62 61 73 65 20 69 73 20 72 6f 6c database is rol
3b7b0 6c 65 64 20 62 61 63 6b 2e 20 54 68 65 20 5b 73 led back. The [s
3b7c0 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f qlite3_backup] o
3b7d0 62 6a 65 63 74 20 69 73 20 69 6e 76 61 6c 69 64 bject is invalid
3b7e0 0a 2a 2a 20 61 6e 64 20 6d 61 79 20 6e 6f 74 20 .** and may not
3b7f0 62 65 20 75 73 65 64 20 66 6f 6c 6c 6f 77 69 6e be used followin
3b800 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 g a call to sqli
3b810 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 te3_backup_finis
3b820 68 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 h()..**.** The v
3b830 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 alue returned by
3b840 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f sqlite3_backup_
3b850 66 69 6e 69 73 68 20 69 73 20 5b 53 51 4c 49 54 finish is [SQLIT
3b860 45 5f 4f 4b 5d 20 69 66 20 6e 6f 20 65 72 72 6f E_OK] if no erro
3b870 72 0a 2a 2a 20 6f 63 63 75 72 72 65 64 2c 20 72 r.** occurred, r
3b880 65 67 61 72 64 6c 65 73 73 20 6f 72 20 77 68 65 egardless or whe
3b890 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 71 6c 69 ther or not sqli
3b8a0 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 te3_backup_step(
3b8b0 29 20 77 61 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 ) was called.**
3b8c0 61 20 73 75 66 66 69 63 69 65 6e 74 20 6e 75 6d a sufficient num
3b8d0 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 6f 20 ber of times to
3b8e0 63 6f 6d 70 6c 65 74 65 20 74 68 65 20 62 61 63 complete the bac
3b8f0 6b 75 70 20 6f 70 65 72 61 74 69 6f 6e 2e 20 4f kup operation. O
3b900 72 2c 20 69 66 0a 2a 2a 20 61 6e 20 6f 75 74 2d r, if.** an out-
3b910 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 of-memory condit
3b920 69 6f 6e 20 6f 72 20 49 4f 20 65 72 72 6f 72 20 ion or IO error
3b930 6f 63 63 75 72 65 64 20 64 75 72 69 6e 67 20 61 occured during a
3b940 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 call to.** sqli
3b950 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 te3_backup_step(
3b960 29 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 4e ) then [SQLITE_N
3b970 4f 4d 45 4d 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b OMEM] or an.** [
3b980 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 SQLITE_IOERR_ACC
3b990 45 53 53 20 7c 20 53 51 4c 49 54 45 5f 49 4f 45 ESS | SQLITE_IOE
3b9a0 52 52 5f 58 58 58 5d 20 65 72 72 6f 72 20 63 6f RR_XXX] error co
3b9b0 64 65 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 de.** is returne
3b9c0 64 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 20 d. In this case
3b9d0 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 61 the error code a
3b9e0 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 nd an error mess
3b9f0 61 67 65 20 61 72 65 0a 2a 2a 20 77 72 69 74 74 age are.** writt
3ba00 65 6e 20 74 6f 20 74 68 65 20 64 65 73 74 69 6e en to the destin
3ba10 61 74 69 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 ation [database
3ba20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a connection]..**.
3ba30 2a 2a 20 41 20 72 65 74 75 72 6e 20 6f 66 20 5b ** A return of [
3ba40 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 SQLITE_BUSY] or
3ba50 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5d 20 [SQLITE_LOCKED]
3ba60 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 62 61 63 from sqlite3_bac
3ba70 6b 75 70 5f 73 74 65 70 28 29 20 69 73 0a 2a 2a kup_step() is.**
3ba80 20 6e 6f 74 20 61 20 70 65 72 6d 61 6e 65 6e 74 not a permanent
3ba90 20 65 72 72 6f 72 20 61 6e 64 20 64 6f 65 73 20 error and does
3baa0 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 20 72 not affect the r
3bab0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 0a 2a eturn value of.*
3bac0 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 * sqlite3_backup
3bad0 5f 66 69 6e 69 73 68 28 29 2e 0a 2a 2a 0a 2a 2a _finish()..**.**
3bae0 20 3c 62 3e 73 71 6c 69 74 65 33 5f 62 61 63 6b <b>sqlite3_back
3baf0 75 70 5f 72 65 6d 61 69 6e 69 6e 67 28 29 2c 20 up_remaining(),
3bb00 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 70 sqlite3_backup_p
3bb10 61 67 65 63 6f 75 6e 74 28 29 3c 2f 62 3e 0a 2a agecount()</b>.*
3bb20 2a 0a 2a 2a 20 45 61 63 68 20 63 61 6c 6c 20 74 *.** Each call t
3bb30 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 o sqlite3_backup
3bb40 5f 73 74 65 70 28 29 20 73 65 74 73 20 74 77 6f _step() sets two
3bb50 20 76 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 values stored i
3bb60 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 62 79 20 nternally.** by
3bb70 61 6e 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b an [sqlite3_back
3bb80 75 70 5d 20 6f 62 6a 65 63 74 2e 20 54 68 65 20 up] object. The
3bb90 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 number of pages
3bba0 73 74 69 6c 6c 20 74 6f 20 62 65 20 62 61 63 6b still to be back
3bbb0 65 64 0a 2a 2a 20 75 70 2c 20 77 68 69 63 68 20 ed.** up, which
3bbc0 6d 61 79 20 62 65 20 71 75 65 72 69 65 64 20 62 may be queried b
3bbd0 79 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 y sqlite3_backup
3bbe0 5f 72 65 6d 61 69 6e 69 6e 67 28 29 2c 20 61 6e _remaining(), an
3bbf0 64 20 74 68 65 20 74 6f 74 61 6c 0a 2a 2a 20 6e d the total.** n
3bc00 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 69 umber of pages i
3bc10 6e 20 74 68 65 20 73 6f 75 72 63 65 20 64 61 74 n the source dat
3bc20 61 62 61 73 65 20 66 69 6c 65 2c 20 77 68 69 63 abase file, whic
3bc30 68 20 6d 61 79 20 62 65 20 71 75 65 72 69 65 64 h may be queried
3bc40 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 by.** sqlite3_b
3bc50 61 63 6b 75 70 5f 70 61 67 65 63 6f 75 6e 74 28 ackup_pagecount(
3bc60 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c )..**.** The val
3bc70 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 ues returned by
3bc80 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 these functions
3bc90 61 72 65 20 6f 6e 6c 79 20 75 70 64 61 74 65 64 are only updated
3bca0 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 by.** sqlite3_b
3bcb0 61 63 6b 75 70 5f 73 74 65 70 28 29 2e 20 49 66 ackup_step(). If
3bcc0 20 74 68 65 20 73 6f 75 72 63 65 20 64 61 74 61 the source data
3bcd0 62 61 73 65 20 69 73 20 6d 6f 64 69 66 69 65 64 base is modified
3bce0 20 64 75 72 69 6e 67 20 61 20 62 61 63 6b 75 70 during a backup
3bcf0 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 2c 20 74 .** operation, t
3bd00 68 65 6e 20 74 68 65 20 76 61 6c 75 65 73 20 61 hen the values a
3bd10 72 65 20 6e 6f 74 20 75 70 64 61 74 65 64 20 74 re not updated t
3bd20 6f 20 61 63 63 6f 75 6e 74 20 66 6f 72 20 61 6e o account for an
3bd30 79 20 65 78 74 72 61 0a 2a 2a 20 70 61 67 65 73 y extra.** pages
3bd40 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 62 65 that need to be
3bd50 20 75 70 64 61 74 65 64 20 6f 72 20 74 68 65 20 updated or the
3bd60 73 69 7a 65 20 6f 66 20 74 68 65 20 73 6f 75 72 size of the sour
3bd70 63 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 ce database file
3bd80 0a 2a 2a 20 63 68 61 6e 67 69 6e 67 2e 0a 2a 2a .** changing..**
3bd90 0a 2a 2a 20 3c 62 3e 43 6f 6e 63 75 72 72 65 6e .** <b>Concurren
3bda0 74 20 55 73 61 67 65 20 6f 66 20 44 61 74 61 62 t Usage of Datab
3bdb0 61 73 65 20 48 61 6e 64 6c 65 73 3c 2f 62 3e 0a ase Handles</b>.
3bdc0 2a 2a 0a 2a 2a 20 54 68 65 20 73 6f 75 72 63 65 **.** The source
3bdd0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
3bde0 63 74 69 6f 6e 5d 20 6d 61 79 20 62 65 20 75 73 ction] may be us
3bdf0 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 ed by the applic
3be00 61 74 69 6f 6e 20 66 6f 72 20 6f 74 68 65 72 0a ation for other.
3be10 2a 2a 20 70 75 72 70 6f 73 65 73 20 77 68 69 6c ** purposes whil
3be20 65 20 61 20 62 61 63 6b 75 70 20 6f 70 65 72 61 e a backup opera
3be30 74 69 6f 6e 20 69 73 20 75 6e 64 65 72 77 61 79 tion is underway
3be40 20 6f 72 20 62 65 69 6e 67 20 69 6e 69 74 69 61 or being initia
3be50 6c 69 7a 65 64 2e 0a 2a 2a 20 49 66 20 53 51 4c lized..** If SQL
3be60 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
3be70 61 6e 64 20 63 6f 6e 66 69 67 75 72 65 64 20 74 and configured t
3be80 6f 20 73 75 70 70 6f 72 74 20 74 68 72 65 61 64 o support thread
3be90 73 61 66 65 20 64 61 74 61 62 61 73 65 0a 2a 2a safe database.**
3bea0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2c 20 74 68 connections, th
3beb0 65 6e 20 74 68 65 20 73 6f 75 72 63 65 20 64 61 en the source da
3bec0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
3bed0 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20 63 6f n may be used co
3bee0 6e 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 66 72 ncurrently.** fr
3bef0 6f 6d 20 77 69 74 68 69 6e 20 6f 74 68 65 72 20 om within other
3bf00 74 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 48 threads..**.** H
3bf10 6f 77 65 76 65 72 2c 20 74 68 65 20 61 70 70 6c owever, the appl
3bf20 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 67 75 61 ication must gua
3bf30 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 65 20 rantee that the
3bf40 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 destination data
3bf50 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 base.** connecti
3bf60 6f 6e 20 68 61 6e 64 6c 65 20 69 73 20 6e 6f 74 on handle is not
3bf70 20 70 61 73 73 65 64 20 74 6f 20 61 6e 79 20 6f passed to any o
3bf80 74 68 65 72 20 41 50 49 20 28 62 79 20 61 6e 79 ther API (by any
3bf90 20 74 68 72 65 61 64 29 20 61 66 74 65 72 20 0a thread) after .
3bfa0 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 ** sqlite3_backu
3bfb0 70 5f 69 6e 69 74 28 29 20 69 73 20 63 61 6c 6c p_init() is call
3bfc0 65 64 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 ed and before th
3bfd0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 e corresponding
3bfe0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 call to.** sqlit
3bff0 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 e3_backup_finish
3c000 28 29 2e 20 55 6e 66 6f 72 74 75 6e 61 74 65 6c (). Unfortunatel
3c010 79 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f y SQLite does no
3c020 74 20 63 75 72 72 65 6e 74 6c 79 20 63 68 65 63 t currently chec
3c030 6b 0a 2a 2a 20 66 6f 72 20 74 68 69 73 2c 20 69 k.** for this, i
3c040 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
3c050 6e 20 64 6f 65 73 20 75 73 65 20 74 68 65 20 64 n does use the d
3c060 65 73 74 69 6e 61 74 69 6f 6e 20 5b 64 61 74 61 estination [data
3c070 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
3c080 0a 2a 2a 20 66 6f 72 20 73 6f 6d 65 20 6f 74 68 .** for some oth
3c090 65 72 20 70 75 72 70 6f 73 65 20 64 75 72 69 6e er purpose durin
3c0a0 67 20 61 20 62 61 63 6b 75 70 20 6f 70 65 72 61 g a backup opera
3c0b0 74 69 6f 6e 2c 20 74 68 69 6e 67 73 20 6d 61 79 tion, things may
3c0c0 20 61 70 70 65 61 72 20 74 6f 0a 2a 2a 20 77 6f appear to.** wo
3c0d0 72 6b 20 63 6f 72 72 65 63 74 6c 79 20 62 75 74 rk correctly but
3c0e0 20 69 6e 20 66 61 63 74 20 62 65 20 73 75 62 74 in fact be subt
3c0f0 6c 79 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 69 6e ly malfunctionin
3c100 67 2e 20 20 55 73 65 20 6f 66 20 74 68 65 0a 2a g. Use of the.*
3c110 2a 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 * destination da
3c120 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
3c130 6e 20 77 68 69 6c 65 20 61 20 62 61 63 6b 75 70 n while a backup
3c140 20 69 73 20 69 6e 20 70 72 6f 67 72 65 73 73 20 is in progress
3c150 6d 69 67 68 74 0a 2a 2a 20 61 6c 73 6f 20 63 61 might.** also ca
3c160 75 73 65 20 61 20 6d 75 74 65 78 20 64 65 61 64 use a mutex dead
3c170 6c 6f 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 75 72 74 lock..**.** Furt
3c180 68 65 72 6d 6f 72 65 2c 20 69 66 20 72 75 6e 6e hermore, if runn
3c190 69 6e 67 20 69 6e 20 5b 73 68 61 72 65 64 20 63 ing in [shared c
3c1a0 61 63 68 65 20 6d 6f 64 65 5d 2c 20 74 68 65 20 ache mode], the
3c1b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
3c1c0 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 20 74 68 .** guarantee th
3c1d0 61 74 20 74 68 65 20 73 68 61 72 65 64 20 63 61 at the shared ca
3c1e0 63 68 65 20 75 73 65 64 20 62 79 20 74 68 65 20 che used by the
3c1f0 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 destination data
3c200 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 base.** is not a
3c210 63 63 65 73 73 65 64 20 77 68 69 6c 65 20 74 68 ccessed while th
3c220 65 20 62 61 63 6b 75 70 20 69 73 20 72 75 6e 6e e backup is runn
3c230 69 6e 67 2e 20 49 6e 20 70 72 61 63 74 69 63 65 ing. In practice
3c240 20 74 68 69 73 20 6d 65 61 6e 73 0a 2a 2a 20 74 this means.** t
3c250 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 hat the applicat
3c260 69 6f 6e 20 6d 75 73 74 20 67 75 61 72 61 6e 74 ion must guarant
3c270 65 65 20 74 68 61 74 20 74 68 65 20 66 69 6c 65 ee that the file
3c280 2d 73 79 73 74 65 6d 20 66 69 6c 65 20 62 65 69 -system file bei
3c290 6e 67 20 0a 2a 2a 20 62 61 63 6b 65 64 20 75 70 ng .** backed up
3c2a0 20 74 6f 20 69 73 20 6e 6f 74 20 61 63 63 65 73 to is not acces
3c2b0 73 65 64 20 62 79 20 61 6e 79 20 63 6f 6e 6e 65 sed by any conne
3c2c0 63 74 69 6f 6e 20 77 69 74 68 69 6e 20 74 68 65 ction within the
3c2d0 20 70 72 6f 63 65 73 73 2c 0a 2a 2a 20 6e 6f 74 process,.** not
3c2e0 20 6a 75 73 74 20 74 68 65 20 73 70 65 63 69 66 just the specif
3c2f0 69 63 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 ic connection th
3c300 61 74 20 77 61 73 20 70 61 73 73 65 64 20 74 6f at was passed to
3c310 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f sqlite3_backup_
3c320 69 6e 69 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 init()..**.** Th
3c330 65 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 e [sqlite3_backu
3c340 70 5d 20 6f 62 6a 65 63 74 20 69 74 73 65 6c 66 p] object itself
3c350 20 69 73 20 70 61 72 74 69 61 6c 6c 79 20 74 68 is partially th
3c360 72 65 61 64 73 61 66 65 2e 20 4d 75 6c 74 69 70 readsafe. Multip
3c370 6c 65 20 0a 2a 2a 20 74 68 72 65 61 64 73 20 6d le .** threads m
3c380 61 79 20 73 61 66 65 6c 79 20 6d 61 6b 65 20 6d ay safely make m
3c390 75 6c 74 69 70 6c 65 20 63 6f 6e 63 75 72 72 65 ultiple concurre
3c3a0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 nt calls to sqli
3c3b0 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 te3_backup_step(
3c3c0 29 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 )..** However, t
3c3d0 68 65 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 he sqlite3_backu
3c3e0 70 5f 72 65 6d 61 69 6e 69 6e 67 28 29 20 61 6e p_remaining() an
3c3f0 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 d sqlite3_backup
3c400 5f 70 61 67 65 63 6f 75 6e 74 28 29 0a 2a 2a 20 _pagecount().**
3c410 41 50 49 73 20 61 72 65 20 6e 6f 74 20 73 74 72 APIs are not str
3c420 69 63 74 6c 79 20 73 70 65 61 6b 69 6e 67 20 74 ictly speaking t
3c430 68 72 65 61 64 73 61 66 65 2e 20 49 66 20 74 68 hreadsafe. If th
3c440 65 79 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 61 ey are invoked a
3c450 74 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 74 69 t the.** same ti
3c460 6d 65 20 61 73 20 61 6e 6f 74 68 65 72 20 74 68 me as another th
3c470 72 65 61 64 20 69 73 20 69 6e 76 6f 6b 69 6e 67 read is invoking
3c480 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f sqlite3_backup_
3c490 73 74 65 70 28 29 20 69 74 20 69 73 0a 2a 2a 20 step() it is.**
3c4a0 70 6f 73 73 69 62 6c 65 20 74 68 61 74 20 74 68 possible that th
3c4b0 65 79 20 72 65 74 75 72 6e 20 69 6e 76 61 6c 69 ey return invali
3c4c0 64 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 73 71 6c d values..*/.sql
3c4d0 69 74 65 33 5f 62 61 63 6b 75 70 20 2a 73 71 6c ite3_backup *sql
3c4e0 69 74 65 33 5f 62 61 63 6b 75 70 5f 69 6e 69 74 ite3_backup_init
3c4f0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 70 44 65 (. sqlite3 *pDe
3c500 73 74 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 st,
3c510 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 65 /* De
3c520 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 stination databa
3c530 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 se handle */. c
3c540 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 65 73 74 onst char *zDest
3c550 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 20 20 Name,
3c560 20 20 20 20 20 20 2f 2a 20 44 65 73 74 69 6e 61 /* Destina
3c570 74 69 6f 6e 20 64 61 74 61 62 61 73 65 20 6e 61 tion database na
3c580 6d 65 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 me */. sqlite3
3c590 2a 70 53 6f 75 72 63 65 2c 20 20 20 20 20 20 20 *pSource,
3c5a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
3c5b0 2a 20 53 6f 75 72 63 65 20 64 61 74 61 62 61 73 * Source databas
3c5c0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f e handle */. co
3c5d0 6e 73 74 20 63 68 61 72 20 2a 7a 53 6f 75 72 63 nst char *zSourc
3c5e0 65 4e 61 6d 65 20 20 20 20 20 20 20 20 20 20 20 eName
3c5f0 20 20 20 20 20 2f 2a 20 53 6f 75 72 63 65 20 64 /* Source d
3c600 61 74 61 62 61 73 65 20 6e 61 6d 65 20 2a 2f 0a atabase name */.
3c610 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 );.int sqlite3_b
3c620 61 63 6b 75 70 5f 73 74 65 70 28 73 71 6c 69 74 ackup_step(sqlit
3c630 65 33 5f 62 61 63 6b 75 70 20 2a 70 2c 20 69 6e e3_backup *p, in
3c640 74 20 6e 50 61 67 65 29 3b 0a 69 6e 74 20 73 71 t nPage);.int sq
3c650 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e lite3_backup_fin
3c660 69 73 68 28 73 71 6c 69 74 65 33 5f 62 61 63 6b ish(sqlite3_back
3c670 75 70 20 2a 70 29 3b 0a 69 6e 74 20 73 71 6c 69 up *p);.int sqli
3c680 74 65 33 5f 62 61 63 6b 75 70 5f 72 65 6d 61 69 te3_backup_remai
3c690 6e 69 6e 67 28 73 71 6c 69 74 65 33 5f 62 61 63 ning(sqlite3_bac
3c6a0 6b 75 70 20 2a 70 29 3b 0a 69 6e 74 20 73 71 6c kup *p);.int sql
3c6b0 69 74 65 33 5f 62 61 63 6b 75 70 5f 70 61 67 65 ite3_backup_page
3c6c0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 62 61 count(sqlite3_ba
3c6d0 63 6b 75 70 20 2a 70 29 3b 0a 0a 2f 2a 0a 2a 2a ckup *p);../*.**
3c6e0 20 43 41 50 49 33 52 45 46 3a 20 55 6e 6c 6f 63 CAPI3REF: Unloc
3c6f0 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 0a 2a k Notification.*
3c700 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
3c710 2a 0a 2a 2a 20 57 68 65 6e 20 72 75 6e 6e 69 6e *.** When runnin
3c720 67 20 69 6e 20 73 68 61 72 65 64 2d 63 61 63 68 g in shared-cach
3c730 65 20 6d 6f 64 65 2c 20 61 20 64 61 74 61 62 61 e mode, a databa
3c740 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 6d 61 79 se operation may
3c750 20 66 61 69 6c 20 77 69 74 68 0a 2a 2a 20 61 6e fail with.** an
3c760 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5d [SQLITE_LOCKED]
3c770 20 65 72 72 6f 72 20 69 66 20 74 68 65 20 72 65 error if the re
3c780 71 75 69 72 65 64 20 6c 6f 63 6b 73 20 6f 6e 20 quired locks on
3c790 74 68 65 20 73 68 61 72 65 64 2d 63 61 63 68 65 the shared-cache
3c7a0 20 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 64 75 61 or.** individua
3c7b0 6c 20 74 61 62 6c 65 73 20 77 69 74 68 69 6e 20 l tables within
3c7c0 74 68 65 20 73 68 61 72 65 64 2d 63 61 63 68 65 the shared-cache
3c7d0 20 63 61 6e 6e 6f 74 20 62 65 20 6f 62 74 61 69 cannot be obtai
3c7e0 6e 65 64 2e 20 53 65 65 0a 2a 2a 20 5b 53 51 4c ned. See.** [SQL
3c7f0 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 ite Shared-Cache
3c800 20 4d 6f 64 65 5d 20 66 6f 72 20 61 20 64 65 73 Mode] for a des
3c810 63 72 69 70 74 69 6f 6e 20 6f 66 20 73 68 61 72 cription of shar
3c820 65 64 2d 63 61 63 68 65 20 6c 6f 63 6b 69 6e 67 ed-cache locking
3c830 2e 20 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 6d . .** This API m
3c840 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 ay be used to re
3c850 67 69 73 74 65 72 20 61 20 63 61 6c 6c 62 61 63 gister a callbac
3c860 6b 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 k that SQLite wi
3c870 6c 6c 20 69 6e 76 6f 6b 65 20 0a 2a 2a 20 77 68 ll invoke .** wh
3c880 65 6e 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f en the connectio
3c890 6e 20 63 75 72 72 65 6e 74 6c 79 20 68 6f 6c 64 n currently hold
3c8a0 69 6e 67 20 74 68 65 20 72 65 71 75 69 72 65 64 ing the required
3c8b0 20 6c 6f 63 6b 20 72 65 6c 69 6e 71 75 69 73 68 lock relinquish
3c8c0 65 73 20 69 74 2e 0a 2a 2a 20 54 68 69 73 20 41 es it..** This A
3c8d0 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c PI is only avail
3c8e0 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 able if the libr
3c8f0 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 ary was compiled
3c900 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 with the.** [SQ
3c910 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 55 4e 4c 4f LITE_ENABLE_UNLO
3c920 43 4b 5f 4e 4f 54 49 46 59 5d 20 43 2d 70 72 65 CK_NOTIFY] C-pre
3c930 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c processor symbol
3c940 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 defined..**.**
3c950 53 65 65 20 41 6c 73 6f 3a 20 5b 55 73 69 6e 67 See Also: [Using
3c960 20 74 68 65 20 53 51 4c 69 74 65 20 55 6e 6c 6f the SQLite Unlo
3c970 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 ck Notification
3c980 46 65 61 74 75 72 65 5d 2e 0a 2a 2a 0a 2a 2a 20 Feature]..**.**
3c990 53 68 61 72 65 64 2d 63 61 63 68 65 20 6c 6f 63 Shared-cache loc
3c9a0 6b 73 20 61 72 65 20 72 65 6c 65 61 73 65 64 20 ks are released
3c9b0 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 when a database
3c9c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6f 6e 63 6c connection concl
3c9d0 75 64 65 73 0a 2a 2a 20 69 74 73 20 63 75 72 72 udes.** its curr
3c9e0 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c ent transaction,
3c9f0 20 65 69 74 68 65 72 20 62 79 20 63 6f 6d 6d 69 either by commi
3ca00 74 74 69 6e 67 20 69 74 20 6f 72 20 72 6f 6c 6c tting it or roll
3ca10 69 6e 67 20 69 74 20 62 61 63 6b 2e 20 0a 2a 2a ing it back. .**
3ca20 0a 2a 2a 20 57 68 65 6e 20 61 20 63 6f 6e 6e 65 .** When a conne
3ca30 63 74 69 6f 6e 20 28 6b 6e 6f 77 6e 20 61 73 20 ction (known as
3ca40 74 68 65 20 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e the blocked conn
3ca50 65 63 74 69 6f 6e 29 20 66 61 69 6c 73 20 74 6f ection) fails to
3ca60 20 6f 62 74 61 69 6e 20 61 0a 2a 2a 20 73 68 61 obtain a.** sha
3ca70 72 65 64 2d 63 61 63 68 65 20 6c 6f 63 6b 20 61 red-cache lock a
3ca80 6e 64 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 nd SQLITE_LOCKED
3ca90 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 is returned to
3caa0 74 68 65 20 63 61 6c 6c 65 72 2c 20 74 68 65 0a the caller, the.
3cab0 2a 2a 20 69 64 65 6e 74 69 74 79 20 6f 66 20 74 ** identity of t
3cac0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
3cad0 65 63 74 69 6f 6e 20 28 74 68 65 20 62 6c 6f 63 ection (the bloc
3cae0 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 69 6f 6e 29 king connection)
3caf0 20 74 68 61 74 0a 2a 2a 20 68 61 73 20 6c 6f 63 that.** has loc
3cb00 6b 65 64 20 74 68 65 20 72 65 71 75 69 72 65 64 ked the required
3cb10 20 72 65 73 6f 75 72 63 65 20 69 73 20 73 74 6f resource is sto
3cb20 72 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 20 red internally.
3cb30 41 66 74 65 72 20 61 6e 20 0a 2a 2a 20 61 70 70 After an .** app
3cb40 6c 69 63 61 74 69 6f 6e 20 72 65 63 65 69 76 65 lication receive
3cb50 73 20 61 6e 20 53 51 4c 49 54 45 5f 4c 4f 43 4b s an SQLITE_LOCK
3cb60 45 44 20 65 72 72 6f 72 2c 20 69 74 20 6d 61 79 ED error, it may
3cb70 20 63 61 6c 6c 20 74 68 65 0a 2a 2a 20 73 71 6c call the.** sql
3cb80 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 ite3_unlock_noti
3cb90 66 79 28 29 20 6d 65 74 68 6f 64 20 77 69 74 68 fy() method with
3cba0 20 74 68 65 20 62 6c 6f 63 6b 65 64 20 63 6f 6e the blocked con
3cbb0 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 61 nection handle a
3cbc0 73 20 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 s .** the first
3cbd0 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 65 67 69 argument to regi
3cbe0 73 74 65 72 20 66 6f 72 20 61 20 63 61 6c 6c 62 ster for a callb
3cbf0 61 63 6b 20 74 68 61 74 20 77 69 6c 6c 20 62 65 ack that will be
3cc00 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e invoked.** when
3cc10 20 74 68 65 20 62 6c 6f 63 6b 69 6e 67 20 63 6f the blocking co
3cc20 6e 6e 65 63 74 69 6f 6e 73 20 63 75 72 72 65 6e nnections curren
3cc30 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 t transaction is
3cc40 20 63 6f 6e 63 6c 75 64 65 64 2e 20 54 68 65 0a concluded. The.
3cc50 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 ** callback is i
3cc60 6e 76 6f 6b 65 64 20 66 72 6f 6d 20 77 69 74 68 nvoked from with
3cc70 69 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f in the [sqlite3_
3cc80 73 74 65 70 5d 20 6f 72 20 5b 73 71 6c 69 74 65 step] or [sqlite
3cc90 33 5f 63 6c 6f 73 65 5d 0a 2a 2a 20 63 61 6c 6c 3_close].** call
3cca0 20 74 68 61 74 20 63 6f 6e 63 6c 75 64 65 73 20 that concludes
3ccb0 74 68 65 20 62 6c 6f 63 6b 69 6e 67 20 63 6f 6e the blocking con
3ccc0 6e 65 63 74 69 6f 6e 73 20 74 72 61 6e 73 61 63 nections transac
3ccd0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 tion..**.** If s
3cce0 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f qlite3_unlock_no
3ccf0 74 69 66 79 28 29 20 69 73 20 63 61 6c 6c 65 64 tify() is called
3cd00 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 in a multi-thre
3cd10 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e aded application
3cd20 2c 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 61 20 ,.** there is a
3cd30 63 68 61 6e 63 65 20 74 68 61 74 20 74 68 65 20 chance that the
3cd40 62 6c 6f 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 blocking connect
3cd50 69 6f 6e 20 77 69 6c 6c 20 68 61 76 65 20 61 6c ion will have al
3cd60 72 65 61 64 79 0a 2a 2a 20 63 6f 6e 63 6c 75 64 ready.** conclud
3cd70 65 64 20 69 74 73 20 74 72 61 6e 73 61 63 74 69 ed its transacti
3cd80 6f 6e 20 62 79 20 74 68 65 20 74 69 6d 65 20 73 on by the time s
3cd90 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f qlite3_unlock_no
3cda0 74 69 66 79 28 29 20 69 73 20 69 6e 76 6f 6b 65 tify() is invoke
3cdb0 64 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 68 61 d..** If this ha
3cdc0 70 70 65 6e 73 2c 20 74 68 65 6e 20 74 68 65 20 ppens, then the
3cdd0 73 70 65 63 69 66 69 65 64 20 63 61 6c 6c 62 61 specified callba
3cde0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6d ck is invoked im
3cdf0 6d 65 64 69 61 74 65 6c 79 2c 0a 2a 2a 20 66 72 mediately,.** fr
3ce00 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 63 61 om within the ca
3ce10 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 6e ll to sqlite3_un
3ce20 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 2e 0a 2a lock_notify()..*
3ce30 2a 0a 2a 2a 20 49 66 20 74 68 65 20 62 6c 6f 63 *.** If the bloc
3ce40 6b 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ked connection i
3ce50 73 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 s attempting to
3ce60 6f 62 74 61 69 6e 20 61 20 77 72 69 74 65 2d 6c obtain a write-l
3ce70 6f 63 6b 20 6f 6e 20 61 0a 2a 2a 20 73 68 61 72 ock on a.** shar
3ce80 65 64 2d 63 61 63 68 65 20 74 61 62 6c 65 2c 20 ed-cache table,
3ce90 61 6e 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e and more than on
3cea0 65 20 6f 74 68 65 72 20 63 6f 6e 6e 65 63 74 69 e other connecti
3ceb0 6f 6e 20 63 75 72 72 65 6e 74 6c 79 20 68 6f 6c on currently hol
3cec0 64 73 0a 2a 2a 20 61 20 72 65 61 64 2d 6c 6f 63 ds.** a read-loc
3ced0 6b 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 74 61 k on the same ta
3cee0 62 6c 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 ble, then SQLite
3cef0 20 61 72 62 69 74 72 61 72 69 6c 79 20 73 65 6c arbitrarily sel
3cf00 65 63 74 73 20 6f 6e 65 20 6f 66 20 0a 2a 2a 20 ects one of .**
3cf10 74 68 65 20 6f 74 68 65 72 20 63 6f 6e 6e 65 63 the other connec
3cf20 74 69 6f 6e 73 20 74 6f 20 75 73 65 20 61 73 20 tions to use as
3cf30 74 68 65 20 62 6c 6f 63 6b 69 6e 67 20 63 6f 6e the blocking con
3cf40 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 nection..**.** T
3cf50 68 65 72 65 20 6d 61 79 20 62 65 20 61 74 20 6d here may be at m
3cf60 6f 73 74 20 6f 6e 65 20 75 6e 6c 6f 63 6b 2d 6e ost one unlock-n
3cf70 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 72 otify callback r
3cf80 65 67 69 73 74 65 72 65 64 20 62 79 20 61 20 0a egistered by a .
3cf90 2a 2a 20 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e 65 ** blocked conne
3cfa0 63 74 69 6f 6e 2e 20 49 66 20 73 71 6c 69 74 65 ction. If sqlite
3cfb0 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 3_unlock_notify(
3cfc0 29 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e ) is called when
3cfd0 20 74 68 65 0a 2a 2a 20 62 6c 6f 63 6b 65 64 20 the.** blocked
3cfe0 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6c 72 65 61 connection alrea
3cff0 64 79 20 68 61 73 20 61 20 72 65 67 69 73 74 65 dy has a registe
3d000 72 65 64 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 red unlock-notif
3d010 79 20 63 61 6c 6c 62 61 63 6b 2c 0a 2a 2a 20 74 y callback,.** t
3d020 68 65 6e 20 74 68 65 20 6e 65 77 20 63 61 6c 6c hen the new call
3d030 62 61 63 6b 20 72 65 70 6c 61 63 65 73 20 74 68 back replaces th
3d040 65 20 6f 6c 64 2e 20 49 66 20 73 71 6c 69 74 65 e old. If sqlite
3d050 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 3_unlock_notify(
3d060 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 77 ) is.** called w
3d070 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 ith a NULL point
3d080 65 72 20 61 73 20 69 74 73 20 73 65 63 6f 6e 64 er as its second
3d090 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 65 6e 20 argument, then
3d0a0 61 6e 79 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 any existing.**
3d0b0 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 unlock-notify ca
3d0c0 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e 63 65 6c llback is cancel
3d0d0 6c 65 64 2e 20 54 68 65 20 62 6c 6f 63 6b 65 64 led. The blocked
3d0e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 0a 2a 2a connections .**
3d0f0 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 unlock-notify c
3d100 61 6c 6c 62 61 63 6b 20 6d 61 79 20 61 6c 73 6f allback may also
3d110 20 62 65 20 63 61 6e 63 65 6c 65 64 20 62 79 20 be canceled by
3d120 63 6c 6f 73 69 6e 67 20 74 68 65 20 62 6c 6f 63 closing the bloc
3d130 6b 65 64 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f ked.** connectio
3d140 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 n using [sqlite3
3d150 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a _close()]..**.**
3d160 20 54 68 65 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 The unlock-noti
3d170 66 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e fy callback is n
3d180 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 49 66 ot reentrant. If
3d190 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 an application
3d1a0 69 6e 76 6f 6b 65 73 0a 2a 2a 20 61 6e 79 20 73 invokes.** any s
3d1b0 71 6c 69 74 65 33 5f 78 78 78 20 41 50 49 20 66 qlite3_xxx API f
3d1c0 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 77 69 unctions from wi
3d1d0 74 68 69 6e 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e thin an unlock-n
3d1e0 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b 2c 20 otify callback,
3d1f0 61 0a 2a 2a 20 63 72 61 73 68 20 6f 72 20 64 65 a.** crash or de
3d200 61 64 6c 6f 63 6b 20 6d 61 79 20 62 65 20 74 68 adlock may be th
3d210 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 e result..**.**
3d220 55 6e 6c 65 73 73 20 64 65 61 64 6c 6f 63 6b 20 Unless deadlock
3d230 69 73 20 64 65 74 65 63 74 65 64 20 28 73 65 65 is detected (see
3d240 20 62 65 6c 6f 77 29 2c 20 73 71 6c 69 74 65 33 below), sqlite3
3d250 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 _unlock_notify()
3d260 20 61 6c 77 61 79 73 0a 2a 2a 20 72 65 74 75 72 always.** retur
3d270 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a ns SQLITE_OK..**
3d280 0a 2a 2a 20 3c 62 3e 43 61 6c 6c 62 61 63 6b 20 .** <b>Callback
3d290 49 6e 76 6f 63 61 74 69 6f 6e 20 44 65 74 61 69 Invocation Detai
3d2a0 6c 73 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 ls</b>.**.** Whe
3d2b0 6e 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 n an unlock-noti
3d2c0 66 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 72 fy callback is r
3d2d0 65 67 69 73 74 65 72 65 64 2c 20 74 68 65 20 61 egistered, the a
3d2e0 70 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 pplication provi
3d2f0 64 65 73 20 61 20 0a 2a 2a 20 73 69 6e 67 6c 65 des a .** single
3d300 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 74 void* pointer t
3d310 68 61 74 20 69 73 20 70 61 73 73 65 64 20 74 6f hat is passed to
3d320 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 68 the callback wh
3d330 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 en it is invoked
3d340 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 ..** However, th
3d350 65 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 74 e signature of t
3d360 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 he callback func
3d370 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 53 51 4c 69 tion allows SQLi
3d380 74 65 20 74 6f 20 70 61 73 73 0a 2a 2a 20 69 74 te to pass.** it
3d390 20 61 6e 20 61 72 72 61 79 20 6f 66 20 76 6f 69 an array of voi
3d3a0 64 2a 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 d* context point
3d3b0 65 72 73 2e 20 54 68 65 20 66 69 72 73 74 20 61 ers. The first a
3d3c0 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 rgument passed t
3d3d0 6f 0a 2a 2a 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e o.** an unlock-n
3d3e0 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 69 otify callback i
3d3f0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
3d400 6e 20 61 72 72 61 79 20 6f 66 20 76 6f 69 64 2a n array of void*
3d410 20 70 6f 69 6e 74 65 72 73 2c 0a 2a 2a 20 61 6e pointers,.** an
3d420 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 d the second is
3d430 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6e the number of en
3d440 74 72 69 65 73 20 69 6e 20 74 68 65 20 61 72 72 tries in the arr
3d450 61 79 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 ay..**.** When a
3d460 20 62 6c 6f 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 blocking connec
3d470 74 69 6f 6e 73 20 74 72 61 6e 73 61 63 74 69 6f tions transactio
3d480 6e 20 69 73 20 63 6f 6e 63 6c 75 64 65 64 2c 20 n is concluded,
3d490 74 68 65 72 65 20 6d 61 79 20 62 65 0a 2a 2a 20 there may be.**
3d4a0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 62 6c more than one bl
3d4b0 6f 63 6b 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e ocked connection
3d4c0 20 74 68 61 74 20 68 61 73 20 72 65 67 69 73 74 that has regist
3d4d0 65 72 65 64 20 66 6f 72 20 61 6e 20 75 6e 6c 6f ered for an unlo
3d4e0 63 6b 2d 6e 6f 74 69 66 79 0a 2a 2a 20 63 61 6c ck-notify.** cal
3d4f0 6c 62 61 63 6b 2e 20 49 66 20 74 77 6f 20 6f 72 lback. If two or
3d500 20 6d 6f 72 65 20 73 75 63 68 20 62 6c 6f 63 6b more such block
3d510 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 68 ed connections h
3d520 61 76 65 20 73 70 65 63 69 66 69 65 64 20 74 68 ave specified th
3d530 65 0a 2a 2a 20 73 61 6d 65 20 63 61 6c 6c 62 61 e.** same callba
3d540 63 6b 20 66 75 6e 63 74 69 6f 6e 2c 20 74 68 65 ck function, the
3d550 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 n instead of inv
3d560 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 oking the callba
3d570 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d ck function.** m
3d580 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 2c 20 69 ultiple times, i
3d590 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 t is invoked onc
3d5a0 65 20 77 69 74 68 20 74 68 65 20 73 65 74 20 6f e with the set o
3d5b0 66 20 76 6f 69 64 2a 20 63 6f 6e 74 65 78 74 20 f void* context
3d5c0 70 6f 69 6e 74 65 72 73 0a 2a 2a 20 73 70 65 63 pointers.** spec
3d5d0 69 66 69 65 64 20 62 79 20 74 68 65 20 62 6c 6f ified by the blo
3d5e0 63 6b 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 cked connections
3d5f0 20 62 75 6e 64 6c 65 64 20 74 6f 67 65 74 68 65 bundled togethe
3d600 72 20 69 6e 74 6f 20 61 6e 20 61 72 72 61 79 2e r into an array.
3d610 0a 2a 2a 20 54 68 69 73 20 67 69 76 65 73 20 74 .** This gives t
3d620 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 61 he application a
3d630 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 20 74 6f n opportunity to
3d640 20 70 72 69 6f 72 69 74 69 7a 65 20 61 6e 79 20 prioritize any
3d650 61 63 74 69 6f 6e 73 20 0a 2a 2a 20 72 65 6c 61 actions .** rela
3d660 74 65 64 20 74 6f 20 74 68 65 20 73 65 74 20 6f ted to the set o
3d670 66 20 75 6e 62 6c 6f 63 6b 65 64 20 64 61 74 61 f unblocked data
3d680 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
3d690 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 44 65 61 64 6c ..**.** <b>Deadl
3d6a0 6f 63 6b 20 44 65 74 65 63 74 69 6f 6e 3c 2f 62 ock Detection</b
3d6b0 3e 0a 2a 2a 0a 2a 2a 20 41 73 73 75 6d 69 6e 67 >.**.** Assuming
3d6c0 20 74 68 61 74 20 61 66 74 65 72 20 72 65 67 69 that after regi
3d6d0 73 74 65 72 69 6e 67 20 66 6f 72 20 61 6e 20 75 stering for an u
3d6e0 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c nlock-notify cal
3d6f0 6c 62 61 63 6b 20 61 20 0a 2a 2a 20 64 61 74 61 lback a .** data
3d700 62 61 73 65 20 77 61 69 74 73 20 66 6f 72 20 74 base waits for t
3d710 68 65 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 he callback to b
3d720 65 20 69 73 73 75 65 64 20 62 65 66 6f 72 65 20 e issued before
3d730 74 61 6b 69 6e 67 20 61 6e 79 20 66 75 72 74 68 taking any furth
3d740 65 72 0a 2a 2a 20 61 63 74 69 6f 6e 20 28 61 20 er.** action (a
3d750 72 65 61 73 6f 6e 61 62 6c 65 20 61 73 73 75 6d reasonable assum
3d760 70 74 69 6f 6e 29 2c 20 74 68 65 6e 20 75 73 69 ption), then usi
3d770 6e 67 20 74 68 69 73 20 41 50 49 20 6d 61 79 20 ng this API may
3d780 63 61 75 73 65 20 74 68 65 0a 2a 2a 20 61 70 70 cause the.** app
3d790 6c 69 63 61 74 69 6f 6e 20 74 6f 20 64 65 61 64 lication to dead
3d7a0 6c 6f 63 6b 2e 20 46 6f 72 20 65 78 61 6d 70 6c lock. For exampl
3d7b0 65 2c 20 69 66 20 63 6f 6e 6e 65 63 74 69 6f 6e e, if connection
3d7c0 20 58 20 69 73 20 77 61 69 74 69 6e 67 20 66 6f X is waiting fo
3d7d0 72 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 r.** connection
3d7e0 59 27 73 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 Y's transaction
3d7f0 74 6f 20 62 65 20 63 6f 6e 63 6c 75 64 65 64 2c to be concluded,
3d800 20 61 6e 64 20 73 69 6d 69 6c 61 72 6c 79 20 63 and similarly c
3d810 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 59 20 69 onnection.** Y i
3d820 73 20 77 61 69 74 69 6e 67 20 6f 6e 20 63 6f 6e s waiting on con
3d830 6e 65 63 74 69 6f 6e 20 58 27 73 20 74 72 61 6e nection X's tran
3d840 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 6e 65 saction, then ne
3d850 69 74 68 65 72 20 63 6f 6e 6e 65 63 74 69 6f 6e ither connection
3d860 0a 2a 2a 20 77 69 6c 6c 20 70 72 6f 63 65 65 64 .** will proceed
3d870 20 61 6e 64 20 74 68 65 20 73 79 73 74 65 6d 20 and the system
3d880 6d 61 79 20 72 65 6d 61 69 6e 20 64 65 61 64 6c may remain deadl
3d890 6f 63 6b 65 64 20 69 6e 64 65 66 69 6e 69 74 65 ocked indefinite
3d8a0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f ly..**.** To avo
3d8b0 69 64 20 74 68 69 73 20 73 63 65 6e 61 72 69 6f id this scenario
3d8c0 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 75 6e , the sqlite3_un
3d8d0 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 20 70 65 lock_notify() pe
3d8e0 72 66 6f 72 6d 73 20 64 65 61 64 6c 6f 63 6b 0a rforms deadlock.
3d8f0 2a 2a 20 64 65 74 65 63 74 69 6f 6e 2e 20 49 66 ** detection. If
3d900 20 61 20 67 69 76 65 6e 20 63 61 6c 6c 20 74 6f a given call to
3d910 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f sqlite3_unlock_
3d920 6e 6f 74 69 66 79 28 29 20 77 6f 75 6c 64 20 70 notify() would p
3d930 75 74 20 74 68 65 0a 2a 2a 20 73 79 73 74 65 6d ut the.** system
3d940 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 65 64 in a deadlocked
3d950 20 73 74 61 74 65 2c 20 74 68 65 6e 20 53 51 4c state, then SQL
3d960 49 54 45 5f 4c 4f 43 4b 45 44 20 69 73 20 72 65 ITE_LOCKED is re
3d970 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 0a 2a 2a turned and no.**
3d980 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 unlock-notify c
3d990 61 6c 6c 62 61 63 6b 20 69 73 20 72 65 67 69 73 allback is regis
3d9a0 74 65 72 65 64 2e 20 54 68 65 20 73 79 73 74 65 tered. The syste
3d9b0 6d 20 69 73 20 73 61 69 64 20 74 6f 20 62 65 20 m is said to be
3d9c0 69 6e 0a 2a 2a 20 61 20 64 65 61 64 6c 6f 63 6b in.** a deadlock
3d9d0 65 64 20 73 74 61 74 65 20 69 66 20 63 6f 6e 6e ed state if conn
3d9e0 65 63 74 69 6f 6e 20 41 20 68 61 73 20 72 65 67 ection A has reg
3d9f0 69 73 74 65 72 65 64 20 66 6f 72 20 61 6e 20 75 istered for an u
3da00 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 0a 2a 2a 20 nlock-notify.**
3da10 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 74 68 65 20 callback on the
3da20 63 6f 6e 63 6c 75 73 69 6f 6e 20 6f 66 20 63 6f conclusion of co
3da30 6e 6e 65 63 74 69 6f 6e 20 42 27 73 20 74 72 61 nnection B's tra
3da40 6e 73 61 63 74 69 6f 6e 2c 20 61 6e 64 20 63 6f nsaction, and co
3da50 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 42 20 68 61 nnection.** B ha
3da60 73 20 69 74 73 65 6c 66 20 72 65 67 69 73 74 65 s itself registe
3da70 72 65 64 20 66 6f 72 20 61 6e 20 75 6e 6c 6f 63 red for an unloc
3da80 6b 2d 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 k-notify callbac
3da90 6b 20 77 68 65 6e 20 63 6f 6e 6e 65 63 74 69 6f k when connectio
3daa0 6e 0a 2a 2a 20 41 27 73 20 74 72 61 6e 73 61 63 n.** A's transac
3dab0 74 69 6f 6e 20 69 73 20 63 6f 6e 63 6c 75 64 65 tion is conclude
3dac0 64 2e 20 49 6e 64 69 72 65 63 74 20 64 65 61 64 d. Indirect dead
3dad0 6c 6f 63 6b 20 69 73 20 61 6c 73 6f 20 64 65 74 lock is also det
3dae0 65 63 74 65 64 2c 20 73 6f 0a 2a 2a 20 74 68 65 ected, so.** the
3daf0 20 73 79 73 74 65 6d 20 69 73 20 61 6c 73 6f 20 system is also
3db00 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 considered to be
3db10 20 64 65 61 64 6c 6f 63 6b 65 64 20 69 66 20 63 deadlocked if c
3db20 6f 6e 6e 65 63 74 69 6f 6e 20 42 20 68 61 73 0a onnection B has.
3db30 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 66 6f ** registered fo
3db40 72 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 r an unlock-noti
3db50 66 79 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 74 fy callback on t
3db60 68 65 20 63 6f 6e 63 6c 75 73 69 6f 6e 20 6f 66 he conclusion of
3db70 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 connection.** C
3db80 27 73 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 's transaction,
3db90 77 68 65 72 65 20 63 6f 6e 6e 65 63 74 69 6f 6e where connection
3dba0 20 43 20 69 73 20 77 61 69 74 69 6e 67 20 6f 6e C is waiting on
3dbb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 41 2e 20 41 connection A. A
3dbc0 6e 79 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 ny.** number of
3dbd0 6c 65 76 65 6c 73 20 6f 66 20 69 6e 64 69 72 65 levels of indire
3dbe0 63 74 69 6f 6e 20 61 72 65 20 61 6c 6c 6f 77 65 ction are allowe
3dbf0 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 d..**.** <b>The
3dc00 22 44 52 4f 50 20 54 41 42 4c 45 22 20 45 78 63 "DROP TABLE" Exc
3dc10 65 70 74 69 6f 6e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a eption</b>.**.**
3dc20 20 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 When a call to
3dc30 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
3dc40 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f returns SQLITE_
3dc50 4c 4f 43 4b 45 44 2c 20 69 74 20 69 73 20 61 6c LOCKED, it is al
3dc60 6d 6f 73 74 20 0a 2a 2a 20 61 6c 77 61 79 73 20 most .** always
3dc70 61 70 70 72 6f 70 72 69 61 74 65 20 74 6f 20 63 appropriate to c
3dc80 61 6c 6c 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f all sqlite3_unlo
3dc90 63 6b 5f 6e 6f 74 69 66 79 28 29 2e 20 54 68 65 ck_notify(). The
3dca0 72 65 20 69 73 20 68 6f 77 65 76 65 72 2c 0a 2a re is however,.*
3dcb0 2a 20 6f 6e 65 20 65 78 63 65 70 74 69 6f 6e 2e * one exception.
3dcc0 20 57 68 65 6e 20 65 78 65 63 75 74 69 6e 67 20 When executing
3dcd0 61 20 22 44 52 4f 50 20 54 41 42 4c 45 22 20 6f a "DROP TABLE" o
3dce0 72 20 22 44 52 4f 50 20 49 4e 44 45 58 22 20 73 r "DROP INDEX" s
3dcf0 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 53 51 4c tatement,.** SQL
3dd00 69 74 65 20 63 68 65 63 6b 73 20 69 66 20 74 68 ite checks if th
3dd10 65 72 65 20 61 72 65 20 61 6e 79 20 63 75 72 72 ere are any curr
3dd20 65 6e 74 6c 79 20 65 78 65 63 75 74 69 6e 67 20 ently executing
3dd30 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 SELECT statement
3dd40 73 0a 2a 2a 20 74 68 61 74 20 62 65 6c 6f 6e 67 s.** that belong
3dd50 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6e to the same con
3dd60 6e 65 63 74 69 6f 6e 2e 20 49 66 20 74 68 65 72 nection. If ther
3dd70 65 20 61 72 65 2c 20 53 51 4c 49 54 45 5f 4c 4f e are, SQLITE_LO
3dd80 43 4b 45 44 20 69 73 0a 2a 2a 20 72 65 74 75 72 CKED is.** retur
3dd90 6e 65 64 2e 20 49 6e 20 74 68 69 73 20 63 61 73 ned. In this cas
3dda0 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 22 62 e there is no "b
3ddb0 6c 6f 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 69 locking connecti
3ddc0 6f 6e 22 2c 20 73 6f 20 69 6e 76 6f 6b 69 6e 67 on", so invoking
3ddd0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f .** sqlite3_unlo
3dde0 63 6b 5f 6e 6f 74 69 66 79 28 29 20 72 65 73 75 ck_notify() resu
3ddf0 6c 74 73 20 69 6e 20 74 68 65 20 75 6e 6c 6f 63 lts in the unloc
3de00 6b 2d 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 k-notify callbac
3de10 6b 20 62 65 69 6e 67 0a 2a 2a 20 69 6e 76 6f 6b k being.** invok
3de20 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 20 ed immediately.
3de30 49 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 If the applicati
3de40 6f 6e 20 74 68 65 6e 20 72 65 2d 61 74 74 65 6d on then re-attem
3de50 70 74 73 20 74 68 65 20 22 44 52 4f 50 20 54 41 pts the "DROP TA
3de60 42 4c 45 22 0a 2a 2a 20 6f 72 20 22 44 52 4f 50 BLE".** or "DROP
3de70 20 49 4e 44 45 58 22 20 71 75 65 72 79 2c 20 61 INDEX" query, a
3de80 6e 20 69 6e 66 69 6e 69 74 65 20 6c 6f 6f 70 20 n infinite loop
3de90 6d 69 67 68 74 20 62 65 20 74 68 65 20 72 65 73 might be the res
3dea0 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 77 ult..**.** One w
3deb0 61 79 20 61 72 6f 75 6e 64 20 74 68 69 73 20 70 ay around this p
3dec0 72 6f 62 6c 65 6d 20 69 73 20 74 6f 20 63 68 65 roblem is to che
3ded0 63 6b 20 74 68 65 20 65 78 74 65 6e 64 65 64 20 ck the extended
3dee0 65 72 72 6f 72 20 63 6f 64 65 20 72 65 74 75 72 error code retur
3def0 6e 65 64 0a 2a 2a 20 62 79 20 61 6e 20 73 71 6c ned.** by an sql
3df00 69 74 65 33 5f 73 74 65 70 28 29 20 63 61 6c 6c ite3_step() call
3df10 2e 20 49 66 20 74 68 65 72 65 20 69 73 20 61 20 . If there is a
3df20 62 6c 6f 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 blocking connect
3df30 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a ion, then the.**
3df40 20 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 extended error
3df50 63 6f 64 65 20 69 73 20 73 65 74 20 74 6f 20 53 code is set to S
3df60 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 QLITE_LOCKED_SHA
3df70 52 45 44 43 41 43 48 45 2e 20 4f 74 68 65 72 77 REDCACHE. Otherw
3df80 69 73 65 2c 20 69 6e 0a 2a 2a 20 74 68 65 20 73 ise, in.** the s
3df90 70 65 63 69 61 6c 20 22 44 52 4f 50 20 54 41 42 pecial "DROP TAB
3dfa0 4c 45 2f 49 4e 44 45 58 22 20 63 61 73 65 2c 20 LE/INDEX" case,
3dfb0 74 68 65 20 65 78 74 65 6e 64 65 64 20 65 72 72 the extended err
3dfc0 6f 72 20 63 6f 64 65 20 69 73 20 6a 75 73 74 20 or code is just
3dfd0 0a 2a 2a 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 .** SQLITE_LOCKE
3dfe0 44 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 D..*/.int sqlite
3dff0 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 3_unlock_notify(
3e000 0a 20 20 73 71 6c 69 74 65 33 20 2a 70 42 6c 6f . sqlite3 *pBlo
3e010 63 6b 65 64 2c 20 20 20 20 20 20 20 20 20 20 20 cked,
3e020 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
3e030 2a 20 57 61 69 74 69 6e 67 20 63 6f 6e 6e 65 63 * Waiting connec
3e040 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 tion */. void (
3e050 2a 78 4e 6f 74 69 66 79 29 28 76 6f 69 64 20 2a *xNotify)(void *
3e060 2a 61 70 41 72 67 2c 20 69 6e 74 20 6e 41 72 67 *apArg, int nArg
3e070 29 2c 20 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 ), /* Callbac
3e080 6b 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e k function to in
3e090 76 6f 6b 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a voke */. void *
3e0a0 70 4e 6f 74 69 66 79 41 72 67 20 20 20 20 20 20 pNotifyArg
3e0b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3e0c0 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e /* Argumen
3e0d0 74 20 74 6f 20 70 61 73 73 20 74 6f 20 78 4e 6f t to pass to xNo
3e0e0 74 69 66 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a tify */.);../*.*
3e0f0 2a 20 55 6e 64 6f 20 74 68 65 20 68 61 63 6b 20 * Undo the hack
3e100 74 68 61 74 20 63 6f 6e 76 65 72 74 73 20 66 6c that converts fl
3e110 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 74 79 70 oating point typ
3e120 65 73 20 74 6f 20 69 6e 74 65 67 65 72 20 66 6f es to integer fo
3e130 72 0a 2a 2a 20 62 75 69 6c 64 73 20 6f 6e 20 70 r.** builds on p
3e140 72 6f 63 65 73 73 6f 72 73 20 77 69 74 68 6f 75 rocessors withou
3e150 74 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 t floating point
3e160 20 73 75 70 70 6f 72 74 2e 0a 2a 2f 0a 23 69 66 support..*/.#if
3e170 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f def SQLITE_OMIT_
3e180 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 FLOATING_POINT.#
3e190 20 75 6e 64 65 66 20 64 6f 75 62 6c 65 0a 23 65 undef double.#e
3e1a0 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 5f 5f 63 ndif..#ifdef __c
3e1b0 70 6c 75 73 70 6c 75 73 0a 7d 20 20 2f 2a 20 45 plusplus.} /* E
3e1c0 6e 64 20 6f 66 20 74 68 65 20 27 65 78 74 65 72 nd of the 'exter
3e1d0 6e 20 22 43 22 27 20 62 6c 6f 63 6b 20 2a 2f 0a n "C"' block */.
3e1e0 23 65 6e 64 69 66 0a 23 65 6e 64 69 66 0a #endif.#endif.